This document covers the following topics:
For Natural RPC servers, see Setting Up a Natural RPC Environment in your Natural documentation.
The EntireX RPC Server for z/OS CICS® 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:
Installing the Server-side Mapping Container for an RPC Server for CICS (Optional)
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/TLS Connections with the RPC Server for CICS (Optional)
Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.
Note:
Installing the RPC Server for CICS also installs the CICS Socket Listener used by the EntireX Adapter or RPC Server for CICS
Socket Listener.
For more information and configuration details see Preparing for CICS Socket Listener (EntireX Adapter | RPC Server for CICS Socket Listener).
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 "Install CICS CSD defs for EntireX RPC Server" of job EXPINSTA located in the EXX109.JOBS data set. This will install the RPC Server for CICS with all relevant CSD 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.
DEFINE TRANSACTION(ERXM) GROUP(ERX) PROGRAM(ERXMAINT) TWASIZE(128) DEFINE TRANSACTION(ESRV) GROUP(ERX) PROGRAM(RPCSRVC) TWASIZE(128) DEFINE TRANSACTION(EC01) GROUP(ERX) PROGRAM(SQRECLT) TWASIZE(28)
Transaction ERXM is used to run the RPC Online Maintenance Facility.
Transaction ESRV is used to run the RPC Server for CICS; see Customizing the RPC Server.
Notes:
TWASIZE. See CICS Settings.
The startup JCL for CICS must be modified to include the EXP109.LD00 and EXX109.LOAD data sets 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.
The RPC executables are distributed prelinked with unresolved external references to z/OS components. To resolve these external references, you need to relink them in your environment. Execute step "Link the RPC Server for CICS modules" of job EXPINSTA located in the EXX109.JOBS data set.
The ERXMAIN control block holds the RPC Server for CICS parameter settings. This configuration can be manually maintained by using the RPC Online Maintenance Facility.
A fully linked control block named ERXMAIN is delivered in the load library EXP109.LOAD. To alter this configuration, perform the following steps:
Adapt the RPC server configuration in the Assembler program EMAINGEN located in the EXP109.SRCE data set to the customer environment, see Customizing the RPC Server.
Execute step "Build the ERXMAIN Control Block" of job EXPINSTA located in the EXX109.JOBS data set.
The name of the ERXMAIN control block may be altered. This allows you to run multiple RPC Server for CICS instances. See Installing Multiple EntireX RPC Servers in the same CICS (Optional).
If you are using transport method TCP/IP, your CICS region must be enabled for TCP/IP. Refer to your CICS documentation for details.
You can skip this step if you are a new customer or have never used server-side mapping files (Designer files with extension .svm) from previous EntireX versions.
If you are using server-side mapping files (Designer files with extension .svm) at runtime, you need to set up a server-side mapping container.
Execute step "Allocate and (CSD) define SVM
file" of the EXPINSTA job located in the EXX109.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 server mapping (VSAM record) that matches the
CICS advanced channel container example DFHCON of the EXP109.DVCO data set.
See Client and Server Examples for z/OS CICS.
CICS CSD definition with the given name in the SVMFILE variable
Server mapping files with extension .svm are no longer supported at design time by the Designer.
You can still use them at runtime in a server-side mapping container.
All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping
files with extension .cvm.
See When is a Server Mapping File Required?
We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation.
See also Server Mapping Files for COBOL | Server-side Mapping Files | Job Replacement Parameters.
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 EXP109.LD00 CICS load library contains a precompiled ERXSTART module with the default settings of the COBOL source member ERXSTART in EXP109.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 EXP109.LD00 CICS load library contains a precompiled ERXSTOP module with the default settings of the COBOL source member ERXSTOP in EXP109.SRCE
To install a second RPC server in the same CICS
Copy the default RPC Server for CICS 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 RPC Server for CICS 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 minimum, 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 RPC Server for CICS 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 RPC Server for CICS 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 RPC Server for CICS PLT startup routine ERXSTART from data set EXP109.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 RPC Server for CICS 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 RPC Server for CICS PLT routine ERXSTOP from data set EXP109.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/TLS with the RPC Server.
The EntireX RPC Server for z/OS Batch allows standard RPC clients to communicate with RPC servers on the operating system z/OS running in batch mode. It supports the programming languages COBOL, PL/I and C and works together with the COBOL Wrapper and IDL Extractor for COBOL. This section covers the following topics:
Installing the Server-side Mapping Container for an RPC Server for Batch (Optional)
Using SSL/TLS Connections with the RPC Server for Batch (Optional)
Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.
The RPC Server for Batch can run as a started task. The installation medium contains the following sample JCL:
EXPSRVB
To prepare your startup JCL
Modify the example started task EXPSRVB of the EXX109.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.
Modify the sample parameter member CONFIG from EXP109.SRCE.
The RPC Server for Batch 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.
The RPC executables are distributed prelinked with unresolved external references to z/OS components. To resolve these external references, you need to relink them in your environment. Execute step "Link the RPC server modules" of job EXPINSTB located in the EXX109.JOBS data set.
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 EXP109.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
EXP109.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.
You can skip this step if you are a new customer or have never used server-side mapping files (Designer files with extension .svm) from previous EntireX versions.
If you are using server-side mapping files (Designer files with extension .svm) at runtime, you need to set up a server-side mapping container.
Execute the EXPSVMAL job located in the EXX109.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 server mapping (VSAM record)
Insert the server-side mapping container (VSAM file) into your RPC server's JCL under the DD
name of ERXSVM. If this cluster is to be shared between more than one RPC server it
should be defined with the RLS=NRI
attribute:
//ERXSVM DD DISP=SHR,DSN=< batch.svm.cluster >
Server mapping files with extension .svm are no longer supported at design time by the Designer.
You can still use them at runtime in a server-side mapping container.
All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping
files with extension .cvm.
See When is a Server Mapping File Required?
We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation.
See also Server Mapping Files for COBOL | Server-side Mapping Files |Job Replacement Parameters.
See Using SSL/TLS with the RPC Server.
The EntireX RPC Server for IMS allows standard RPC clients to communicate with RPC servers on the operating system z/OS running with IMS in BMP mode. It supports the programming languages COBOL, PL/I and C and can provide IMS-specific PCB pointers for access to IMS databases if needed. This section covers the following topics:
Installing the Server-side Mapping Container for an RPC Server for IMS (Optional)
Using SSL/TLS Connections with the RPC Server for IMS (Optional)
Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.
The RPC Server for IMS can run as a started task. The installation medium contains the following sample JCL:
EXPSRVI
To prepare your startup JCL
Modify the sample started task EXPSRVI of the EXX109.JOBS data set to suit
your installation.
Modify the CONFIG DD statement to point to your server configuration
file.
Name a valid PSB in the parameter list for IMSBATCH.
Concatenate the necessary EntireX product data sets to the RPC server STEPLIB.
Concatenate your server application data set to the RPC server STEPLIB.
Insert a valid IMS RESLIB data set high-level qualifier.
Add the EntireX RPC server JCL to your TASKLIB data set.
Modify the sample parameter member CONFIG from EXP109.SRCE.
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.
The RPC executables are distributed prelinked with unresolved external references to z/OS components. To resolve these external references, you need to relink them in your environment. Execute step "Link the IMS RPC server modules" of job EXPINSTI located in the EXX109.JOBS data set.
You can skip this step if you are a new customer or have never used server-side mapping files (Designer files with extension .svm) from previous EntireX versions.
If you are using server-side mapping files (Designer files with extension .svm) at runtime, you need to set up a server-side mapping container.
Execute the EXPSVMAL job located in the EXX109.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 server mapping (VSAM record)
Insert the server-side mapping container (VSAM file) into your RPC Server for IMS'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=< ims.svm.cluster >
Server mapping files with extension .svm are no longer supported at design time by the Designer.
You can still use them at runtime in a server-side mapping container.
All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping
files with extension .cvm.
See When is a Server Mapping File Required?
We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation.
See also Server Mapping Files for COBOL | Server-side Mapping Files |Job Replacement Parameters.
See also Using SSL/TLS with the RPC Server and Job Replacement Parameters.
Under z/OS, 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
EXP109.EXPL data set. The CICS, Batch and IMS examples are unloaded
with separate jobs:
To unload the CICS members to their target data sets and install them in CICS
Unloading the CICS COBOL or CICS PL/I examples and installation into CICS is part of job EXPINSTA
located in the EXX109.JOBS data set.
For CICS, COBOL and PL/I examples are mutually exclusive:
you can only install either the COBOL examples or the PL/I examples into the same CICS.
Depending on the installation of the selected programing language examples into CICS,
the related Generic RPC Services Module (COBOL | PL/I) used by RPC clients is installed too.
CICS definitions for COBOL can be found in member COBDFH, and for PL/I in member PLIDFH of dataset EXP109.SRCE.
For more information refer to the job.
To unload the Batch members to their target data sets
Unloading the Batch COBOL PL/I examples is part of job EXPEXAMP located in the EXX109.JOBS data set.
For more information refer to the job.
To unload the IMS members to their target data sets
Unloading the IMS COBOL examples is part of job EXPINSTI located in the EXX109.JOBS data set.
For more information refer to the job.
To compile and link the examples
Before you can use the examples, you need to build them. Each examples data set has members suffixed with *IGY. These members contain JCL to compile and link the related examples. For detailed information see Delivered Examples for COBOL Wrapper | PL/I Wrapper.
Notes: