Note that, if you have previously configured CICS as an IIOP
server (to support method calls to CORBA stateless objects), you may already
have performed some of these steps.
- Install the IBM® Software Developer Kit for z/OS®, Java™ 2 Technology Edition, Version 1.4.2,
which provides a Java Virtual Machine (JVM) featuring persistent reusable
JVM technology. This is available from www.s390.ibm.com/java.
- Set up CICS to support IIOP calls. (CICS uses the same RMI-over-IIOP protocol
to support client method requests for both CORBA stateless objects and enterprise
beans.) How to do this is described in Setting up CICS for IIOP.
Bear in mind when reading
Setting up CICS for IIOP that:
- Because our single-region EJB server is a combined listener/AOR, you must
specify 'YES' on the IIOPLISTENER system initialization parameter.
- CICS® loads
JVM profiles from the HFS directory that is specified by the JVMPROFILEDIR
system initialization parameter. When you install CICS, the CICS-supplied
default and sample JVM profiles are placed in the directory /usr/lpp/cicsts/cicsts31/JVMProfiles,
where cicsts31 is
the value that you chose for the CICS_DIRECTORY variable used by the DFHIJVMJ
job during CICS installation.
The default value of CICS_DIRECTORY is "cicsts31".
The default value of JVMPROFILEDIR is /usr/lpp/cicsts/cicsts31/JVMProfiles. That is, the supplied setting for JVMPROFILEDIR points to the default directory
for the sample JVM profiles. If you chose a different name during CICS installation
for the directory containing the sample JVM profiles (that is, if you chose
a non-default value for the CICS_DIRECTORY variable used by the DFHIJVMJ job),
or if you have created your own JVM profiles in a directory other than the
samples directory, you need to do one of the following:
- Change the value of the JVMPROFILEDIR system initialization parameter.
- Link to your profiles from the directory specified by JVMPROFILEDIR by
means of UNIX soft
links.
- If you want to use your single-region server as the basis of a multi-region
server, you should ensure that the request streams directory file, DFHEJDIR,
and the EJB object store file, DFHEJOS, can be shared across multiple regions.
For this reason, it is recommended that you define them in one of the following
ways:
- As remote files in a file-owning region (FOR)
- As coupling facility data tables
- Using VSAM RLS.
- PROGRAM definitions are not required for enterprise beans as such. The
only PROGRAM definitions required are those for the request receiver and request
processor programs. The default request processor program—named by the default
CIRP transaction on REQUESTMODEL definitions—is DFJIIRP. CIRP and DFJIIRP
are defined in the supplied resource definition group DFHIIOP, as are CIRR
and DFHIIRRS, the request receiver transaction and program. DFHIIOP is included
in the default CICS startup group list.
If you are using a JVM profile
other than the default DFHJVMCD, you must specify the name of your
profile on the JVMPROFILE option of the PROGRAM definition for the request
processor program. (It is possible to use a CEMT SET PROGRAM JVMPROFILE
command to change the JVM profile from that specified on the installed PROGRAM
definition. However, if you create your own JVM profile you are recommended
to create new TRANSACTION and PROGRAM definitions for the request processor
program, rather than change the default definitions.)
- You must specify the location of your name server on the com.ibm.cics.ejs.nameserver property
in all the JVM properties files that are used by CORBA applications or enterprise
beans—including the dfjjvmcd.props properties file that CICS
uses to to publish deployed JAR files.
For detailed information about
defining the location of your name server, see the CICS System Definition Guide.
- You don't need to install REQUESTMODEL or DJAR definitions at this stage,
because:
- The EJB IVP and EJB sample applications use the default REQUESTMODEL transaction
ID, CIRP.
- REQUESTMODEL definitions are most easily created by using the CREA transaction
after you have deployed your enterprise beans into CICS. Deployment is a separate
process that occurs after you have set up your EJB server. It is described
in Deploying enterprise beans.
- DJAR definitions are typically created and installed by the CICS scanning
mechanism during deployment.
- Create the following CICS resource definitions:
- A TCPIPSERVICE
- A CORBASERVER
The CICS-supplied sample group, DFH$EJB, contains TCPIPSERVICE and CORBASERVER
definitions suitable for running the EJB IVP. You must change some of the
attributes of these resource definitions to suit your own environment. To
do this, use the CEDA transaction or the DFHCSDUP utility. - Copy the sample group to a group of your own choosing. For example:
CEDA COPY GROUP(DFH$EJB) TO(mygroup)
- Display group mygroup and change the following attributes
appropriately:
- On the TCPIPSERVICE resource definition, modify the PORTNUMBER as necessary
to a suitable TCP/IP port on your installation. The port number that you specify
must be authorized by your network administrator.
Note: - Note that, on the supplied TCPIPSERVICE definition:
- The PROTOCOL option specifies IIOP. This is the required protocol for
method calls to enterprise beans and CORBA stateless objects.
- The SSL option specifies NO.
- The AUTHENTICATE option defaults to NO. This means that the service on
this port will accept unauthenticated inbound IIOP requests.
- If you want to use your single-region server as the basis of a multi-region
server, as described in Setting up a multi-region EJB server, you should
specify a value for the DNSGROUP option. This ensures that, in a multi-region
server, you will be able to use connection optimization, by means of dynamic
DNS registration, to balance client connections across the listener regions.
- For reference information about TCPIPSERVICE definitions, see the CICS Resource
Definition Guide.
- On the CORBASERVER resource definition:
- Modify the SHELF option so that it specifies the fully-qualified name
of the HFS shelf directory that you created in step 2 of Actions required on HFS.
Note: In a multi-region EJB server, because the CORBASERVER definition will
be installed on all the AORs 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.
- Modify the DJARDIR option so that it specifies the fully-qualified
name of the HFS deployed JAR file directory (pickup directory) that you created
in step 3 of Actions required on HFS.
Note: In a multi-region
EJB server, the pickup directory (or directories, if the AORs contain
multiple CorbaServers), like the shelf directory, will be shared by all
the AORs in the logical server.
- Set the HOST to your TCP/IP hostname.
Note: - Note that, on the supplied CORBASERVER definition:
- The UNAUTH option specifies the name of the TCPIPSERVICE definition.
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
definitions.
- The AUTOPUBLISH option specifies YES. This causes CICS to publish beans
to the namespace automatically, when a DJAR definition is successfully installed.
- The STATUS option specifies Enabled.
- Because we're creating a single-region server, the value of the HOST option
of the CORBASERVER definition must match that of the IPADDRESS option of the
TCPIPSERVICE definition. (In a multi-region server, if dynamic DNS registration
is used to balance client connections across the listener regions, the value
of the HOST option must match the generic host name specified on the DNSGROUP
option of the TCPIPSERVICE definition.)
- For reference information about CORBASERVER definitions, see the CICS Resource
Definition Guide.
- Install group mygroup to make these definitions known
to CICS.
When the CORBASERVER definition is installed, CICS:
- Scans the pickup directory that you specified on the DJARDIR option
- Copies any deployed JAR files that it finds in the pickup directory to
its shelf directory
- Dynamically creates and installs DJAR definitions for the deployed JAR
files (if any) that it found in the pickup directory
- Because the CORBASERVER definition specifies AUTOPUBLISH(YES), publishes
any enterprise beans contained in the DJARs to the JNDI namespace.
- Set the status of the TCPIPSERVICE to OPEN:
CEMT SET TCPIPSERVICE(EJBTCP1) OPEN
On
the CICS Console, you should see, among others, messages similar to the following:
DFHEJ0701 CorbaServer EJB1 has been created.
DFHEJ5024 Scan commencing for CorbaServer EJB1, directory being scanned is
DJARDIR_name.
DFHEJ5025 Scan completed for CorbaServer EJB1, 0 DJars created, 0 DJars
updated.
DFHEJ1520 CorbaServer EJB1 is now accessible.
DFHSO0107 TCPIPSERVICE EJBTCP1 has been opened on port port_number at IP
address xxx.xxx.xxx.xxx
where:
- DJARDIR_name is the name of your CorbaServer's deployed JAR file
(“pickup”) directory.
- port_number is the number of the TCP/IP port used by your CorbaServer.
- xxx.xxx.xxx.xxx is your CorbaServer's IP address.
- Set up CICS to use JNDI. To enable Java code running under CICS to issue
JNDI API calls, and CICS to publish references to the home interfaces of enterprise
beans, you must specify the location of the name server. (For an LDAP name
server there is additional information to be specified.) Specify the URL
and port number of your name server on the com.ibm.cics.ejs.nameserver property
in your JVM properties file.
For example, to use
tnameserv,
the lightweight COS Naming Directory Server supplied with Java 1.3 and later,
specify:
com.ibm.cics.ejs.nameserver=iiop://tnameserv.yourcompany.com:2809
where
tnameserv.yourcompany.com is the address of the host on which you started the
tnameserv name
server and
2809 is the port you selected.
If you are
using an enterprise-quality LDAP server you might specify:
com.ibm.cics.ejs.nameserver=ldap://demojndi.yourcompany.com:389
For
the other properties that are required, and the way to set up your LDAP name
server, see
Setting up an LDAP server.
If you are
using a standard COS Naming Directory Server you might specify:
com.ibm.cics.ejs.nameserver=iiop://demojndi.yourcompany.com:900
If you are using the COS Naming Directory Server supplied with
WebSphere® Application Server Version 5 or
later, you should specify:
com.ibm.cics.ejs.nameserver=iiop://demojndi.yourcompany.com:2809/domain/legacyRoot
Important: For detailed information about defining the location
of the name server, see the description of the
com.ibm.cics.ejs.nameserver property
in
the CICS System
Definition Guide.
The location of the JVM properties file
is specified on the JVMPROPS statement in your JVM profile. (The JVM profile
for the default request processor program is DFHJVMCD. If you have followed
the previous steps in this section, the profile or profiles you are using
should be in the HFS directory specified by the JVMPROFILEDIR system initialization
parameter.)
Important: These instructions have shown you how to set
up a single-region EJB server that contains a single CorbaServer execution
environment. In a production region that supports multiple applications, each
of which uses its own set of enterprise beans, you may require multiple CorbaServers.
To facilitate maintenance in a production region, you should follow the guidelines
on how to allocate beans to CorbaServers and transaction IDs in
Updating enterprise beans in a production region.
Having
completed the above steps, you can, if you wish, run the EJB Installation
Verification Program, which tests that you have configured CICS correctly
as an EJB server. For details of the EJB IVP, see Running the EJB IVP.
Alternatively, you can continue with the next section before running the IVP.