Installing the z/VSE EntireX RPC Servers

This document covers the following topics:

For Natural RPC servers, see Setting Up a Natural RPC Environment in your Natural documentation.


Contents of Sublibrary EXP960

Configuration, Startup JCL and Server Executables

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.PHASE
RPCCONS.PHASE
RPCLEST.PHASE
Batch RPC Server.
RPCSRVC.PHASE CICS RPC Server.
COBUEX02.C
COBUEX02.CPY
CICS RPC Server user exit.

CICS RPC Server ERXMAIN Control Block and RPC Online Maintenance Facility

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 RPC Online Maintenance Facility.
ERXMAPS.PHASE RPC Online Maintenance Facility map.

Batch COBOL Client Server Example (CALC)

File Description
CALCRUN.J Batch CALC client startup JCL.
CALCCLT.PHASE Batch CALC client executable.
CALC.PHASE Batch CALC server program.

CICS COBOL Client Server Example (SQUARE)

File Description
SQRECLT.PHASE CICS SQUARE client executable.
SQREMAP.PHASE CICS SQUARE client map.
SQUARE.PHASE CICS SQUARE server program.

Installing the CICS RPC Server

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)

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.

(SMA Job I008 / Step 7570 and Job I025 / Step 7570)

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

SVM File Definition Job Control

* $$ 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

Step 2: Build the ERXMAIN Control Block (Optional)

(SMA Job I070 / Step 7572, 7573)

The ERXMAIN control block holds the EntireX CICS RPC Server 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:

  1. Adapt source EMAINGEN.A to match your environment. See Customizing the RPC Server.

  2. Adapt job ERXMAIN.J to match your environment.

  3. 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. See Installing Multiple EntireX RPC Servers in the same CICS (Optional).

Step 3: Modify CICS Startup JCL

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 RPC Online Maintenance Facility or set up permanently in the ERXMAIN control block (installation Step 2).

Step 4: Update the CICS Tables

(SMA Job I005 / Step 7570)

Add the definitions listed below to your CICS system, either manually or with job CICSDEF.J in sublibrary EXP960.

File Definitions

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)

Program Definitions

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 RPC Online Maintenance Facility.
RPCSRVC CICS RPC Server.
SQRECLT COBOL CICS SQUARE example client.
SQUARE COBOL CICS SQUARE example server.

Mapset Definition

DEFINE MAPSET(ERXMAPS) GROUP(EXP)
DEFINE MAPSET(SQREMAP) GROUP(EXP)

This mapset is used by the EntireX RPC Online Maintenance Facility.

Transaction Definitions

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)

Notes:

  1. Transaction ERXM is used to start the EntireX RPC Online Maintenance Facility. The transaction ESRV is used internally to run EntireX CICS RPC Server.
  2. If required, adapt CICS settings, for example TWASIZE. See CICS Settings.

Step 4: Start CICS RPC Server

To start the CICS RPC Server, use the EntireX RPC Online Maintenance Facility by entering transaction ERXM. 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:

  • TCP Transport Method
    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
  • NET Transport Method
    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.

Installing Multiple EntireX RPC Servers in the same CICS (Optional)

Start of instruction setTo install a second RPC server in the same CICS

  1. 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)
  2. 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)
  3. Add the new group ERX2 to the CICS autoinstall list.

    CEDA ADD GROUP(ERX2) LIST(listname) AFTER(groupname)
  4. 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.

Installing the Batch RPC Server

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)

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.

(SMA Job I008 / Step 7570)

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.

SVM File Definition Job Control

* $$ 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

Step 2: Adapt the RPC Parameter File

(SMA Job I200 / Step 7570)

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:

  • TCP Transport Method
    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
  • NET Transport Method
    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
*
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Step 3: Customize the Batch RPC Server Startup JCL - RUNRPC.J

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 partition_id 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.

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

Step 4: Start Batch RPC Server

Start of instruction setTo start the batch RPC Server

  1. Run job RUNRPC.J.

Start of instruction setTo stop the batch RPC Server

  1. Use the console command STOP.

    task_id STOP

    or use System Management Hub functionality.

Installation Verification

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 Products > Download Components. 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:

CICS COBOL SQUARE Client Server Example (Optional)

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:

graphics/rpc_verify_cics.png

Enter the Broker ID, depending on the transport method used:

  • TCP Transport Method
    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
  • NET Transport Method
    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 PF5 to execute the client.

Batch COBOL CALC Client Server Example (Optional)

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