This document covers the following topics:
For Natural RPC servers, see Setting Up a Natural RPC Environment in your Natural documentation.
| File | Description |
|---|---|
RUNRPC.J |
RPC Server for Batch startup JCL. |
RPCPARM.CFG |
RPC Server for Batch configuration file. |
CICSDEF.J |
CICS CSD definitions JCL. |
VSAMDEF.J |
server mapping file VSAM definition JCL. |
SVMPRIME.PHASE |
server mapping file VSAM prime utility. |
RPCSRVB.PHASERPCCONS.PHASERPCLEST.PHASE |
RPC Server for Batch. |
RPCSRVC.PHASE |
RPC Server for CICS. |
COBUEX02.CCOBUEX02.CPY |
RPC Server for CICS user exit. |
| File | Description |
|---|---|
ERXMAIN.J |
Assemble and LNKEDT JCL.
|
EMAINGEN.A |
ERXMAIN control block macro.
|
ERXMAIN.A |
Assembler source to generate the ERXMAIN control block
containing the RPC Server for CICS default configuration.
|
ERXMAIN.PHASE |
default ERXMAIN control block executable.
|
ERXMAINT.PHASE |
RPC Online Maintenance Facility. |
ERXMAPS.PHASE |
RPC Online Maintenance Facility map. |
| File | Description |
|---|---|
CALCRUN.J |
Batch CALC client startup JCL. |
CALCCLT.PHASE |
Batch CALC client executable. |
CALC.PHASE |
Batch CALC server program. |
| File | Description |
|---|---|
SQRECLT.PHASE |
CICS SQUARE client executable. |
SQREMAP.PHASE |
CICS SQUARE client map. |
SQUARE.PHASE |
CICS SQUARE server program. |
The EntireX RPC Server for z/VSE CICS® allows standard RPC clients to communicate with RPC servers on the operating system z/VSE under CICS. It supports the programming language COBOL. This section covers the following topics:
Step 1: Define a Server-side Mapping Container - VSAMDEF.J (Optional)
Installing Multiple EntireX RPC Servers in the same CICS (Optional)
If you are using or plan to use server-side mapping files, you need to set up a server-side mapping container. A server-side mapping file is an EntireX Workbench file with extension .svm. See Server Mapping Files for COBOL. If this step is omitted, the RPC server will start without the server-side mapping container. This means that server programs cannot make use of special COBOL syntax and features. See When is a Server Mapping File Required? in the EntireX Workbench documentation.
The server-side mapping container stores the content of server-side mapping files, which are used at runtime to marshal and unmarshal the RPC data stream. This enables the RPC server to support special COBOL syntax. The server-side mapping container is technically a VSAM file that needs to be defined and initialized.
Note:
Perform this step for RPC Server for Batch and RPC Server for CICS with
different file names.
Customize and run job VSAMDEF.J. Specify the desired VSAM KSDS cluster
name, catalog and Catalog ID. These are marked by the placeholders
"<...>" in VSAMDEF.J.
See also Server-side Mapping Files
* $$ JOB JNM=VSAMDEF,CLASS=H,DISP=D
* $$ LST CLASS=0,DISP=D
// JOB VSAMDEF
*
* DEFINE AND INITIALIZE THE RPC SVM FILE VSAM CLUSTER
*
// EXEC IDCAMS,SIZE=AUTO
/* ------------------------------------------------------------ */
/* DELETE SERVER MAPPING VSAM CLUSTER */
/* ------------------------------------------------------------ */
DELETE (<vsam_ksds_cluster_name>) CL NOERASE PURGE -
CATALOG(<catalog_name>)
SET MAXCC = 0
SET LASTCC = 0
/* ------------------------------------------------------------ */
/* DEFINE SERVER MAPPING VSAM CLUSTER */
/* ------------------------------------------------------------ */
DEFINE CLUSTER -
( NAME(<vsam_ksds_cluster_name>) -
RECORDSIZE(1024 16384) -
RECORDS(1000 1000) -
KEYS(255 0) -
INDEXED -
SHR(2,3) -
VOL(<volume>) -
) -
DATA(NAME(<vsam_ksds_cluster_name>.DATA)) -
INDEX(NAME(<vsam_ksds_cluster_name>.INDEX)) -
CATALOG(<catalog_name>)
/*
/* ------------------------------------------------------------- */
/* INITIALIZE SERVER MAPPING VSAM CLUSTER */
/* ------------------------------------------------------------- */
// DLBL ERXSVM,'<vsam_ksds_cluster_name>',0,VSAM,CAT=<catalog>
// LIBDEF *,SEARCH=(SAGLIB.EXP960),TEMP
// EXEC SVMPRIME,SIZE=AUTO
/*
/&
* $$ EOJ
The ERXMAIN control block holds the EntireX RPC Server for CICS parameter
settings. This configuration can be manually maintained by using the RPC Online Maintenance Facility.
A preconfigured ERXMAIN phase is delivered in sublibrary
EXP960. To alter this configuration, perform the following steps:
Adapt source EMAINGEN.A to match your environment. See Customizing the RPC Server.
Adapt job ERXMAIN.J to match your environment.
Run job ERXMAIN.J.
Running job ERXMAIN.J assembles macro ERXMAIN and links a new ERXMAIN
phase with the preferred default settings.
The name of the phase may be altered within job ERXMAIN.J. This allows
you to run multiple EntireX RPC Server for CICS instances. See Installing Multiple EntireX RPC Servers in the same CICS (Optional).
To enable CICS to find the various programs defined to the PPT (installation step 4), the CICS startup JCL needs to be modified to include the sublibraries EXP960 and EXX960 into the DFHRPL chain.
Additionally, if installation Step 1 was performed, a DLBL statement, as shown below, needs to be added for the VSAM KSDS cluster of the SVM file.
// DLBL ERXSVM,'<vsam_ksds_cluster_name>',0,VSAM,CAT=<catalog>
Each RPC Server instance running in same CICS partition requires its own SVM file, that is, its own DLBL entry. You can choose any DLBL name. ERXSVM is the default. It can be altered manually in the RPC Online Maintenance Facility (see RPC Online Maintenance Facility in the RPC Server for CICS documentation) or set up permanently in the ERXMAIN control block (installation Step 2).
Add the definitions listed below to your CICS system, either manually or
with job CICSDEF.J in
sublibrary EXP960.
If installation Step 1 was performed, the SVM file VSAM KSDS cluster
needs to be defined. Replace the <vsam_ksds_cluster_name> in the
DEFINE statement.
DEFINE FILE(ERXSVM) GROUP(EXX) DSNAME(<vsam_ksds_cluster_name>) DESCRIPTION(ENTIREX RPC SVM FILE) LSRPOOLID(NONE) ADD(YES) BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES) RECORDSIZE(16384) KEYLENGTH(255) STRINGS(2) DATABUFFERS(201) INDEXBUFFERS(200)
DEFINE PROGRAM(BKIMC) GROUP(ERX) LANGUAGE(ASSEMBLER) DEFINE PROGRAM(BROKERC) GROUP(ERX) LANGUAGE(C) DEFINE PROGRAM(ERXMAIN) GROUP(ERX) LANGUAGE(ASSEMBLER) DEFINE PROGRAM(ERXMAINT) GROUP(ERX) LANGUAGE(C) DEFINE PROGRAM(RPCSRVC) GROUP(ERX) LANGUAGE(C) DEFINE PROGRAM(SQRECLT) GROUP(ERX) LANGUAGE(COBOL) DEFINE PROGRAM(SQUARE) GROUP(ERX) LANGUAGE(COBOL)
The programs in the definitions above are used for following purposes:
| Program | Purpose |
|---|---|
BKIMC |
CICS Broker stub interface. |
BROKERC |
CICS Broker stub. |
ERXMAIN |
Control block. |
ERXMAINT |
RPC Online Maintenance Facility. |
RPCSRVC |
RPC Server for CICS. |
SQRECLT |
COBOL CICS SQUARE example client.
|
SQUARE |
COBOL CICS SQUARE example server.
|
DEFINE MAPSET(ERXMAPS) GROUP(EXP) DEFINE MAPSET(SQREMAP) GROUP(EXP)
This mapset is used by the RPC Online Maintenance Facility. See RPC Online Maintenance Facility in the RPC Server for CICS documentation.
DEFINE TRANSACTION(ERXM) GROUP(EXXERX) PROGRAM(ERXMAINT) TWASIZE(28) DEFINE TRANSACTION(ESRV) GROUP(EXXERX) PROGRAM(RPCSRVC) TWASIZE(28) 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.
Note:
If required, adapt CICS settings, for example TWASIZE. See CICS Settings.
To start the RPC Server for CICS, use the RPC Online Maintenance Facility by
entering transaction ERXM (see RPC Online Maintenance Facility in the RPC Server for CICS documentation).
The RPC Online Maintenance Facility is command-line
oriented. If the default ERXMAIN control block is used, adapt the parameter
settings to match the environment - especially the Broker ID - by entering:
BROKER=<Broker ID>
Depending on the communication method, the Broker ID can be specified in two formats:
ip:port:TCP
| where | ip |
is the address or DNS host name, |
port |
is the port number that EntireX Broker is listening on, and | |
TCP |
is the protocol name |
ETBnnn:SVCmmm:NET
| where | nnn |
is the ID under which EntireX Broker is connected to the Adabas ID table, |
mmm |
is the SVC number under which the Adabas ID table can be accessed, and | |
NET |
is the protocol name |
To start RPC Server for CICS, press PF8.
To stop RPC Server for CICS, press PF10.
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. See Starting the RPC Server under RPC Online Maintenance Facility in the RPC Server for CICS documentation.
The EntireX RPC Server for z/VSE Batch allows standard RPC clients to communicate with RPC servers on the operating system z/VSE under Batch. It supports the programming language COBOL and works together with the COBOL Wrapper and IDL Extractor for COBOL. This section covers the following topics:
If you are using or plan to use server-side mapping files, you need to set up a server-side mapping container. A server-side mapping file is an EntireX Workbench file with extension .svm. See Server Mapping Files for COBOL. If this step is omitted, the RPC server will start without the server-side mapping container. This means that server programs cannot make use of special COBOL syntax and features. See When is a Server Mapping File Required? in the EntireX Workbench documentation.
The server-side mapping container stores the content of server-side mapping files, which are used at runtime to marshal and unmarshal the RPC data stream. This enables the RPC server to support special COBOL syntax. The server-side mapping container is technically a VSAM file that needs to be defined and initialized.
Note:
Perform this step for RPC Server for Batch and RPC Server for CICS with
different file names.
Customize and run job VSAMDEF.J. Specify the desired VSAM KSDS cluster
name, catalog, catalog ID and volume. These are marked by the placeholders
"<...>" in VSAMDEF.J.
See also Server-side Mapping Files.
* $$ JOB JNM=VSAMDEF,CLASS=H,DISP=D
* $$ LST CLASS=0,DISP=D
// JOB VSAMDEF
*
* DEFINE AND INITIALIZE THE RPC server mapping file VSAM CLUSTER
*
// EXEC IDCAMS,SIZE=AUTO
/* ------------------------------------------------------------ */
/* DELETE SERVER MAPPING VSAM CLUSTER */
/* ------------------------------------------------------------ */
DELETE (<vsam_ksds_cluster_name>) CL NOERASE PURGE -
CATALOG(<catalog_name>)
SET MAXCC = 0
SET LASTCC = 0
/* ------------------------------------------------------------ */
/* DEFINE SERVER MAPPING VSAM CLUSTER */
/* ------------------------------------------------------------ */
DEFINE CLUSTER -
( NAME(<vsam_ksds_cluster_name>) -
RECORDSIZE(1024 16384) -
RECORDS(1000 1000) -
KEYS(255 0) -
INDEXED -
SHR(2,3) -
VOL(<volume>) -
) -
DATA(NAME(<vsam_ksds_cluster_name>.DATA)) -
INDEX(NAME(<vsam_ksds_cluster_name>.INDEX)) -
CATALOG(<catalog_name>)
/*
/* ------------------------------------------------------------- */
/* INITIALIZE SERVER MAPPING VSAM CLUSTER */
/* ------------------------------------------------------------- */
// DLBL ERXSVM,'<vsam_ksds_cluster_name>',0,VSAM,CAT=<catalog>
// LIBDEF *,SEARCH=(SAGLIB.EXP960),TEMP
// EXEC SVMPRIME,SIZE=AUTO
/*
/&
* $$ EOJ
RPCPARM.CFG in sublibrary EXP960 contains the RPC server parameters. If
the default settings are used, only the BROKERID parameter needs to be set up
according to your environment. The RPC Server for Batch will then run in a default
configuration with two permanent worker tasks (up to 16 replicates are
possible) and the deployment service
turned off. See Server Mapping Deployment Wizard.
It will register at EntireX Broker as service SRV1, class RPC and
service CALLNAT, which corresponds to the settings in the delivered Broker
attribute file. Security is turned off. See
also Configuring the RPC Server.
Depending on the communication method, the Broker ID can be specified in two formats:
ip:port:TCP
| where | ip |
is the address or DNS host name, |
port |
is the port number that EntireX Broker is listening on, and | |
TCP |
is the protocol name |
ETBnnn:SVCmmm:NET
| where | nnn |
is the ID under which EntireX Broker is connected to the Adabas ID table, |
mmm |
is the SVC number under which the Adabas ID table can be accessed, and | |
NET |
is the protocol name |
To turn on the Deployment Service, a built-in service of the RPC server, (see Deployment Service)
uncomment the line shown below. This will allow deploying information from the EntireX Workbench into the SVM file. Additionally, the SVM file needs to be installed;
See Step 1: Define a Server-side Mapping Container - VSAMDEF.J (Optional).
* DEPLOYMENT=YES register Deployment Service
The default configuration file RPCPARM.CFG:
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * EntireX RPC Server configuration file * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * EntireX Broker Parameters * * * * * * * * * * * * * * BROKERID=<ip>:<port>:TCP Broker ID if TCP/IP is used * BROKERID=ETB<nnn>:SVC<ccc>:NET Broker ID if XCOM is used * SERVERNAME=SRV1 SERVICE=CALLNAT CLASS=RPC * TIMEOUT=30 * * USERID=ERXUSER * PASSWORD=PASSWORD * LOGON=YES * * * * * * * * * * * EntireX RPC Server Parameter * * * * * * * * * * * * RESTARTCYCLES=3 try three times (1 minute * interval) when EntireX * Broker is unavailable * * DEPLOYMENT=YES register Deployment Service * * TRACELEVEL=ADVANCED NONE, STANDARD or ADVANCED * * ETBLNK=BROKER required if Relay Manager * communication is desired * * Start up a fixed number of workers (up to 16 workers possible) * --------------------------------------------------------------------- MINWORKERS=2 number of parallel server * replicates started * MAXWORKERS will be ignored ENDWORKERS=NEVER stop never * * * Balance the load of available workers * --------------------------------------------------------------------- * MINWORKERS=0 keep alive at least one * replicate * MAXWORKERS=<n> n .. maximum of parallel * server replicates * ENDWORKERS=IMMEDIATLY stop immediately after * request worked off * * Balance the load of available workers * --------------------------------------------------------------------- * MINWORKERS=1 keep alive at least one * replicate * MAXWORKERS=<n> n..maximum of parallel * server replicates * ENDWORKERS=TIMEOUT stop after timeout received * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Adapt the RPC Server for Batch startup JCL RUNRPC.J to fit your
environment.
If installation Step 1 was performed, include the VSAM KSDS Cluster name of the SVM file and uncomment following line:
/* / DLBL ERXSVM,'<vsam_ksds_cluster_name>',0,VSAM,CAT=<catalog>
Insert the sublibraries containing your own server programs into the
LIBDEF search chain.
If you wish to suppress the console prompt, uncomment the UPSI statement.
/* / UPSI 00000001
Note:
In the current RPC Server version, the UPSI setting suppresses the
startup of the RPC Server Console task. In that case an MSG
command will not have any effect as there is no AR routine present. Stopping
the RPC Server is then only possible with partition_idETBCMD.
RPC Server for Batch Job Control:
* $$ JOB JNM=RUNRPC,CLASS=0,DISP=D
* $$ LST CLASS=A,DISP=H
// JOB RUNRPC
*
* BATCH RPC SERVER START UP JOB CONTROL
*
// OPTION DUMP,NOSYSDUMP
/*
/* TURN OFF RPC SERVER CONSOLE PROMPT
/*
/* / UPSI 00000001
/*
/* SERVER MAPPING FILE
/*
/* / DLBL ERXSVM,'<vsam_ksds_cluster_name>',0,VSAM,CAT=<catalog>
/*
// LIBDEF PHASE,SEARCH=(SAGLIB.EXP960, +
SAGLIB.EXX960, +
SAGLIB.WAL826),TEMP
/*
// EXEC RPCSRVB,SIZE=AUTO,PARM='CFG=DD:SAGLIB.EXP960(RPCPARM.CFG)'
/*
/&
* $$ EOJ
To start the RPC Server for Batch
Run job RUNRPC.J.
To stop the RPC Server for Batch
Use the following console command:
task_id STOPThere are two COBOL client/server examples delivered as executables with the RPC servers, one for use in Batch (CALC),
the other for CICS (SQUARE). These examples are useful for verifying the RPC Server installation.
They are a subset of the z/VSE COBOL examples provided with EntireX on Windows.
See Client and Server Examples for z/VSE CICS and Client and Server Examples for z/VSE Batch for more information.
This section covers the following topics:
This COBOL client server example is delivered as executable and ready to run. Its purpose is to verify the RPC Server for CICS installation.
Ensure following CICS transaction and programs are defined:
DEFINE TRANSACTION(EC01) GROUP(ERX) PROGRAM(SQRECLT) TWASIZE(28) DEFINE PROGRAM(SQRECLT) GROUP(ERX) LANGUAGE(COBOL) DEFINE PROGRAM(SQUARE) GROUP(ERX) LANGUAGE(COBOL)
Executing the transaction EC01 will display following CICS map:
Enter the Broker ID, depending on the transport method used:
ip:port:TCP
| where | ip |
is the address or DNS host name, |
port |
is the port number that EntireX Broker is listening on, and | |
TCP |
is the protocol name |
ETBnnn:SVCmmm:NET
| where | nnn |
is the ID under which EntireX Broker is connected to the Adabas ID table, |
mmm |
is the SVC number under which the Adabas ID table can be accessed, and | |
NET |
is the protocol name |
Enter the BROKER-ID and press to execute the client.
This COBOL client server example is delivered as executable and ready to run. Its purpose is to verify the RPC Server for Batch installation.
Customize CALCRUN.J to fit the environment. Set up BROKERID as described under CICS COBOL SQUARE Client Server Example (Optional).
Run job CALCRUN.J.
* $$ JOB JNM=CALCRUN,CLASS=0,DISP=D
* $$ LST CLASS=A,DISP=H
// JOB CALCRUN
*
* CALC EXAMPLE CLIENT START UP JOB CONTROL
*
// LIBDEF PHASE,SEARCH=(SAGLIB.EXP960, +
SAGLIB.EXX960, +
SAGLIB.WAL826),TEMP
// EXEC CALCCLT,SIZE=AUTO
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Input Parameter *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
BROKERID <ipaddr>:<port>:TCP *
* BROKERID ETB<nnnnn>::NET *
* USERID <userid> *
* PASSWORD <password> *
CLASS RPC *
SERVER SRV1 *
SERVICE CALLNAT *
LOGON *
CALC + 00012345 00067890 *
CALC - 00067890 00012345 *
CALC * 00001234 00005678 *
CALC / 00005678 00001234 *
CALC % 00005678 00001234 *
END *
/*
/&
* $$ EOJ