Version 9.5 SP1
 —  EntireX z/OS IMS RPC Server  —

Introduction to IMS RPC Server

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 document covers the following topics:


Inside the RPC Server

This section covers the following topics:

IMS-specific PCB Pointers

graphics/intro_inside_pcbPointers.png

The IMS RPC Server provides one worker thread. RPC requests are worked off inside the RPC server in the worker thread, which is controlled by a main thread. IMS-specific PCB pointers can be provided as parameters in the linkage section for COBOL and PL/I. They allow you to access the IMS PCB pointer IOPCB, for example to print data or to start an asynchronous transaction and to access IMS databases

IMS-specific PCB pointers are supported with the following programming languages:

Inbuilt Services

IMS RPC Server provides several services for ease-of-use:

Extractor Service

The Extractor Service is a prerequisite for remote extractions with the IDL Extractor for COBOL and IDL Extractor for PL/I. See Extractor Service for more information.

graphics/intro_inside_inbuilt_extractor.png

Deployment Service

The Deployment Service allows you to deploy server mapping files (SVM files) interactively using the Deployment Wizard (see Server Mapping Deployment). On the RPC server side, the SVM files are stored in a VSAM file as the container. See Deployment Service for configuration information.

graphics/intro_inside_inbuilt_deployment.png

SMH Listener Service

With the SMH Listener Service you use the System Management Hub to monitor the RPC server. See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows.

The SMH Service is switched on if the parameter smhport is set. See parameter smhport under Configuring the RPC Server.

graphics/intro_inside_inbuilt_smh.png

Top of page

Impersonation

graphics/intro_impersonation.png

The IMS RPC Server can be configured so that worker threads authenticate the RPC client user ID before execution of the RPC request request with a mainframe security repository (RACF, CA Top Secret or CA ACF2), using the SAF interface. If the RPC user ID is valid, the worker thread gets the identity of the RPC client. This is necessary when accessing (security) protected data sets. The way authentication is carried out can be controlled by the RPC parameter impersonation.

The picture above shows the configuration impersonation=yes.

The lifetime of an impersonated task starts when an open request for an RPC conversation or a non-conversational RPC request is received. It ends when the RPC conversation stops (after a commit operation or timeout) or when the non-conversational RPC request has been performed.

Top of page

Usage of SVM Files

To correctly support special COBOL syntax such as JUSTIFIED, SYNCHRONIZE and OCCURS DEPENDING ON clauses, LEVEL-88 fields, etc., the IMS RPC Server requires in many situations a server mapping file.

SVM files contain COBOL-specific mapping information that is not included in the IDL file and therefore not sent by an EntireX RPC client to the RPC server. See also When is an SVM File Required? under Handling SVM Files.

graphics/intro_useSvm.png

The RPC server marshalls the data in a two-step process: the RPC request coming from the RPC client (Step 1) is completed with COBOL-specific mapping information taken from the SVM file (Step 2). In this way the COBOL server can be called as expected.

The SVM files are retrieved as a result of the IDL Extractor for COBOL extraction process and the COBOL Wrapper if a COBOL server is generated.

You can customize the usage of the SVM file using parameter svm. See Configuring the RPC Server.

Note:
SVM files are used for COBOL only.

Top of page

Automatic Syncpoint Handling

The IMS RPC Server issues a SYNC | ROLB call under the following circumstances:

Top of page

Scenario I: Calling an Existing COBOL Server

Start of instruction setTo call an existing COBOL server

  1. Use the IDL Extractor for COBOL to extract the Software AG IDL and, depending on the complexity of the extraction, also an SVM file. If your COBOL server uses PCB pointers, see IMS-specific PCB Pointers.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

See Client and Server Examples for z/OS IMS BMP for COBOL RPC Server examples.

Top of page

Scenario II: Writing a New COBOL Server

Start of instruction setTo write a new COBOL server

  1. Use the COBOL Wrapper to generate a COBOL server skeleton and, depending on the complexity of the extraction, also an SVM file. Write your COBOL server and proceed as described under Using the COBOL Wrapper for the Server Side. If your COBOL server uses PCB pointers, see IMS-specific PCB Pointers.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

See Client and Server Examples for z/OS IMS BMP for COBOL RPC Server examples.

Top of page

Scenario III: Calling an Existing PL/I Server

Start of instruction setTo call an existing PL/I server

  1. Use the IDL Extractor for PL/I to extract the Software AG IDL.

  2. If your PL/I server uses PCB pointers, generate one or more server interface objects, using the Software AG IDL File extracted in Step 1 above. For more information see Extraction Result in the IDL Extractor for PL/I documentation. See also IMS-specific PCB Pointers.

  3. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

See Client and Server Examples for z/OS IMS BMP for PL/I RPC Server examples.

Top of page

Scenario IV: Writing a New PL/I Server

Start of instruction setTo write a new PL/I server

  1. Use the PL/I Wrapper to generate a PL/I server skeleton. Write your PL/I server and proceed as described under Using the PL/I Wrapper for the Server Side. If your PL/I server uses PCB pointers, see IMS-specific PCB Pointers.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

See Client and Server Examples for z/OS IMS BMP for PL/I RPC Server examples.

Top of page

Scenario V: Writing a New C Server

Start of instruction setTo write a new C server

  1. Use the C Wrapper to generate a C server skeleton and a C server interface object. Write your C server and proceed as described under Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000/OSD, IBM i).

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

Top of page

Scenario VI: Writing a New Assembler Server

Start of instruction setTo write a new Assembler (IBM 370) server

  1. Build an RPC server in Assembler. Here are some hints:

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

Top of page

Returning Application Error Codes from a Server to a Client

See Returning Application Errors from a Server under z/OS IMS to a Client in the COBOL Wrapper documentation under Writing Applications with the COBOL Wrapper.

Top of page