Developing and deploying a dynamic scripting application

You create an OSGi bundle, with web support, and an enterprise bundle archive (EBA) on your workstation. You then deploy the EBA into a CICS® Liberty JVM server. You can create and edit PHP files in the WebContent of the OSGi bundle, or import existing PHP files into it.

Before you begin

Before you can develop and deploy a dynamic scripting application, the following conditions must be satisfied:
  • The CICS TS Feature Pack for Dynamic Scripting V2.0 z/OS® components are installed and customized.
  • The "CICS TS V5.4 with Liberty and PHP" target platform definition is available in the CICS Explorer® SDK.
  • You understand how to create and deploy bundles in CICS.
  • The CICS Explorer SDK is started and the following connections are established:
    • A CICS Management Interface connection to the CICSPlex® in which your target CICS region is defined.
    • A z/OS FTP connection to the appropriate z/OS system, with sufficient access authority.

For more information about OSGi and how it is implemented in CICS, see The OSGi Service Platform. For more information about packaging applications and deploying them in a JVM server, see the CICS Java Developer Guide in the CICS Explorer SDK help.

To gain experience in developing and deploying dynamic scripting applications, you can review, copy, and modify the contents of the artifacts that are delivered with the example application. For more information about the example application, see Verifying the installation is successful.

Procedure

  1. In the CICS Explorer SDK, open the Java™ perspective.
  2. Ensure the target platform is available. For more information, see Making the CICS TS Feature Pack for Dynamic Scripting V2.0 target platform available.
  3. Create an OSGi bundle, with web support, by using the New OSGi Bundle Project Include wizard:
    1. In the CICS Explorer SDK menu bar, click File > New > Other. The New wizard starts.
    2. In the "Select a wizard" window, expand CICS Resources, select OSGi Bundle Project Include, then click Next. The OSGi Bundle Project Include window opens.
    3. In the OSGi Bundle Project Include window, select the Add Web support check box and select Web 3.0 from the list. Complete other fields as appropriate and click Next. Web 3.0 dependency is added to the bundle, and the Java window opens.
    4. In the Java window, click Next. The Web Module window opens.
    5. In the Web Module window, select Generate web.xml deployment descriptor. Update the Context root and Content directory fields if you want to use non-default values. Click Next. The OSGi Bundle window opens.
    6. In the OSGi Bundle window select Generate an activator, a Java class that controls the life cycle of the bundle. Update the Symbolic name (ID) and Version fields if you want to use non-default values. Click Finish.
    The OSGi bundle is created and is displayed in the Package Explorer window.
  4. In the generated OSGi bundle, append the following code to the Import-Package: in the WebContent/META-INF/MANIFEST.MF file:
    com.ibm.cics.php;version="[1.0.0,2.0.0)",
  5. Modify the generated Activator Java class. The Activator Java class is in the path Java Resources/src/projectname, where projectname is the name of the project you supplied in step 3.c. The modifications that are needed are as follows:
    1. Add the following import declaration to the generated Activator Java class:
      import com.ibm.cics.php.CICSPHPInitialiser;
    2. Add the following statement to the start(BundleContext context) function of the generated Activator Java class:
      CICSPHPInitialiser.getInstance().activate(context);
      CICSPHPInitialiser is used to extract the bundle entries into a cache directory and register this cache directory when the web OSGi bundle is activated, so that the PHPServlet knows where to pick up the bundle entries. CICSPHPInitialiser also cleans up the cache directory when the web OSGi bundle stops. If you miss this step, message CWWDS0021E is issued.
    The following is an example of an Activator that is provided in the Dynamic Scripting feature pack plug-in:
    package com.ibm.cics.server.examples.php.web;
    
    import org.osgi.framework.BundleActivator;
    import org.osgi.framework.BundleContext;
    import com.ibm.cics.php.CICSPHPInitialiser;
    
    
    public class Activator implements BundleActivator {
    
        /*
         * (non-Javadoc)
         * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
         */
        public void start(BundleContext context) throws Exception {
    	 CICSPHPInitialiser.getInstance().activate(context);
        }
    
        /*
         * (non-Javadoc)
         * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
         */
        public void stop(BundleContext context) throws Exception {
        }
    
    }
  6. Add the following code to the WEB-INF/web.xml file:
    <servlet-mapping>
        <servlet-name>PHPServlet</servlet-name>
        <url-pattern>*.php</url-pattern>
    </servlet-mapping>
    <servlet>
        <servlet-name>PHPServlet</servlet-name>
        <servlet-class>com.ibm.cics.php.PHPServlet</servlet-class>
        <multipart-config/>
    </servlet>
    This code enables the web OSGi bundle to handle PHP requests.
  7. Either create and edit .php files in the WebContent directory of your OSGi bundle, or import .php files into the WebContent, by using the Import wizard. To import files by using the import wizard, click File > Import > General > File system > Next, then specify the source and destination locations and click Finish.
    Note:
    • If you edit .php files in the Eclipse PHP editor, it does not detect errors in JCICS or Java calls.
    • The PHP support in CICS TS Feature Pack for Dynamic Scripting V2.0 can differ from the support that is provided by php.net. For more information, see PHP Language support and Restrictions.
  8. Optional: Provide your own php.ini file in the root of the WebContent. If you do not provide a php.ini file, dynamic scripting uses a default version.
  9. Create a user EBA file by using the New OSGi Application Project wizard:
    1. In the CICS Explorer SDK menu bar, click File > New > Other.
    2. In the "Select a wizard"window, expand CICS Resources, select OSGi Application Project Include, then click Next. The OSGi Application Project Include window opens.
    3. Provide a name for the project in the Project name field and click Next. The Contained OSGi Bundles and Composite Bundles window opens.
    4. In the Contained Bundles and Composite Bundles (Application-Content) list, select the check box for the OSGi bundle that you created in step 3, then click Finish. The OSGi Application Project (user EBA) is created and is displayed in the Package Explorer window.
  10. Optional: Use the Liberty profile deployment model to export and deploy your EBA file to the Dynamic Scripting JVM server. Liberty supports the dropin deployment method, so you can deploy a web application as a drop-in directly to a Liberty JVM server without creating a CICS bundle project. For more information, see Deploying Java EE applications directly to a Liberty JVM server. If you use the dropin deployment method, you do not need to do steps 11, 12, 13, and 14
  11. Create a CICS bundle project by using the CICS Bundle Project wizard:
    1. In the CICS Explorer SDK menu bar, click File > New > Other. The New wizard starts.
    2. In the "Select a wizard" window, expand CICS Resources, select CICS Bundle Project, then click Next. The Bundle Project wizard starts and the CICS Bundle Project window opens.
    3. Provide a name for the project in the Project name field. Update the ID and Version fields if you do not want to use the default values. Click Finish. The CICS Bundle Project is created and is displayed in the Package Explorer window.
  12. Create an .ebabundle file in the CICS Bundle Project created in step 11:
    1. In the Package Explorer pane, right-click the CICS Bundle project that is created in step 11, and click New > Other. The New wizard starts.
    2. In the "Select a wizard" window, expand CICS Resources, select OSGi Application Project Include, then click Next.
    3. In the OSGi Application Project Include window, select the OSGi Application Project (user EBA) that you created in step 9, provide the name of the JVM Server where the application is to run in the JVM Server field, and click Finish. The .ebabundle file is created in the CICS Bundle Project. The *.ebabundle file associates the Liberty JVM server that is installed by the feature pack with the OSGi Application Project created in step 9.
  13. Right-click the CICS bundle project that you created in step 11 and click Export Bundle project to z/OS UNIX File System to export to zFS the CICS Bundle project you created in step 11. The zFS location must be accessible by the CICS region in which you installed the CICS Dynamic Scripting Feature Pack. The EBA is exported as a file with a .eba extension.
  14. Define and install a BUNDLE resource that references the CICS bundle project that is exported in step 13. For details, see the CICS Explorer SDK help topic Deploying OSGi bundles in a JVM server.

Results

Your application is created on your workstation and deployed to your CICS region. The application is available for testing.

What to do next

Test that the application works correctly in CICS.

For more information about debugging PHP code, see Debugging PHP code.



devapps_eclipse_workstation.html | Timestamp icon Last updated: Sunday, 4 June 2017