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 |
Batch RPC Server startup JCL. |
RPCPARM.CFG |
Batch RPC Server 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 |
Batch RPC Server. |
RPCSRVC.PHASE |
CICS RPC Server. |
COBUEX02.CCOBUEX02.CPY |
CICS RPC Server 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 CICS RPC Server default configuration.
|
ERXMAIN.PHASE |
default ERXMAIN control block executable.
|
ERXMAINT.PHASE |
CICS RPC Server online maintenance tool. |
ERXMAPS.PHASE |
CICS RPC Server online maintenance tool 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 z/VSE CICS® RPC Server 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 Batch RPC Server and CICS RPC Server 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 CICS RPC Server parameter
settings. This configuration can be manually maintained by using the EntireX
CICS Online Utility. A preconfigured ERXMAIN phase is delivered in sublibrary
EXP960. To alter this configuration, perform the following steps.
Adapt source EMAINGEN.A to fit the environment (see also
RPC Servers)
Adapt job ERXMAIN.J to fit 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 CICS RPC Server instances. To do so, a new
control block needs to be loaded. The EntireX CICS Online Utility provides the
necessary functionality. Note that the new control block requires a PPT entry
in CICS according to the delivered ERXMAIN control block phase.
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 EntireX CICS Online Utility 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 |
EntireX CICS Online Utility. |
RPCSRVC |
CICS RPC Server. |
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 EntireX CICS Online Utility.
DEFINE TRANSACTION(ERXM) GROUP(EXXERX) PROGRAM(ERXMAINT) TWASIZE(128) DEFINE TRANSACTION(ESRV) GROUP(EXXERX) PROGRAM(RPCSRVC) TWASIZE(128) DEFINE TRANSACTION(EC01) GROUP(ERX) PROGRAM(SQRECLT) TWASIZE(28)
Transaction ERXM is used to start the EntireX CICS Online Utility. The
transaction ESRV is used internally to run EntireX CICS RPC Server.
To start the CICS RPC Server, use the EntireX CICS Online Utility by
entering transaction ERXM. The EntireX CICS Online Utility is command line
oriented. If the default ERXMAIN control block is used, adapt the parameter
settings to fit 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 CICS RPC Server, press PF8.
To stop CICS RPC Server, press PF10.
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 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 CICS RPC server can now be started. See Starting the RPC Server under RPC Online Maintenance Facility in the CICS RPC Server documentation.
The EntireX z/VSE Batch RPC Server 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:
Step 1: Define a Server-side Mapping Container - VSAMDEF.J (Optional)
Step 3: Customize the Batch RPC Server Startup JCL - RUNRPC.J
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 Batch RPC Server and CICS RPC Server 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 Batch RPC Server 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. System Management Hub support and security are 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 * * SMHPOPT=<smhport> port number for System * Management Hub connection * * 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 Batch RPC Server 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 through System
Management Hub.
partition_id
Batch RPC Server 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 batch RPC Server
Run job RUNRPC.J.
To stop the batch RPC Server
Use the console command STOP.
task_id STOPor use System Management Hub functionality.
There 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 Developer's Kit on Windows.
See Client and Server Examples for z/VSE CICS and Client and Server Examples for z/VSE Batch for more information.
You can also download the full set of z/VSE COBOL examples from the Software AG's customer service site Empower.
In Empower, choose .
The examples are provided as AWS tape EXAMPLE.AWS. The tape contains several example sources, JCL and detailed descriptions, and also ready-to-run load modules.
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 CICS RPC Server 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 Batch RPC Server 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