This document covers the following topics:
The EntireX z/OS CICS® RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/OS under CICS. It supports the programming languages COBOL and PL/I.
This section covers the following topics:
Starting the EntireX RPC Server Automatically on CICS Startup (Optional)
Stopping the EntireX RPC Server Automatically on CICS Shutdown (Optional)
Installing Multiple EntireX RPC Servers in the same CICS (Optional)
Using SSL or TLS Connections with the CICS RPC Server (Optional)
Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.
EntireX RPC requires a number of enhancements to the CICS tables. These changes are usually performed by a CICS system programmer using standard system jobs.
Execute "Step 3: Install CICS CSD defs for EntireX RPC Server" of job EXPINSTA located in the EXX951.JOBS data set. This will add the group ERX with all its relevant entries.
Tracing: TD queue entries for RPC server trace output may optionally
be updated by uncommenting the DFHTRACE exec line.
See also ERXMAIN
Macro parameter TRC1
.
Note:
If you have not extended your DCT (that is, you are using the
default values), you must specify the option DCT= in the CICS SYSIN
file.
The startup JCL for CICS must be modified to include the EXP951.LD00 data set in the DFHRPL data set concatenation. This is to enable CICS to find the various programs that have been defined in the PPT.
You may also include a DD statement for ERXOUT extra partition data set. Once the startup JCL has been modified, restart your CICS system.
Adapt the RPC server configuration in the Assembler program EMAINGEN
(in EXP951.SRCE) to the customer environment. See ERXMAIN
Macro.
Execute "Step 2: Build the ERXMAIN
Control
Block" of job EXPINSTA
located in the EXX951.JOBS data set.
The name of the main control block in earlier versions was fixed as
ERXMAIN
. As of version 5.1.1, any meaningful name can be chosen.
Using this name as input parameter memory
for the RPC Online Maintenance Facility
means that multiple CICS RPC Servers can be started and monitored in parallel.
A fully linked control block named ERXMAIN
is delivered in the load library EXP951.LOAD.
See also Verify the Installation of the EntireX RPC Server.
If you are using transport method TCP/IP, your CICS region must be enabled for TCP/IP. Refer to your CICS documentation for details.
Execute "Step 7: Allocate and (CSD) define SVM
file" of the EXPINSTA
job located in the EXX951.JOBS data set.
After updating the SVMFILE
variable to a suitable name, the following steps are
performed:
allocation of the required VSAM cluster
initialization of the cluster with the first SVM record fitting the
CICS advanced channel container example DFHCON
and the advanced CICS large buffer example DFHLBUF
of the EXP951.DVCO data set.
See Client and Server Examples for z/OS CICS.
CICS CSD definition with the given name in the SVMFILE
variable
See also Handling SVM Files.
To start the RPC server automatically on CICS startup
Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTART
.
Rebuild the PLT for CICS startup.
Note:
The EXP951.LD00 CICS load library contains a precompiled ERXSTART
module with the default settings of the COBOL source member ERXSTART
in EXP951.SRCE
To stop the RPC server automatically on CICS shutdown
Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTOP
into your CICS shutdown table.
Rebuild the PLT for CICS shutdown.
Note:
The EXP951.LD00 CICS load library contains a precompiled ERXSTOP
module with the default settings of the COBOL source member ERXSTOP
in EXP951.SRCE
To install a second RPC server in the same CICS
Copy the default CICS RPC Server transaction definition ESRV
and give it a unique name,
e.g. ESR2
.
CEDA COPY TRANSACTION(ESRV) GROUP(ERX) TO(ERX2) AS(ESR2)
Copy the default CICS RPC Server ERXMAIN
Control Block and give it a unique name, e.g. ERXMAIN2
.
CEDA COPY PROGRAM(ERXMAIN) GROUP(ERX) TO(ERX2) AS(ERXMAIN2)
Add the new group ERX2
to the CICS autoinstall list.
CEDA ADD GROUP(ERX2) LIST(listname) AFTER(groupname)
Build a new ERXMAIN
Control Block and give it the name created above, e.g. ERXMAIN2
.
As a minumum, set the ERXMAIN
Macro parameter REPL
in the ERXMAIN
Control Block to the new RPC server transaction ID created above, e.g. REPL=ESR2
.
The second CICS RPC server can now be started manually (see Starting the RPC Server under RPC Online Maintenance Facility), or automatically on CICS startup.
To start a second RPC server automatically on CICS startup
Copy the default CICS RPC Server autostart definition ERXSTART
and give it a unique name, e.g. ERXSTRT2
.
CEDA COPY PROGRAM(ERXSTART) GROUP(ERX) TO(ERX2) AS(ERXSTRT2)
"CEDA Install" the new autostart definition.
Modify the CICS RPC Server PLT startup routine ERXSTART
from data set EXP951.SRCE.
Update RPC-TRANSID
with ESR2
.
Update RPC-INPUT
with MEM=ERXMAIN2
.
Compile and link the modified source and give it the name defined above, e.g. ERXSTRT2
.
Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTRT2
.
Rebuild the PLT for CICS startup.
To stop a second RPC server automatically on CICS shutdown
Copy the default CICS RPC server autostop definition ERXSTOP
and give it a unique name, e.g. ERXSTOP2
.
CEDA COPY PROGRAM(ERXSTOP) GROUP(ERX) TO(ERX2) AS(ERXSTOP2)
"CEDA Install" the new autostop definition.
Modify the CICS RPC Server PLT routine ERXSTOP
from data set EXP951.SRCE.
Update RPC-TRANSID
with ESR2
.
Update RPC-INPUT
with MEM=ERXMAIN2
.
Compile and link the modified source and give it the name defined above, e.g. ERXSTOP2
.
Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTOP2
into your CICS shutdown table.
Rebuild the PLT for CICS shutdown.
See Using SSL or TLS with the RPC Server.
The EntireX RPC Server under z/OS (Batch, IMS) enables you to call COBOL or PL/I RPC services with standard IBM linkage convention as servers.
This section covers the following topics:
Install the SVM File for a Batch or IMS RPC Server (Optional)
Using SSL or TLS Connections with the Batch RPC Server (Optional)
Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.
Note:
For Natural RPC servers, see Setting Up a Natural RPC Environment in your Natural documentation.
The EntireX RPC Server for z/OS (Batch) can run as a started task. The installation medium contains the following sample JCL:
EXPSRVB
To prepare your startup JCL
Modify the example job EXPSRVB of the EXX951.JOBS data set to suit your installation.
Modify the CONFIG DD statement to point to your server configuration file.
Concatenate your server application data set to the RPC server STEPLIB.
Add the EntireX RPC server JCL to your TASKLIB data set.
The EntireX RPC server is optimized for use in COBOL environments. Nevertheless, as a minimum the following parameters must be set according to your system environment:
BrokerId
Class
ServerName
Service
For more information see Configuring the RPC Server.
Some of the RPC server features such as impersonation require privileged z/OS access. Therefore, the RPC server should be started (initially) from an APF-authorized library. Consequently, all other load data sets concatenated to STEPLIB DD have to be APF-authorized as well, including customer's server data sets.
To cope with non-APF-authorized data sets, a server invocation module
EXXAUTH$
is provided. The module can be invoked (APF-authorized)
from an APF data set (other than STEPLIB), which installs the authorized PC
routines necessary before it invokes (unauthorized) the RPC server.
To install the server invocation module
Copy load module EXXAUTH$
from EntireX load
library EXP951.LB00 to an APF-authorized load library
that is linked to the system LNKLST concatenation and rename the copy to
EXXAUTH
.
Note:
A different name is essential if the
EXP951.LB00 is part of the STEPLIB concatenation,
because under z/OS search for the module is first done in the STEPLIB libraries
prior to LNKLST libraries. Thus not changing the name would result in invoking
the module from STEPLIB instead of invoking the module from LNKLST and the
module could not work properly.
Change the RPC server startup JCL:
//BATRPCS EXEC PGM=EXXAUTH, PARM='RPCSRVB CFG=DD:CONFIG'
Note:EXXAUTH
expects the first parameter to be the name
of the RPC server to be started. Subsequent parameters will be passed to the
RPC server directly.
Execute the EXPSVMAL
job located in the EXX951.JOBS data set. After
updating the SVMFILE
variable to a suitable name, the following steps are
performed:
allocation of the required VSAM cluster
initialization of the cluster with a dummy SVM record
Insert the new SVM file into your Batch RPC server's JCL under the DD
name of ERXSVM
. If this cluster is to be shared between more than one server it
should be defined with the RLS=NRI
attribute:
//ERXSVM DD DISP=SHR,DSN=< batch.svm.cluster >
See Handling SVM Files.
See Using SSL or TLS with the RPC Server.
All example data sets are delivered in the condensed IBM IEBCOPY
load
format and can be found with their last level qualifier as a member name in the
EXP951.EXPL data set. The CICS and batch examples are unloaded
with separate jobs:
To unload the CICS members to their target data sets
Select the desired programming language (COBOL or PL/I) and execute
"Step 5: Extract the Examples" of job EXPINSTA
located in the EXX951.JOBS data set.
To unload the Batch members to their target data sets
Select the desired programming language (COBOL or PL/I) and execute
job EXPEXAMP
located in the EXX951.JOBS data set.
To unload the IMS members to their target data sets
Execute
job EXPINSTI
located in the EXX951.JOBS data set.