Running Caucho’s Quercus PHP Java interpreter on WebSphere Application Server for z/OS with DB2 UDB for z/OS

An open-source PHP solution for System z

PHP is one of the most common Web scripting languages. This article shows the quickest way to use PHP with WebSphere® for z/OS, in just a few simple steps. You can even run it on the IBM System z Application Assist Processor (zAAP) with no additional software costs, and connect it to DB2® UDB for z/OS.

Peter Bruns (peter_bruns@de.ibm.com ), Certified IT Specialist , IBM

author photoPeter Bruns is Certified IT specialist in the German IBM Sales and Technology Group. He is working with customers as a performance and sizing specialist, with software development experience in customer and IBM teams. Peter is co-author of the Redbook Data Warehousing with DB2 for OS/390, written in 1997. He also supports the Large System Performance Reference program.



10 September 2008

Implementing PHP on z/OS - not an easy task ?

Did you know that many Web sites are written in a very common language callend PHP? However, when you view the source code of the Web page in your browser, you cannot see the PHP code because it is interpreted on the Web server and the resulting HTML code is sent back to your browser. You can use PHP for just about every programming task, and also for accessing databases, files, and other resources.

For PHP interpretation, the Web server works with a PHP engine that either resides inside the Web server or outside of it as a separate program. When outside the Web server, the server calls a set of DLLs, interpreting the PHP code and sending the results back to the Web server for further processing.

I wanted to get PHP running on WebSphere Application Server for z/OS, and if possible, connecting to DB2 UDB for z/OS for several reasons:

  • Every platform has PHP on it
  • It is a very common language that many developers are skilled in
  • You can buy PHP journals at retail stores
  • Most importantly, if your data is already on z/OS, for example on DB2 UDB, and you want to use PHP, there is no better performance than running PHP on that same platform.

When I was looking how to get PHP to run under z/OS, it seemed a bit complex. I started by installing IBM Ported Tools for z/OS, which requires SMP/E. However I must have done something wrong when applying the Ported Tools code, so I dropped this first approach -- even if I could install the Ported Tools, I would still have to wire it to WebSphere Application Server.

I thought it would be nice to get it running as easy as on my PC… just install PHP, then install WebSphere Application Server Community Edition and connect it to PHP. Ok: I tried it, and my second approach worked: I started a PHP Hello World program and was able to connect it to DB2 UDB for Windows and to Derby databases. Wow, quite easy right ? Next question was , where is WebSphere Application Server Community Edition for z/OS? It's not available yet, so I couldn’t get it running on z/OS.

Then, a colleague of mine, Kevin Keller, suggested that I try installing a PHP Java interpreter on WebSphere Application Server for z/OS. He recommended Quercus , Caucho Technology's 100% Java implementation of PHP 5 released under the Open Source GPL license. Seems there's no easier way. So let's do it. But will it work on WebSphere Application Server ? And can I connect it to DB2 UDB for z/OS ? We'll see.

I downloaded the quercus-3.1.6.war. As it is a WAR file, it should work when deploying it to WebSphere Application Server, right ? Guess what: it failed. I was not able to deploy it. I So I thought let's do it really on a solid basis, using the Rational Application Developer tool.

Finally I got it working, and even connected to DB2 UDB for z/OS. This article takes you step by step through how I did it.


Importing the Quercus WAR file and creating an EAR project

I used Rational Application Developer version 6.0.1, build ID 20050725_1800. However, these steps should also work on more recent versions of Application Developer and its successor tools.

  1. Download the quercus-3.1.6.war file from The Quercus site to a subdirectory on your PC
  2. Start Application Developer and open the Project Explorer view
  3. Import the quercus-3.1.6.war file from the subdirectory to a new enterprise application project EAR file named quercus-3_1_6EAR.
    Note: I created some of the screenshots when I had the WAR file already imported, so RAD required different names. If you see 3_1_61 in some screenshots, don't worry: it means 3_1_6.

    Figure 1 shows the import window.
    Figure 1. Importing the quercus-3.1.6.war to a new EAR project
    Importing the quercus-3.1.6.war to a new EAR project
  4. Click Finish. This step creates a new EAR project called quercus-3_1_6EAR, containing the dynamic Web project quercus-3_1_6. Figure 2 shows the new EAR file after importing the WAR file.
    Figure 2. Exploring the quercus-3_1_6EAR enterprise application
    Exploring the quercus-3_1_6EAR enterprise application
  5. Figure 3 shows the expanded WAR file.
    Figure 3. Exploring the quercus-3_1_6 dynamic Web application
    Exploring the quercus-3_1_6 dynamic Web application

Adapting the web.xml file

To access DB2, we add a data source reference to the Web implementation descriptor file web.xml. It is a pointer to a JNDI definition. This JNDI definition is created on the WebSphere Application Server administration console and describes a path to a relational database. As we will connect to an existing database with JNDI name jdbc/XWikiDS, we will use jdbc/MyWikiDataSource as our reference name.

  1. Double-click the web.xml file, which opens it for editing.
  2. Select the Reference pane and select Add - Resource reference.
  3. For Name, enter jdbc/MyWikiDataSource.
  4. For Type, select javax.sql.DataSource.
  5. For Authentication, select Container.
  6. For Sharing scope, select Shareable.
  7. Click Finish. This step adds the data source reference to web.xml. In addition, it creates a binding file that contains the relation between the data source reference and the data source JNDI name.
  8. Figure 4 shows the reference pane after creating the data source reference. On the JAAS Logon configuration, select Use Default Method and add following alias name: w1node1/xwikids. We will also define this alias on the WebSphere Application Server administrative console for the JNDI data source and describe the authentication method for it.
    Figure 4. A JNDI data source reference has been added to web.xml
    A JNDI data source reference has been added to web.xml

    Listing 1 shows the binding file in edit mode.

    Listing 1. The JNDI data source reference bindings file
    <?xml version="1.0" encoding="UTF-8"?>
    <webappbnd:WebAppBinding xmi:version="2.0" 
        xmlns:xmi="http://www.omg.org/XMI" xmlns:webappbnd="webappbnd.xmi" 
        xmi:id="WebAppBinding_1213799890099">
      <webapp href="WEB-INF/web.xml#WebApp_1213799890099"/>
      <resRefBindings xmi:id="ResourceRefBinding_1213799890109" 
          jndiName="jdbc/XWikiDS" 
          loginConfigurationName="DefaultPrincipalMapping">
        <bindingResourceRef 
           href="WEB-INF/web.xml#ResourceRef_1213799890109"/>
        <properties xmi:id="Property_1213873979842" 
            name="com.ibm.mapping.authDataAlias" 
            value="w1node1/xwikids" 
            description="container-managed auth alias from resource-ref"/>
      </resRefBindings>
    </webappbnd:WebAppBinding>
  9. Now, if we test this configuration on WebSphere Application Server and try connecting to our XWikiDS database, we would get the following error message: Attempted to use a 5.0 DataSource outside of a 2.3 servlet.
    This means that we need to manually adapt the web.xml file to get it running. So open web.xml, select the source pane, make the 2.2 header a comment for future reference, and add a 2.3 header. After editing, the source code should look like Listing 2:
    Listing 2. The adapted web.xml header source code
    <?xml version="1.0" encoding="utf-8"?>
    <!--
    <!DOCTYPE web-app
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
        "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
    -->
    <!DOCTYPE web-app
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
        "http://java.sun.com/dtd/web-app_2_3.dtd">
    <web-app>
      <description>Caucho Technology's PHP Implementation</description>
      <servlet>
        <servlet-name>Quercus Servlet</servlet-name>
        <servlet-class>com.caucho.quercus.servlet.QuercusServlet
        </servlet-class>
    
        <!-- Specifies the encoding Quercus should use 
             to read in PHP scripts.
             Uncomment this if you're having "invalid utf-8" errors.
        -->
        <!--
        <init-param>
          <param-name>script-encoding</param-name>
          <param-value>ISO-8859-1</param-value>
        </init-param>
        -->
    
        <!-- Tells Quercus to use the following JDBC database 
             and to ignore the
             arguments of mysql_connect().
        -->
        <!--
        <init-param>
          <param-name>database</param-name>
          <param-value>jdbc/test</param-value>
        </init-param>
        -->
    
        <!--
        <init-param>
          <param-name>php-ini-file</param-name>
          <param-value>WEB-INF/php.ini</param-value>
        </init-param>
        -->
      </servlet>
    
      <servlet-mapping>
        <servlet-name>Quercus Servlet</servlet-name>
        <url-pattern>*.php</url-pattern>
      </servlet-mapping>
    
      <welcome-file-list>
        <welcome-file>index.php</welcome-file>
      </welcome-file-list>
      
      <resource-ref id="ResourceRef_1213799890109">
      	<description>datasource for access 
                       to external DB2 database XWikiDS</description>
      	<res-ref-name>jdbc/MyWikiDataSource</res-ref-name>
      	<res-type>javax.sql.DataSource</res-type>
      	<res-auth>CONTAINER</res-auth>
      </resource-ref>
    
    <!--
        <init-param>
          <param-name>database</param-name>
          <param-value>jdbc/XWikiDS</param-value>
        </init-param>
    -->
    
    </web-app>

Adding some PHP Web pages

We are almost done editing the EAR file. Next we need to add some Web pages that use the quercus PHP Java interpreter classes inside the Quercus war file when deployed and running on WebSphere Application Server.

Since we don't want a static application, we want to let the user input the number of rows to read from one of our XWikiDS database tables, so we are able to communicate with the application. We will ask for the number of rows on an input html page and then use it in the PHP page and the SQL database access. To keep it simple for now, we will just use SQL SELECT statements.

Quercus provides database-specific access methods for a couple of common databases. DB2 is not yet part of this set of databases. However PDO (Portable Database Objects) is a generic method of database access that also works with DB2 (for more information, see the Portable Database Objects page). We will use it for accessing DB2 UDB for z/OS.

We will access the XWIKISTRINGS table with its three columns XWS_ID, XWS_NAME and XWS_VALUE.

Listing 3 shows the source code of the parameter input page (phpinfo2.html). It requests the number of rows to return.

Listing 3. The input html page
<html>
<head>
<title>phpinfo2_action.php Input Form</title>
</head>
<body>
<form action="phpinfo2_action.php" method="post">
We are feeding PHP with input values.<br>
How many rows to fetch from XWIKISTRINGS table ?:
<input type="text" name="rows" size="10"><br>
Action: <br>
<input type="submit" value="Submit">
<input type="reset" value="Clear">
</form>
</body>
</html>

Listing 4 show the source code of our PHP page. First, it accepts the number of rows as the input parameter. Then it requests that number of rows from our relational database table and creates the HTML code to list the three requested rows. Finally, it calls the phpinfo method, which provides useful information about this specific PHP implementation.

Listing 4. The PHP action page
<html><head><title>phpinfo2.html Result</title></head><body>

<?php
  function quercus_test()  {
    return function_exists("quercus_version"); 
  }
?>

<div class="message" id="success">
<img src="images/dragonfly-tiny.png">
  Getting quercus to run on z/OS and connect to DB2 UDB for z/OS.
  Congratulations!  Quercus&#153; 
  <?php if (quercus_test()) echo quercus_version(); ?>
  seems working fine.
</div>

<?php
printf("Hello PHP community.<br>\n");
if( is_numeric($rows) ) { echo("No of rows entered, is valid.<br>"); 
} else                  { echo("Invalid entry - please retry.<br>"); 
}
$value = 5;  printf("Some calculation: start value = %d<br>\n",$value);
$value += 3;
          printf("increased value by 3, value is now %d<br>\n",$value);

printf("Under z/OS WAS6: 
        Connecting to external DB2 database named XWIKI ...<br>\n");
$pdo = new PDO("java:comp/env/jdbc/MyWikiDataSource");
printf("... done with connecting (?).<br>\n");
printf("Selecting data from table PJ80063.XWIKISTRINGS ...<br>\n");
printf("There are 169 rows ... now we select just the 1st ");
echo $rows; printf(" rows ...<br>\n");
$stmt = $pdo->query("SELECT * FROM PJ80063.XWIKISTRINGS") or die();
echo "<table>";
$rowno = 0;
echo "<tr><td>rowno<td>XWS_ID<td>XWS_NAME<td>XWS_VALUE</tr>\n";
while (($row = $stmt->fetch(PDO::FETCH_OBJ)) && $rowno<$rows) {
  /* $rowno<10 */
     $rowno += 1;
  echo "<tr><td>$rowno<td>$row->XWS_ID<td>$row->XWS_NAME
            <td>$row->XWS_VALUE</tr>\n";
}
echo "</table>";
printf("... done with selecting data
            from z/OS WAS6 external DB2 database named XWIKI.<br>\n");
printf("... Calling phpinfo() now ...<br>\n");
phpinfo();
printf("... done calling phpinfo().<br>\n");
?>

</body></html>

Exporting the EAR file

The edited EAR file is now ready for exporting and deploying on WebSphere Application Server.

  1. Right-click quercus-3_1_6EAR, and select Export - EAR file.
  2. For the destination, enter a subdirectory and file name of your choice. Make a note of the subdirectory and the file name for future use in the deployment process. Figure 5 shows the final export dialog, before we click Finish to invocate the export process.
    Figure 5. Exporting the EAR file
    Exporting the EAR file

Defining the data source definitions for WebSphere Application Server

Remember we have defined a data source reference (jdbc/MyWikiDataSource) and a JAAS authentication entry (w1node1/xwikids)for a DB2 JNDI data source (jdbc/XWikiDS) on our web.xml file. These entries are of course samples. You could use your own definitions that are available on your WebSphere Application Server installation. Next we check our definitions on the WebSphere Application Server administrative console:

  1. Login to the WebSphere Application Server administrative console.
  2. Select Resources - JDBC - Data Sources
  3. Select the XWikiDS data source, check if the JNDI name is the same as in our web.xml file
  4. Click JAAS - J2C authentication data. If necessary, select w1node1/xwikids and check that the user ID and password are correct. They are used to access DB2 UDB for z/OS
  5. Check if the authentication entry is the same as defined in our web.xml file

Figure 6 shows the data source definition, and Figure 7 the JAAS authentication entry:

Figure 6. The data source to access the XWikiDS database
The data source to access the XWikiDS database
Figure 7. The JAAS - J2C authentication entry
The JAAS - J2C authentication entry

Deploying the EAR file on WebSphere Application Server

We are now ready to deploy the EAR file to WebSphere Application Server.

  1. Login to the WebSphere Application Server administrative console.
  2. Select Applications - Install New application.
  3. Select the Local file system radio button, and enter the path and filename of the EAR file.
  4. Click Next (see Figure 8).
    Figure 8. Selecting the local EAR file for deployment
    Selecting the local EAR file for deployment
  5. Select Precompile JSPs for better performance, as Figure 9 shows. Since we do not have JSPs on our EAR file, it is not important here. However, it could be important for your application. Click Next.
    Figure 9. Selecting Precompile JSPs
    Selecting Precompile JSPs
  6. In this step, we map the EAR file modules to the server components. Select the Web server instance of your administration cell. We currently have just one single instance, as Figure 10 shows. If your installation has multiple servers, you could deploy it on all servers at once. That's a good option on WebSphere Application Server for z/OS. Click Next.
    Figure 10. Map the war module to the web application server
    Map the war module to the web application server
  7. Now we map the Web modules to virtual hosts. We select default_host as our virtual host here, as Figure 11 shows:
    Figure 11. Map the war module to virtual hosts
    Map the war module to virtual hosts
  8. Figure 12 shows a summary with the selected options. Click Finish to start the deployment process.
    Figure 12. Checking the options and starting the deployment process
    Checking the options and starting the deployment process
  9. Figure 13 shows the deployment messages that indicate a successful installation.
    Figure 13. Successful deployment of the adapted quercus ear file
    Successful deployment of the adapted quercus ear file
  10. Save the updated WebSphere Application Server configuration and then go to the Enterprise Application panel and start the application. Figures 14 and 15 illustrate these two steps
    Figure 14. Saving the updated WebSphere Application Server configuration
    Saving the updated WebSphere Application Server configuration
    Figure 15. Starting the quercus PHP java interpreter application
    Starting the quercus PHP java interpreter application
    .

Testing the WebSphere Application Server PHP application and accessing DB2

Now it's time to test our new PHP application. We open a browser and enter following URL to access the HTML input page for entering the number of rows:

http://<your_webserver_name>:9148/quercus-3_1_6/phpinfo2.html

Figure 16 shows the HTML page.. Port 9148 is the port I used on my tests, but please adapt it to your environment.

Figure 16. Entering input values for PHP
Entering input values for PHP

Click Submit to finally see the resulting three rows from the DB2 UDB for z/OS table with some additional information, as Figure 17 shows:.

Figure 17. Enjoying the result page
Enjoying the result page

What's next?

We can now start using PHP on WebSphere for z/OS, using the steps described above. We can also connect PHP to DB2 UDB for z/OS.

That doesn’t mean this is the best or the only method of getting PHP to work on WebSphere Application Server for z/OS. It's just a good starting point and quite easy to implement. Also, as it is a 100% pure Java implementation, you can use new technologies such as the zAAP processor, saving additional hardware and software costs. In addition, if there is already WebSphere Application Server active, you don’t need to set up another Web server.

The Rational Application Developer version I've been using does not yet provide a means for developing PHP pages. One of my next steps will be to check how to enhance Application Developer for developing PHP pages and whole PHP applications, but this is not in the scope of this article.

This article just describes how we can enrich available J2EE applications with PHP pages that could have been developed with other tools. Also, you can use PHP for application pages as well as presentation pages. So we have some good options for application development. Our young developers, familiar with PHP from university or from previous experiences, can start working with WebSphere Application Server and DB2 UDB for z/OS immediately. What do you think?

Acknowledgments

I want to express my thanks to Kevin Keller, IBM Germany, who had the idea of using Caucho Quercus for PHP on WebSphere Application Server. Also, thanks to Holger Wunderlich and Kevin Keller from IBM Germany for technically reviewing this article.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Information Management, Open source
ArticleID=336650
ArticleTitle=Running Caucho’s Quercus PHP Java interpreter on WebSphere Application Server for z/OS with DB2 UDB for z/OS
publish-date=09102008