EntireX Version 9.7
 —  Installation under z/OS  —

Installing the EntireX RPC Servers under z/OS

This document covers the following topics:

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


Installing EntireX RPC Servers under CICS

The EntireX z/OS CICS® RPC Server 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:

Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.

Update the CICS Tables

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.

Note:
If you have not extended your DCT (that is, you are using the default values), you must specify the option DCT= in the CICS SYSIN file.

Modify the CICS Startup JCL

The startup JCL for CICS must be modified to include the EXP970.LD00 and EXX970.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.

Build the ERXMAIN Control Block

Adapt the RPC server configuration in the Assembler program EMAINGEN (in EXP970.SRCE) to the customer environment. See ERXMAIN Macro.

Execute "Step 2: Build the ERXMAIN Control Block" of job EXPINSTA located in the EXX970.JOBS data set.

The name of the main control block in earlier versions was fixed as ERXMAIN. As of version 5.1.1, any meaningful name can be chosen. Using this name as input parameter memory for the RPC Online Maintenance Facility means that multiple CICS RPC Servers can be started and monitored in parallel. A fully linked control block named ERXMAIN is delivered in the load library EXP970.LOAD.

See also Verify the Installation of the EntireX RPC Server.

TCP/IP-enable the CICS Region (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.

Install the Server-side Mapping Container for a CICS RPC Server (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.

Execute "Step 7: Allocate and (CSD) define SVM file" of the EXPINSTA job located in the EXX970.JOBS data set. After updating the SVMFILE variable to a suitable name, the following steps are performed:

See also Server-side Mapping Files and Job Replacement Parameters.

Starting the EntireX RPC Server Automatically on CICS Startup (Optional)

Start of instruction setTo start the RPC server automatically on CICS startup

  1. Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTART.

  2. Rebuild the PLT for CICS startup.

Note:
The EXP970.LD00 CICS load library contains a precompiled ERXSTART module with the default settings of the COBOL source member ERXSTART in EXP970.SRCE

Stopping the EntireX RPC Server Automatically on CICS Shutdown (Optional)

Start of instruction setTo stop the RPC server automatically on CICS shutdown

  1. Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTOP into your CICS shutdown table.

  2. Rebuild the PLT for CICS shutdown.

Note:
The EXP970.LD00 CICS load library contains a precompiled ERXSTOP module with the default settings of the COBOL source member ERXSTOP in EXP970.SRCE

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 manually (see Starting the RPC Server under RPC Online Maintenance Facility), or automatically on CICS startup.

Start of instruction setTo start a second RPC server automatically on CICS startup

  1. Copy the default CICS RPC Server autostart definition ERXSTART and give it a unique name, e.g. ERXSTRT2.

    CEDA COPY PROGRAM(ERXSTART) GROUP(ERX) TO(ERX2) AS(ERXSTRT2)
  2. "CEDA Install" the new autostart definition.

  3. Modify the CICS RPC Server PLT startup routine ERXSTART from data set EXP970.SRCE.

  4. Compile and link the modified source and give it the name defined above, e.g. ERXSTRT2.

  5. Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTRT2.

  6. Rebuild the PLT for CICS startup.

Start of instruction setTo stop a second RPC server automatically on CICS shutdown

  1. Copy the default CICS RPC server autostop definition ERXSTOP and give it a unique name, e.g. ERXSTOP2.

    CEDA COPY PROGRAM(ERXSTOP) GROUP(ERX) TO(ERX2) AS(ERXSTOP2)
  2. "CEDA Install" the new autostop definition.

  3. Modify the CICS RPC Server PLT routine ERXSTOP from data set EXP970.SRCE.

  4. Compile and link the modified source and give it the name defined above, e.g. ERXSTOP2.

  5. Insert a new PLT entry DFHPLT TYPE=ENTRY,PROGRAM=ERXSTOP2 into your CICS shutdown table.

  6. Rebuild the PLT for CICS shutdown.

Using SSL or TLS Connections with the CICS RPC Server (Optional)

See Using SSL or TLS with the RPC Server.

Top of page

Installing EntireX RPC Servers under Batch

The EntireX z/OS Batch RPC Server 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. This section covers the following topics:

Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.

Prepare Your Startup JCL

The Batch RPC Server can run as a started task. The installation medium contains the following sample JCL:

Start of instruction setTo prepare your startup JCL

  1. Modify the example started task EXPSRVB of the EXX970.JOBS data set to suit your installation.

  2. Modify the CONFIG DD statement to point to your server configuration file.

  3. Concatenate your server application data set to the RPC server STEPLIB.

  4. Add the EntireX RPC server JCL to your TASKLIB data set.

Customize Your Server Configuration

Modify the sample parameter member CONFIG from EXP970.SRCE. The Batch RPC Server is optimized for use in COBOL environments. Nevertheless, as a minimum the following parameters must be set according to your system environment:

For more information see Configuring the RPC Server.

Using z/OS Privileged Services

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.

Start of instruction setTo install the server invocation module

  1. Copy load module EXXAUTH$ from EntireX load library EXP970.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 EXP970.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.

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

Install the Server-side Mapping Container for a Batch RPC Server (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.

Execute the EXPSVMAL job located in the EXX970.JOBS data set. After updating the SVMFILE variable to a suitable name, the following steps are performed:

Insert the new server-side mapping container (VSAM file) into your Batch 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 >

See also Server-side Mapping Files and Job Replacement Parameters.

Using SSL or TLS Connections with the Batch RPC Server (Optional)

See Using SSL or TLS with the RPC Server.

Top of page

Installing EntireX RPC Servers under IMS

The EntireX z/OS IMS RPC Server 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:

Prerequisites for all EntireX components are described centrally. See z/OS Prerequisites.

Prepare Your Startup JCL

The IMS RPC Server can run as a started task. The installation medium contains the following sample JCL:

Start of instruction setTo prepare your startup JCL

  1. Modify the sample started task EXPSRVI of the EXX970.JOBS data set to suit your installation.

  2. Modify the CONFIG DD statement to point to your server configuration file.

  3. Name a valid PSB in the parameter list for IMSBATCH.

  4. Concatenate the necessary EntireX product data sets to the RPC server STEPLIB.

  5. Concatenate your server application data set to the RPC server STEPLIB.

  6. Insert a valid IMS RESLIB data set high-level qualifier.

  7. Add the EntireX RPC server JCL to your TASKLIB data set.

Customize Your Server Configuration

Modify the sample parameter member CONFIG from EXP970.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:

For more information see Configuring the RPC Server.

Install the Server-side Mapping Container for an IMS RPC Server (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.

Execute the EXPSVMAL job located in the EXX970.JOBS data set. After updating the SVMFILE variable to a suitable name, the following steps are performed:

Insert the new server-side mapping container (VSAM file) into your IMS RPC Server'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 >

See also Server-side Mapping Files and Job Replacement Parameters.

Using SSL or TLS Connections with the IMS RPC Server (Optional)

See also Using SSL or TLS with the RPC Server and Job Replacement Parameters.

Top of page

Extract the EntireX RPC Examples from their Container Data Set

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 EXP970.EXPL data set. The CICS and batch examples are unloaded with separate jobs:

Start of instruction setTo unload the CICS members to their target data sets

Start of instruction setTo unload the Batch members to their target data sets

Start of instruction setTo unload the IMS members to their target data sets

Top of page