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:
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:
If the COBOL Wrapper is used, see IMS PSB List.
If the IDL Extractor for COBOL is used, see IMS BMP with Standard Linkage Calling Convention.
For COBOL, the mapping to IMS-specific PCB pointers is done with server mapping files, thus a server-mapping file is always required. See Usage of Server Mapping Files.
If the PL/I Wrapper is used, see PSB List.
If the IDL Extractor for PL/I is used, see Preferences.
For PL/I, the mapping to IMS-specific PCB pointers is done with server interface object(s).
They are generated using the PL/I Wrapper (see Scenario III: Calling an Existing PL/I Server) and provided with the parameter stublib to the IMS RPC Server.
IMS RPC Server provides several services for ease-of-use:
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.
The Deployment Service allows you to deploy server-side mapping files (EntireX Workbench files with extension .svm) interactively using the Server Mapping Deployment Wizard. On the RPC server side, the server-side mapping files are stored in a server-side mapping container (VSAM file). See Server-side Mapping Files in the RPC Server and Deployment Service for configuration information.
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.
The IMS RPC Server can be configured to execute the RPC request impersonated under the RPC client user ID. This means that
for the request execution, the worker thread gets the identity of the RPC client.
This is necessary when accessing (security) protected data sets, for example with the Extractor Service.
The way authentication is carried out can be controlled by the RPC parameter impersonation.
For impersonation value AUTO, the IMS RPC Server does not validate RPC passwords, so you have to make sure the RPC client is
correctly authenticated, either by using a secure EntireX Broker (validation must be against the correct mainframe security
repository where z/OS user IDs are defined) or with your own security implementation.
For impersonation value YES, the IMS RPC Server uses the RPC user ID and password supplied by the RPC client for authentication and impersonation of
the client.
This means that the RPC server validates the password.
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.
There are many situations where the IMS RPC Server requires a server mapping file
to correctly support special COBOL syntax such as REDEFINES,
SIGN LEADING and OCCURS DEPENDING ON clauses, LEVEL-88 fields, etc.
Server mapping files contain COBOL-specific mapping information that is not included in the IDL file, but is needed to successfully call the COBOL server program.
The RPC server marshals 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 server mapping file (Step 2). In this way the COBOL server can be called as expected.
The server mapping files are retrieved as a result of the IDL Extractor for COBOL extraction process and the COBOL Wrapper if a COBOL server is generated. See When is a Server Mapping File Required?.
There are server-side mapping files (EntireX Workbench files with extension .svm) and client-side mapping files (Workbench files with extension .cvm). See Server Mapping Files for COBOL and How to Set the Type of Server Mapping Files.
If you are using server-side mapping files, you need to customize the server-side mapping container with parameter svm.
See Configuring the RPC Server.
Note:
Server mapping files are used for COBOL only.