Use PHP to Bring i5/OS Resources to the Web

This is our third article in the PHP in i5/OS series. In previous articles we have provided an overview of PHP on System i as well as the basic syntax of the language. This article provides an overview of the API toolkit, and a collection of Application Programming Interfaces (APIs) that facilitate PHP programs accessing and working with i5/OS objects.

Web Development and Deployment Stacks–LAMP

To begin our discussion let’s first look at the Web development and deployment stack that incorporation of PHP provides to i5/OS. In the past you have probably encountered the LAMP stack – a Web development/deployment stack based on the Linux operating system, Apache Web server, MySQL database engine, and the PHP (or Perl or Phython) scripting language. The following diagram provides a high-level architectural view of the LAMP stack:

Over the last several years, the LAMP stack has become a major development platform for the enterprise and is used by such companies as Amazon, Friendster, Google, and Yahoo. LAMP represents the open source software components used as a “toolkit” by Web developers for deploying robust Web content complete with data access and manipulation. System i customers have for a number of years been able to leverage the LAMP stack through the incorporation of Linux running in a Logical Partition (LPAR) on their System i systems.

Web Development and Deployment Stacks–iADP

The adoption of PHP in i5/OS provides a Web development/deployment stack similar to the LAMP stack. The iADP stack is a Web development/deployment stack based on the i5/OS operating system, Apache Web server (installed in the PASE environment as part of the Zend Core installation), the DB/2 database engine, and the PHP scripting language. The following diagram provides a high-level architectural view of the iADP stack:

NOTE: The next article in this series will take a look at yet another Web development/deployment stack–the iAMP stack–facilitated by the adoption of MySQL on the platform and used to leverage existing open community applications in i5/OS.

With the iADP stack, a System i customer can develop and deploy PHP based Web applications directly in i5/OS without the need to manage an additional Logical Partition and operating system. You will notice from the above diagram, that the PHP engine runs in the PASE environment. When Zend Core is installed, in addition to PHP and Apache being installed in the PASE environment, an additional program is installed in i5/OS (called i5_COMD) that listens for requests for i5/OS objects from the PHP engine and satisfies those requests. The following diagram provides an architectural view of this relationship:

The Zend Core API Toolkit

One of the key components of Zend Core is the API toolkit, a collection of APIs for working with i5/OS objects from PHP. There are a large number of APIs and the collection continues to grow over subsequent releases of Zend Core. The APIs can be broken down into a number of main categories:

• Connection management
• Command calls
• Program calls
• Data retrieval
• Native file access
• System values
• Data areas
• Print and working with spool files
• Job logs
• Active jobs
• Object list
• User space
• Data queue

The following sections will walk through some examples of different APIs calls to give you a sense for how these can be used to develop and deploy customized Web applications that leverage i5/OS resources. Before we begin, a quick disclaimer: These examples are intended to provide you with a sense of how PHP can be used. You are welcome to use these examples to get started with PHP on System i and learn what PHP and the System i can do for you. However, the code provided is not supported by the author, IBM, or IT Jungle. If you are going to use this code in a production environment you should ensure that you add more robust error handling and input validation. Additionally, you should ensure that you establish a secure i5/OS and PHP environment through proper use of authentication, authorization, and object-level security. With that disclaimer out of the way, let’s get started by looking at our first example.

Connection Management

Before any other API can be used, a connection to i5/OS must be established. The connection APIs will facilitate establishing this connection. The APIs in the connection category include:

• i5_connect: establishes a connection to i5/OS. Parameters include the system network address, user profile name and password. NOTE: The system name can only be localhost or 127.0.0.1. This is the API that will establish a connection to the I5_COMD job
• i5_CLOSE: closes an active connection
• i5_adopt_authority: Used to adopt other authorities while a PHP program is executing
• i5_error: retrieves data about an error
• i5_errno: retrieves the error number
• i5_errormsg: retrieves the error message

Let’s take a look at a code sample that uses some of the connection management APIs.

< form method="post" action="i5_connection.php">
User profile: < input type="text" name="uprf">


Password: < input type="password" name="pwd">
< input type="submit" value="Connect">
< /form>

The snippet of HTML above establishes a form that will collection user-input and pass it on to a PHP program. The form will look similar to the following:

The form method line establishes that this is an HTML form that will provide values through a post (represented as the _POST super-global variable to PHP), and that when the form is submitted by the user, the file “i5_connection.php” will be called. The User profile line establishes a field with the title of User profile and a text box whose user-entered value will be represented in the _POST super-global array as the key value “uprf”.

Similarly, the Password line establishes a field with the title of “Password” and a text box whose user-entered value will be represented in the _POST super-global array as the key value “pwd”; the difference being that the type of password will cause the value to be masked as it is typed by the user. The input type line establishes a user-selectable button on the form with the label “Connect” that will cause a submit action to take place. The submit action is what triggers the action identified back on the form method line, which passes control to the i5_connection.php file.

Now let’s take a look at the corresponding php code:

Error Number" .
		i5_errorno() . "
msg = ". i5_errormsg());
	}
	print 

The first thing to notice in this code snippet is the reference to the $_POST super-global variable. The values from the HTML form are accessed through the use of the associative keys into the _POST array and the values are assigned to the local variables $user and $pwd. The $conn = i5_connect line calls the i5_connect API to establish a connection to i5/OS. Notice that the value localhost is used for the system identifier and the user profile and password entered on the HTML form are used for the user credentials.

The result of the i5_connect call is a connection handle, which is returned to the $conn variable. The if(!$conn) line tests to see if a valid connection was returned. If explanation point before the variable inverses the tests, it means the value returned is invalid. If the test is successful (i.e., a valid connection handle was not returned), then the API die causes an error message to be output and the execution of the PHP code to terminate. Notice in the die call that there are additional APIs calls, specifically to the i5_errorno and i5_errormsg APIs to include the resulting error number and error message respectively in the message output by die. This is an example of being able to use APIs calls anywhere that a string or variable would be used–the return value from the API call being substituted for the actual call.

If the i5_connect call is successful then the print statement is executed and the string connection successful is output. Finally the i5_close API is called to close the connection. Notice that the i5_close API takes as its parameter the connection handle originally returned by the i5_connect call. Also notice that the output statements include HTML tags. Remember from our earlier articles that output from PHP is inserted into the HTML stream and processed as HTML. The last comment on this code snippet is that in a real-use of these connection APIs there would obviously be other API calls and processing between the i5_connect and i5_close APIs.

Command Call

The command call APIs allow a PHP program to make a call to a CL command and retrieve output from a running command. The following HTML and PHP code snippets provide an example where a user can either send or receive a message. First, let’s look at the HTML:

Send a message (SNDMSG)

< form method="post" action="i5_command.php">
	< input type="hidden" name="task" value="send">
	Message: < input type="text" name="message">
	< input type="reset">
	< input type="submit" value="Send message">
< /form>

Receive a message (RCVMSG)

< form method="post" action="i5_command.php">
	< input type="hidden" name="task" value="get">
	< input type="submit" value="Receive message">
< /form>

The result of the above HTML code will generate an HTML form similar to the following:

Items to make note of in this HTML code are:

• There are two form method lines establishing two different actions to take based on which submit button is selected. However, note that the action for both is the same (i.e., call i5_command.php). The PHP code will differentiate which submit button was selected through the task element in the _POST array.
• Each form method has an input type of “hidden” that establishes an element in the _POST array that will contain a value (from the input type line) but will not be displayed on the form. The value is specified through the value parameter on the input type line.
• The input type of reset causes a reset button to be displayed, selection of which resets the values in the form to their default (in this case blank) values.

Now let’s take a look at the corresponding php code:

Note: The code in the above graphic is available for download here.

For purposes of explanation the code above can be split into four main functional areas:

1. The first block of statements uses the i5_connect API to establish a connection to i5/OS. Recall from our earlier discussion of the i5_connect API that the first parameter indicates the system name (i5/OS) and must be either localhost or 127.0.0.1. The second parameter is the user profile and the third is the password. This example shows the password masked out; in actual practice the password would either be provided in this call as a string or as a variable either in this code or a separate include file.
2. The second block of statements tests the task element of the _POST array to see if the user selected the Send Message button on the HTML form. If that button was selected then the i5_command API is called to invoke the send message (SNDMSG) command using the string entered in the message field of the HTML form.
3. The third block of statements tests the task element of the _POST array to see if the user selected the “Receive Message” button on the HTML form. If that button was selected then the i5_command API is called to invoke the receive message (RCVMSG) command to retrieve and output the top message from the PHPUSER message queue.
4. The final statement uses the i5_close API to close the connection to i5/OS.

This article has presented two examples of APIs included in Zend Core’s API Toolkit. Our next article will complete this discussion by looking at APIs for record-level access, program call, data areas, and system values. Once we have completed our discussion of the API toolkit, we will then take a look at the DB2 extensions in the PHP language that Zend Core supports.

Erwin Earley is an advisory software engineer in the IBM lab located in Rochester, Minnesota, and heads up the Open Source Technologies Center of Competency for System i within the System i Technology Center. At that center, he provides education and enablement services for open source related technologies on System i including Linux , MySQL, and Zend’s PHP. Earley currently holds certifications from Red Hat as well as the Linux Professional Institute and is a candidate for certification with Zend’s PHP.

RELATED STORIES

PHP: An Easy Yet Powerful Language Syntax

PHP on i5/OS: A Whole New Stack

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot