fhg
Volume 7, Number 38 -- October 31, 2007

Use PHP to Bring i5/OS Resources to the Web

Published: October 31, 2007

by Erwin Earley

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 <"brConnection successful"; // Close the connection i5_close($conn); ?>

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


Sponsored By
PROFOUND LOGIC SOFTWARE

Give Modernization with RPGsp a try.

RPGsp offers more Modernization Options
and has greater success in the marketplace
than any other product.

It's the perfect fit for both large-scale and small modernization projects.

Take our demo and prove it to yourself.

www.RPGsp.com


Senior Technical Editor: Ted Holt
Technical Editors: Howard Arner, Joe Hertvik, Shannon O'Donnell, Kevin Vandever
Contributing Technical Editors: Joel Cochran, Wayne O. Evans, Raymond Everhart,
Bruce Guetzkow, Brian Kelly, Marc Logemann, David Morris
Publisher and Advertising Director: Jenny Thomas
Advertising Sales Representative: Kim Reed
Contact the Editors: To contact anyone on the IT Jungle Team
Go to our contacts page and send us a message.

Sponsored Links

SafeData:  The iSeries HA Solution that’s Guaranteed
COMMON:  Join us at the annual 2008 conference, March 30 - April 3, in Nashville, Tennessee
NowWhatJobs.net:  NowWhatJobs.net is the resource for job transitions after age 40


 

IT Jungle Store Top Book Picks

The System i RPG & RPG IV Tutorial and Lab Exercises: List Price, $59.95
The System i Pocket RPG & RPG IV Guide: List Price, $69.95
The iSeries Pocket Database Guide: List Price, $59.00
The iSeries Pocket Developers' Guide: List Price, $59.00
The iSeries Pocket SQL Guide: List Price, $59.00
The iSeries Pocket Query Guide: List Price, $49.00
The iSeries Pocket WebFacing Primer: List Price, $39.00
Migrating to WebSphere Express for iSeries: List Price, $49.00
iSeries Express Web Implementer's Guide: List Price, $59.00
Getting Started with WebSphere Development Studio for iSeries: List Price, $79.95
Getting Started With WebSphere Development Studio Client for iSeries: List Price, $89.00
Getting Started with WebSphere Express for iSeries: List Price, $49.00
WebFacing Application Design and Development Guide: List Price, $55.00
Can the AS/400 Survive IBM?: List Price, $49.00
The All-Everything Machine: List Price, $29.95
Chip Wars: List Price, $29.95


 
The Four Hundred
IBM's Math on User-Priced System i Versus Vintage Machines

Midrange Shops Get Disaster Recovery Services from IBM

Ask TPM: Two System i Questions, and Two Responses

As I See It: Survey Says . . .

The Linux Beacon
Egenera Breaks Blade Software Free from Hardware

Citrix Closes XenSource Deal, Does Deal with Dell and Xen Desktops

Sun Puts Intel Quad-Core Chips into Ultra Workstations

Midrange Shops Get Disaster Recovery Services from IBM

Four Hundred Stuff
Zend Plans Treats, Tricks for System i Programmers

Mantis Bug Tracker Ported to i5/OS

mrc Goes Web 2.0 with m-Power

IBM Updates Disk and Tape, Buys Storage Software Developer

Big Iron
IBM Hit by Financial Services Slowdown in Q3

Top Mainframe Stories From Around the Web

Chats, Webinars, Seminars, Shows, and Other Happenings

System i PTF Guide
October 27, 2007: Volume 9, Number 43

October 20, 2007: Volume 9, Number 42

October 13, 2007: Volume 9, Number 41

October 6, 2007: Volume 9, Number 40

September 29, 2007: Volume 9, Number 39

September 22, 2007: Volume 9, Number 38

The Windows Observer
Office Communication Server 2007 Launched by Microsoft

Will OCS 2007 Live Up to the Hype?

Zend Puts Out New Release of Commercial-Grade PHP

Growing Businesses, Upgrades Drive IT Hiring in Q4

The Unix Guardian
IBM's Power-Based Servers Save the Day in Q3

Sun Puts Intel Quad-Core Chips into Ultra Workstations

Intel Is Back on Track in Q3, AMD Is Fighting to Get There

Mad Dog 21/21: Symphony for the Devil

Four Hundred Monitor
Four Hundred Monitor's
Full iSeries Events Calendar

THIS ISSUE SPONSORED BY:

Profound Logic Software
Guild Companies
ARCAD Software


Printer Friendly Version


TABLE OF CONTENTS
Use PHP to Bring i5/OS Resources to the Web

Wrapping Free Form Text

Admin Alert: Limiting System i User Sign-ons the Smart Way

Four Hundred Guru

BACK ISSUES

From the IT Jungle Forums
Reallocate disk space from one lpar to another

how to retrieve a workstation ID

Finding *OUTFILE Template Files

i5/OS V5R4 Release Notes

MCH1202





 
Subscription Information:
You can unsubscribe, change your email address, or sign up for any of IT Jungle's free e-newsletters through our Web site at http://www.itjungle.com/sub/subscribe.html.

Copyright © 1996-2008 Guild Companies, Inc. All Rights Reserved.
Guild Companies, Inc., 50 Park Terrace East, Suite 8F, New York, NY 10034

Privacy Statement