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
- In the CICS Explorer SDK,
open the Java™ perspective.
- Ensure the target platform is available. For
more information, see Making the CICS TS Feature Pack for Dynamic Scripting V2.0 target platform available.
- Create an OSGi bundle, with web
support, by using the New OSGi Bundle Project Include wizard:
- In the CICS Explorer SDK menu
bar, click . The New
wizard starts.
- In the "Select a wizard" window,
expand CICS Resources, select OSGi
Bundle Project Include, then click Next. The OSGi Bundle Project Include window
opens.
- 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.
- In the Java window, click Next. The Web Module window opens.
- 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.
- 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.
- 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)",
- 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:
- Add the following import declaration to the generated
Activator Java class:
import com.ibm.cics.php.CICSPHPInitialiser;
- 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 {
}
}
- 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.
- 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 , 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.
- 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.
- Create a user EBA file by using the
New OSGi Application Project wizard:
- In the CICS Explorer SDK menu
bar, click .
- In the "Select a wizard"window,
expand CICS Resources, select OSGi
Application Project Include, then click Next. The OSGi Application Project Include window
opens.
- Provide a name for the project in the Project
name field and click Next. The Contained OSGi Bundles and Composite Bundles window
opens.
- 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.
- 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
- Create a CICS bundle project by using the CICS Bundle Project wizard:
- In the CICS Explorer SDK menu
bar, click . The New
wizard starts.
- 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.
- 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.
- Create an .ebabundle file
in the CICS Bundle Project
created in step 11:
- In the Package Explorer pane, right-click the CICS Bundle project that is created
in step 11,
and click . The New wizard starts.
- In the "Select a wizard" window,
expand CICS Resources, select OSGi
Application Project Include, then click Next.
- 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.
- 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.
- 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.