Bringing i5/OS Resources to the Web

This is the fourth article in a PHP on i5/OS series and it continues our discussion of the API toolkit included with the Zend Core product. In my previous article Use PHP to Bring i5/OS Resources to the Web, I explained that the API toolkit is a collection of APIs for accessing i5/OS resources from PHP applications. The Zend Core product splits functions for accessing i5/OS resources into two broad categories: a collection of functions for accessing db2 resources, and a collection of functions for accessing all other i5/OS resources. The following diagram provides an overview of the structure of those i5/OS resource functions:

Observe in the above diagram that the functions in the i5 Toolkit allow for accessing native i5/OS resources only on the local system (i.e., resources in the same i5/OS partition where Zend Core is installed), while the db2 functions allow for accessing of db2 related resources (via SQL support) on the local as well as remote systems.

The db2 related functions are an extension to the PHP language and the function names all begin with the characters “db2_”. The db2 functions will be discussed in my next article. The toolkit functions are contained in the API toolkit and begin with the characters “i5_”. This article completes our discussion of the API toolkit functions.

Record-Level Access

The API toolkit includes functions for accessing records from physical files. Functions in this category include the following:

• i5_open: This function is used to open a physical file. The parameters for this function include the library/file to open as well as the open mode.
• i5_list_fields: This function is used to retrieve the list of field-names from an opened file.
• i5_fetch_row: This function is used to retrieve records from the opened file.

Let’s take a look at a code snippet that uses these record-level access functions.

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

A couple of general notes for this code snippet are needed before we look into its specific aspects. To begin with this is not a complete code sample–the complete code would include the PHP tags and the function calls to connect to i5/OS. Additionally, this code would have been invoked from an HTML form that would have been used to supply the file and library name. Now, let’s dive deeper into aspects of this code sample:

• The first block of code simply assigns values from an HTML form to local variables in the PHP code.
• The second block of code uses the “i5_open function” call to open the physical file. The call returns a file-handle that in this case is stored in the “$file” variable. Additionally, the call takes as a parameter the open mode, which in this case is “read” (as represented by the constant “I5_OPEN_READ”). Note that a test is made to ensure that a valid file handle was returned. If a valid file handle was not returned then the execution of the PHP code terminates.
• The third block of code retrieves the list of fields from the file and prints out the HTML representing a table with a header line of the field names. The “i5_list_fields” call is used to retrieve a list of field names from the file and store them in an array variable called “$fields. ” Note that the “i5_list_fields” function call takes as an argument the file handle returned from the previous call to the “i5_open” function. Once the field names have been retrieved, the PHP tags for printing a table border are output.
• The fourth block of code uses a “foreach” loop to step through the array of field names printing each one as a table header. Once the “foreach” loop is completed the HTML tag to complete the table record (in this case the list of field names) is output.
• The fifth block of code uses the “i5_fetch_row” function to retrieve records from the file. The call to “i5_fetch_row” takes two arguments: the file handle returned from the “i5_open” function, and an indication of which record to retrieve. Notice that the first call to “i5_fetch_row” uses the constant “I5_READ_FIRST” to retrieve the first record from the file. The “while” loop tests the return value from “i5_fetch_row” and if a valid record has been returned a subsequent “foreach” loop is used to parse through the array of fields from the retrieved record and outputs the HTML to print the field value as a table data item. The last statement of the “while” loop is another call to the “i5_fetch_row” function to retrieve the next record from the file.
• The sixth and final block of code is executed once all of the records have been processed by the “while” loop. It simply outputs the HTML tag to close the table.

Following is an example of the output that can be generated by the above code:

Program Call

PHP programs in i5/OS are able to invoke programs in the Integrated Language Environment (ILE), send parameters to those programs, and get results from those programs. The following functions are included in the Program Call group of APIs:

• i5_program_prepare: This function calls opens the program to be run. In one way this could be thought of as establishing a communication channel to the program.
• i5_program_call: This function passes arguments to the program that was opened with the “i5_program_prepare” function, causes the program to be executed, and obtains the output values form the program.
• i5_program_close. This function closes the connection to the prepared program.

For this example we need to look at the program to be called as well the PHP code. Let’s first take a look at the CL program to be called:

PGM		PARM(&SOMESTRING &SOMENUM)
DCL		VAR(&SOMESTRING) TYPE(*CHAR) LEN(10)
DCL		VAR(&SOMENUM) TYPE(DEC) LEN(15 5)
CHGVAR	VAR(&SOMESTRING) VALUE(%SST(&SOMESTRING 1 3))
CHGVAR	VAR(&SOMENUM) VALUE(&SOMENUM + 1)
ENDPGM

As you can see the program takes two arguments: a string (referred to as SOMESTRING), and a number (referred to as SOMENUM). The program will return the first three characters of the input string and the number that was input incremented by one. Now let’s take a look at the PHP code:

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

Like our previous example, this is an incomplete PHP code sample, as it is missing items such as the PHP tags. Additionally the code is making use of form values that would have been supplied by a corresponding HTML form. Now let’s look deeper into this code:

• The first block of code defines a two dimensional array (called “$description”) that is used to describe the input and output parameters to the program call. The simplest way to understand this definition maybe to take a look at what the “print_r()” function would show for the definition (see code below). You can think of the array that is passed to the “i5_program_prepare” function as a sandbox of sorts that is used by the PHP code to supply the values to the program being called and is used by the program being called to retrieve pointers to those values.

Array
(
    [0] => Array
        (
            [name] => SOMESTRING
            [IO] => I5_INOUT
            [Type] => I5_TYPE_CHAR
            [Length] => 10
        )

    [1] => Array
        (
            [name] => SOMENUM
            [IO] => I5_INOUT
            [Type] => i5_TYPE_PACKED
            [Length] => 15.5
        )

)

• The second block of code uses the “i5_program_prepare()” function to establish the program to be called and the array that describes the input and output parameters for the program call.
• The third block of code defines the “$parmIn” and “$parmOut” variables as arrays that will be used to provide the input values to the program as well as the output values expected from the program call. This block of code needs to be looked at in conjunction with the “i5_program_prepare” call earlier in the code. Notice that these array definitions make use of associative keys, which refer back to the names provided in the “i5_program_prepare” parameter. As an example, notice that both the “$parmIn” and “$parmOut” definitions have an associative key named “SOMESTRING”. If you look back at the “$description” definition, you’ll notice that one of the arrays has an associative element called “SOMESTRING”. The “SOMESTRING” in the “$description” array describes the format of the “SOMESTRING” parameter to the program (as provided in the “i5_program_prepare()” call. The “SOMESTRING” in the “$parmIn” array provides the actual parameter value that will be mapped into the program call. The following diagram attempts to show the relationship between the array of parameter descriptions provided in the “i5_program_prepare()” function and the corresponding values provided in “the i5_program_call()” function:

• The fourth block of code performs the actual program call (via the “i5_program_call()” function and outputs the values returned from the call.
• The fifth block of code uses the “i5_program_close()” function to close the handle to the program that was established by the earlier call to the “i5_program_prepare()” function.

Working with Data Areas

Let’s take a look at one more code sample for the i5 toolkit APIs. This example will show how you can work with data areas from PHP programs. We’ll start with a code sample:

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

• The first block of code uses form values from an associated HTML form to build variables in the PHP program that will be used by the subsequent function calls. The “$inputstring” variable will be set to the values entered for the first and last name on the HTML form in single quotes (i.e., ‘Erwin Earley’). The assignment of the “$start” and “$length” variables is interesting in that it uses the “intval()” PHP construct. Values from HTML forms are provided as strings to the PHP program. If you want the value to be treated as something other then a string (in this case an integer) then you will need to cast its variable type (which is what the “intval()” construct will do).
• The second block of code will call the “i5_data_area_create()” function to create a data area called “DATAAREA” in the “EEARLEY” library with a length of 256 characters. Notice that in this code we have used a different coding style in that we are calling a function directly in an “if” statement and testing its return value. This is a perfectly legitimate way to code within PHP.
• In the third block of code, if the create of the data area was successful, then the “i5_data_write()” function will be called to write up to 50 characters of data into the data area starting at the first position. The value to be written into the data area is the quoted first and last names entered on the HTML form.
• The fourth block of code shows that if the data area write was successful then the “i5_data_area_read()” function will be called to read the number of characters from the data area indicated on the HTML form at the starting position indicated on the HTML form.
• In the fifth block, we see that if the data area write was not successful then we would have dropped down to this section of code (from section 3) and an error will be output indicating that the data area write failed. The “var_dump()” language construct is used to output both the value and type of the return value from the “i5_error()” function.
• If the data area create was not successful then we would have dropped down to this sixth section of code (from section 2) and an error will be output indicating that the data area create failed. Again the “var_dump()” language construct is used to output both the value and type of the return value from the “i5_error()” function.
• In the final block, the “i5_data_area_delete” function is used to delete the data area called “DATAAREA” in the library “EEARLEY”.

Conclusion

I hope you have gained some insight and benefit from this look into the functions and capabilities provided by the i5 API toolkit that is provided with the Zend Core product. The next article in this series will take a look at the db2 extensions that Zend has provided for the PHP language.

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

Use PHP to Bring i5/OS Resources to the Web

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