Version 9.6
 —  Installation under z/VSE  —

Installing the z/VSE EntireX RPC Servers

This document covers the following topics:


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 Online Maintenance Tool

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.

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.

Top of page

Installing the CICS RPC Server

Step 1: Define an RPC Server Mapping File - VSAMDEF.J (Optional)

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

Note:
Perform this step for Batch RPC Server and CICS RPC Server with different file names.

The SVM file is used at runtime to marshal and unmarshal the RPC data stream. This enables the RPC Server to support special COBOL syntax. See Handling SVM Files. This server-related information is held in a VSAM cluster, which needs to be defined and primed. Each RPC server requires its own SVM file.

If this step is omitted, the RPC server will start without the SVM file. This means that server programs cannot make use of special COBOL syntax.

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.

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 EntireX CICS Online Utility. A preconfigured ERXMAIN phase is delivered in sublibrary EXP960. To alter this configuration, perform the following steps.

  1. Adapt source EMAINGEN.A to fit the environment (see also RPC Servers)

  2. Adapt job ERXMAIN.J to fit 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. 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.

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 CICS Online Utility 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 CICS Online Utility.
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 CICS Online Utility.

Transaction Definitions

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.

Step 4: Start 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:

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 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. See Starting the RPC Server under RPC Online Maintenance Facility in the CICS RPC Server documentation.

Top of page

Installing the Batch RPC Server

Step 1: Define an RPC Server mapping file (SVM File) - VSAMDEF.J (Optional)

(SMA Job I008 / Step 7570)

Note:
Perform this step for Batch RPC Server and CICS RPC Server with different file names.

The SVM file is used at runtime to marshal and unmarshal the RPC data stream. This enables the RPC Server to support special COBOL syntax. See Handling SVM Files. This server-related information is held in a VSAM cluster, which needs to be defined and primed. Each RPC server requires its own SVM file.

If this step is omitted the RPC server will start without the SVM file. This means that server programs cannot make use of special COBOL syntax.

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.

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

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 an RPC Server mapping file (SVM File) - 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.

Top of page

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:

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

Top of page