Important
It is strongly recommended that all the
regions in a logical EJB server—both listeners and AORs—should be at the same
level of CICS.
In simplified form, the steps involved in setting up a CICS logical
EJB server to
support enterprise beans are:
- Create a set of cloned CICS® Transaction Server for z/OS®, Version 3 Release 1 listener
regions.Each of the listener regions must have the IIOPLISTENER system
initialization parameter set to YES.
- Create a set of cloned CICS Transaction Server for z/OS, Version 3 Release 1 AORs.
Each of the AORs must:
- Be set up to use JNDI
- Use the same JNDI initial context as the other AORs
- Be connected to all of the listener regions by MRO (not ISC)
- Have the IIOPLISTENER system initialization parameter set to NO.
- Create a shelf root directory on HFS. For example, you might create an
HFS directory called /var/cicsts/. To do this, you need an
HFS userid with write authority to the directory path to be used by CICS.
Having created the shelf directory, you must give the AORs' userids full access
to it—read, write, and execute.
- Create a deployed JAR file (pickup) directory on HFS. For example, you
might create an HFS directory called /var/cicsts/pickup.
The AORs must have at least read access to it.
Note: If your AORs are to contain
more than one CorbaServer execution environment:
- You must create a separate pickup directory for each CorbaServer.
- It is recommended that you assign different sets of transaction IDs to
the objects supported by each CorbaServer. That is, each CorbaServer in an
AOR should support a different set of transaction IDs. (To assign transaction
IDs to bean methods, you use REQUESTMODEL definitions—see step 5.)
- Create the following resource definitions. You can create them on a CSD
that is shared by all the regions in the logical server, copy them to all
the CSDs used by the regions, or add them to a CICSPlex SM Resource Description
that applies to all the regions. Optionally, you can use the CICS scanning
mechanism, the RM for enterprise beans, and the CREA CICS-supplied transaction
to create some of these definitions, as described below.
- A TCPIPSERVICE. On the PROTOCOL option, specify IIOP. On the SSL option,
specify NO. On the AUTHENTICATE option, specify NO. This means that the service
on this port will accept unauthenticated inbound IIOP requests.
- Some REQUESTMODEL definitions. In a single-region EJB server, these
are only required if the default TRANSID, CIRP, is unsuitable. In a multi-region
logical server, however, they are required if you want to route method requests
across several AORs. (The TRANSACTION definition for CIRP specifies DYNAMIC(NO).) They
are required too if, for example, you want to segregate your IIOP workload
by transaction ID.
The BEANNAME attribute of each REQUESTMODEL definition
must “match” (in a pattern-matching sense) the name of an enterprise bean
in the deployment descriptor in a deployed JAR file on HFS. The value of the
CORBASERVER attribute must match (either literally or in a pattern-matching
sense) the name of the CorbaServer on the CORBASERVER definition.
Note: - Copy the transaction definition for the TRANSID named on your REQUESTMODEL
from that of CIRP. Set the DYNAMIC attribute to YES. You can change
any of the other attributes, but the program name must be that of a JVM program
whose JVMClass is com.ibm.cics.iiop.RequestProcessor.
- When the CorbaServer is operational, you can use the CREA CICS-supplied
transaction to display the transaction IDs associated with particular beans
and bean-methods in the CorbaServer. You can change the transaction IDs, apply
the changes, and save the changes to new REQUESTMODEL definitions.
- A CORBASERVER definition.
The value of the HOST option of the CORBASERVER
definition must match that of the IPADDRESS option of the TCPIPSERVICE definition.
However, if the TCPIPSERVICE specifies a value for DNSGROUP, the HOST option
of the CORBASERVER definition must specify a matching generic host name.
On
the UNAUTH option, specify the name of the TCPIPSERVICE definition.
Note: You
must always specify a value for the UNAUTH attribute when you define a CorbaServer,
even if you intend that all inbound requests to the CorbaServer should be
authenticated. This is because the port number from the TCPIPSERVICE is used
to construct Interoperable Object References (IORs) that are exported from
this logical server. You can, by specifying the name of other TCPIPSERVICE
definitions on one or both of the CLIENTCERT or SSLUNAUTH options, cause your
listener regions to listen on other ports for different types of authenticated
inbound IIOP requests. For more information, see
the documentation
of the CORBASERVER and
TCPIPSERVICE
resource definitions.
On the SHELF option, specify the
fully-qualified name of the HFS shelf directory that you created in step 3.
(Because the CORBASERVER definition will be installed on all the AORs in the
logical server, this “high-level” shelf directory will be shared by all of
them. Each AOR will automatically create its own sub-directory beneath the
shelf directory, and a sub-directory for the CorbaServer beneath that.)
On
the DJARDIR option, specify the fully-qualified name of the HFS deployed JAR
file directory (pickup directory) that you created in step 4. Like the shelf
directory, the pickup directory (or directories, if your AORs contain
multiple CorbaServers) will be shared by all the AORs in the logical
server. On each AOR, when a CORBASERVER definition is installed, CICS
scans the CorbaServer's pickup directory and installs any deployed JAR files
it finds there. It copies them to its shelf sub-directory and dynamically
creates and installs DJAR definitions for them.
Specify AUTOPUBLISH(YES).
This causes CICS to publish beans to the namespace automatically, when a DJAR
definition is successfully installed.
On the STATUS option, specify
Enabled.
- FILE definitions for the following files required by CICS:
- The EJB directory, DFHEJDIR
- is
a file containing a request streams directory which must be shared by all
the regions (listeners and AORs) in the logical EJB server. (Request streams
are used in the distributed routing of method requests for enterprise beans
and CORBA stateless objects.) You must define DFHEJDIR as recoverable.
- The EJB object Store, DFHEJOS
- is a
file of stateful session beans that have been passivated. It must be shared
by all the AORs in the logical EJB server. You must define it as non-recoverable.
To share DFHEJDIR and DFHEJOS across multiple regions,
you could, for instance, use any of the following methods:
- Define them as remote files in a file-owning region (FOR)
- Define them as coupling facility data tables
- Use VSAM RLS.
There are sample FILE definitions for DFHEJDIR and DFHEJOS in
the CICS-supplied RDO group, DFHEJVS. There are sample coupling facility FILE
definitions for DFHEJDIR and DFHEJOS in the CICS-supplied RDO group, DFHEJCF.
There are sample VSAM RLS FILE definitions for DFHEJDIR and DFHEJOS in the
CICS-supplied RDO group, DFHEJVR. (DFHEJVS, DFHEJCF, and DFHEJVR are not included
in the default CICS startup group list, DFHLIST.)
Note: For clarity's sake, we're assuming that there's only one CorbaServer
in the logical server. To create another CorbaServer, you'll need a second
CORBASERVER definition and another TCPIPSERVICE definition.
- Define the underlying VSAM data sets for DFHEJDIR and DFHEJOS. CICS supplies
sample JCL to help you do this, in the DFHDEFDS member of the SDFHINST library.
- Using a deployment tool such as the Assembly Toolkit (ATK),
take one or more ejb-jar files and perform code generation on them to produce
deployed JAR files on HFS. Store the deployed JAR files in the CorbaServer's
pickup directory.
- Start all the CICS regions. On each of the listener regions, the definitions
to be installed from the CSD are:
- The TCPIPSERVICE definition
- The REQUESTMODEL definitions
- The file definition for DFHEJDIR
On each of the AORs, the definitions to be installed from the CSD
are:
- The TCPIPSERVICE definition.
- The REQUESTMODEL definitions.
Note: The REQUESTMODEL definitions in the
AORs are required for outbound requests to local objects. If a CORBA stateless
object or enterprise bean makes a call to another object, and that object
is available on the local AOR, CICS does not send the request to a listener
region. Instead, it either runs the called method in the current task (“tight
loopback”) or starts another request processor in the local AOR (“normal loopback”).
Where normal loopback is used, it's preferable that the new request processor
task should use the same REQUESTMODEL as that used for the call to the first
object—otherwise, unpredictable results may occur. If your CORBA stateless
objects and enterprise beans make no outbound calls, the REQUESTMODELs on
the AOR are not strictly required.
- The CORBASERVER definition.
- The file definitions for DFHEJDIR and DFHEJOS.
Note: If you put your deployed JAR files in the shared pickup directory,
DJAR definitions are created and installed on the AORs automatically when
the CorbaServer is installed (or when a subsequent scan takes place). It is
only necessary to create static (CSD-installed) DJAR definitions for deployed
JAR files that you place in other HFS directories.
- On each AOR, when the CORBASERVER definition is installed, CICS scans
the pickup directory and installs any deployed JAR files it finds there. It
copies them to its shelf directory and dynamically creates and installs DJAR
definitions for them.
Note: You can put deployed JAR files in the pickup directory
after CICS has performed its initial scan at the time the CORBASERVER definition
was installed. If you do so, you can force CICS to perform another scan by
issuing a CORBASERVER PERFORM SCAN command. This command can be issued using
EXEC CICS, the CEMT master terminal transaction, or the web-based resource
manager for enterprise beans (otherwise known as the RM for enterprise beans).
- Because you specified AUTOPUBLISH(YES) on the CORBASERVER definition,
when the DJAR definitions are successfully installed the homes of the enterprise
beans will be automatically bound into the JNDI namespace.
If you had
specified AUTOPUBLISH(NO), you would need to issue a PERFORM CORBASERVER(CorbaServer_name)
PUBLISH command on at least one of the AORs. This command can be issued using
EXEC CICS, the CEMT master terminal transaction, the RM for enterprise beans,
or via a CICSPlex SM EUI or WUI View.
- On the DSRTPGM system initialization parameter for the listener regions,
specify the name of the distributed routing program to be used. If you're
using CICSPlex SM, specify the name of the CICSPlex SM routing program, EYU9XLOP.
Otherwise, specify the name of your customized routing program. For information
about the DSRTPGM system initialization parameter, see the CICS System Definition
Guide.
Figure 1 shows the RDO definitions
required to define a CICS logical EJB server. It shows which definitions are
required in the listener regions, which in the AORs, and which in both.
Figure 1. Resource definitions in a CICS logical
EJB server.
The picture shows which definitions are required in
the listener regions, which in the AORs, and which in both.