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 following elements are used for setting up the IMS RPC Server:
The name of the delivered example configuration file is
CONFIGI (see source library EXP970.SRCE).
The configuration file is specified as a DD definition with a user-defined DD name in the Started Task JCL. The configuration file contains the configuration for the IMS RPC Server.
The following settings are important:
connection information such as broker ID, server address (class, name, service)
location and usage of server-side mapping container, see Usage of Server Mapping Files
scalability parameters
trace settings
etc.
For more information see Configuring the RPC Server.
Depending on the feature the IMS RPC Server needs to support (see table below) additional runtime options for IBM's Language Environment need to be set. For a full description of LE runtime options, see z/OS V1R4.0 Lang Env Prog Guide.
| Feature | LE Runtime Options | Description |
|---|---|---|
| SSL/TLS connections | POSIX(ON) |
If not specified, TCP or NET connections are supported. |
| Call RPC server programs with AMODE 24 as well | ALL31(OFF),STACK(,,BELOW) |
If not specified, AMODE 31 is supported. |
Note:
(1) Set internally by the IMS RPC Server and cannot be changed.
There are various ways to specify LE runtime options, for example during installation; using JCL; using CSECT CEEUOPT (for application-specific LE runtime options) linked to the RPC Server; etc.
We recommend you use the IBM standard approach with CEEOPTS DD statement in the started task JCL. See Started Task JCL for this purpose.
Add the following lines to your started task JCL:
//... //CEEOPTS DD * ALL31(OFF),STACK(,,BELOW) /* //..
The example above uses an in-stream data set to configure ALL31(OFF),STACK(,,BELOW) to allow calling of 24-bit and 31-bit programs and configure RPTOPTS(ON) to list all used LE runtime options to SYSOUT.
The name of the started task is EXPSRVI
(see EntireX job library EXX970.JOBS).
The started task contains the following:
the target server libraries of the called COBOL or PL/I server
for PL/I, if IMS-specific PCB pointers are used, the stub library; see stublib
the configuration file used; see Configuration File; specified as a DD definition with a user-defined DD name as RPC server startup argument CFG:
CFG=DD:ddname
Under IMS, server startup arguments are passed with the DD name ERXPARMS.
So to pass the argument for the example above, you need to specify a data set in the DD definition for ERXPARMS.
This data set needs to have one line containing the CFG argument, for example CFG=DD:CONFIGI.
//* //G.ERXPARMS DD * ERXPARMS - DEFINE ONLY THE CONFIG DD NAME HERE CFG=DD:CONFIGI
LE runtime options used; see IBM LE Runtime Options
etc.
The following rules apply:
In the configuration file:
Comments must be on a separate line.
Comment lines can begin with '*', '/' and ';'.
Empty lines are ignored.
Headings in square brackets [<topic>] are ignored.
Keywords are not case-sensitive.
Underscored letters in a parameter indicate the minimum number of letters that can be used for an abbreviated command.
For example, in brokerid=localhost,
brok is the minimum number of letters that
can be used as an abbreviation, i.e. the commands/parameters broker=localhost
and brok=localhost are equivalents.
| Parameter | Default | Values | Req/ Opt |
|||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
brokerid |
localhost |
Broker ID used by the server. See Using the Broker ID in Applications.
Example: |
R | |||||||||||||||||||
ceeoptions |
Allows you to change IBM's LE runtime options. This parameter is deprecated. See IBM LE Runtime Options for how to set the LE runtime options. | O | ||||||||||||||||||||
class |
RPC |
Server class part of the server address used by the
server. The server address must be defined as a service in the broker attribute file (see Service-specific Attributes under Broker Attributes).
Case-sensitive, up to 32 characters. Corresponds to CLASS.
Example: |
R | |||||||||||||||||||
codepage |
no codepage transferred | Depending on the internationalization approach, the codepage (locale string)
where incoming data is provided to the COBOL server. Conversely, the COBOL server must provide outgoing data in the
given codepage, otherwise unpredictable results occur. See What is the Best Internationalization Approach to use? under Internationalization with EntireX for information
on which internationalization approach requires a codepage (locale string).
By default, no codepage is transferred to the broker. For the most popular internationalization approach, ICU Conversion, the correct codepage (locale string) must be provided. This means it must:
Example: |
||||||||||||||||||||
compresslevel |
N |
Enforce compression when data is transferred between
broker and server. See Data Compression in EntireX Broker.
Example: |
O | |||||||||||||||||||
deployment |
NO |
Activates the deployment service, see Deployment Service. Required to
use the Server Mapping Deployment Wizard. See Server Mapping Deployment Wizard in the EntireX Workbench documentation.
Example: |
O | |||||||||||||||||||
encryptionlevel |
0 | Enforce encryption when data is transferred between
client and server. Requires EntireX Security. See ENCRYPTION-LEVEL under Broker ACI Fields.
Example: |
O | |||||||||||||||||||
etblnk |
BROKER |
Define the broker stub to be used. See Administering Broker Stubs for available stubs.
Example: |
O | |||||||||||||||||||
extractor |
NO |
The extractor service is a prerequisite
for remote extractions. See Extractor Service.
Example: |
O | |||||||||||||||||||
impersonation |
NO |
|
O | |||||||||||||||||||
library |
no default | library = search-logic [- library] where search-logic is one of FIX(dllname) | PREFIX(prefix) | PREFIX()
This parameter applies to programming language C only. Do not set if other programming languages for RPC server are used.
Example Example |
O | |||||||||||||||||||
logon |
YES |
Execute broker functions LOGON/LOGOFF in worker
threads. Must match the setting of the broker attribute
AUTOLOGON. Reliable RPC requires logon set to YES. See Reliable RPC.
Example: |
O | |||||||||||||||||||
marshalling |
COBOL |
|
O | |||||||||||||||||||
password |
no default | Password for broker logon. Case-sensitive, up to 32
characters. For more information see broker ACI control block field
PASSWORD.
Example: |
O | |||||||||||||||||||
restartcycles |
15 | Number of restart attempts if the broker is not
available. This can be used to keep the IMS RPC Server running while
the broker is down for a short time. A restart cycle will be
repeated at an interval which is calculated as follows:
When the number of cycles is reached and a connection to the broker is not possible, the RPC server stops. Example: |
O | |||||||||||||||||||
return_code |
NO |
Enable application-specific errors.return_code=(NO|YES)
Example: |
O | |||||||||||||||||||
runoption |
no default | This parameter is for special purposes. It provides the IMS RPC Server with additional information.
The runoptions are normally set to meet the platform's requirements. Set this parameter only if a support representative provides
you with an option and asks you to do so. The parameter can be defined multiple times.
Example: |
O | |||||||||||||||||||
servername |
SRV1 |
Server name part of the server address used by the server.
The server address must be defined as a service in the broker attribute file.
See Service-specific Attributes under Broker Attributes.
Case-sensitive, up to 32 characters.
Corresponds to SERVER of the broker attribute file.
Example: |
R | |||||||||||||||||||
service |
CALLNAT |
Service part of the server address used by the server.
The server address must be defined as a service in the broker attribute file.
See Service-specific Attributes under Broker Attributes.
Case-sensitive, up to 32 characters.
Corresponds to SERVICE attribute of the broker attribute file.
Example: |
R | |||||||||||||||||||
smhport |
0 | The port where the server listens for commands from
the System Management Hub (SMH). If this port is 0 (default), no port is used and
management by the SMH is disabled.
Example: |
O | |||||||||||||||||||
ssl_file |
no default | Set the SSL parameters. See Using SSL or TLS with the RPC Server for examples and more information. | O | |||||||||||||||||||
stublib |
no default | For PL/I server if its interface has IMS-specific PCB Pointers
to access IMS databases. Provide the DD name of the library where the PL/I server interface object(s) are located.
Not required for COBOL or if the interface of your PL/I server does not have IMS-specific PCB pointers.
Example: For the example above, define the DD name //PLISTUBS DD DISP=SHR,DSN=<plistubs> |
O | |||||||||||||||||||
svm |
ERXSVM |
Usage and location of server-side mapping files; see Server-side Mapping Files in the RPC Server.
If no svm parameter is given, the RPC server tries to open the
server-side mapping container using DD name ERXSVM.
If this DD name is not available, no server-side mapping files are used.
If you use server-side mapping files, the server-side mapping container must be installed and configured;
see Install the Server-side Mapping Container for an IMS RPC Server (Optional) in the z/OS Installation documentation.
There are also client-side mapping files that do not require configuration here; see
Server Mapping Files in the EntireX Workbench in the EntireX Workbench documentation.
Example: See also Usage of Server Mapping Files. |
O | |||||||||||||||||||
timeout |
60 | Timeout in seconds,
used by the server to wait for broker requests. See broker ACI control block field
WAIT for more information. Also influences restartcycles.
Example: |
O | |||||||||||||||||||
tracedestination |
DD:ERXTRACE |
The name of the destination file for trace output.
Example: The DD name //MYTRACE DD DISP=SHR,DSN=<rpctrace-file> |
O | |||||||||||||||||||
tracelevel |
None |
Trace level for the server. See also Activating Tracing for the RPC Server.
tracelevel = None | Standard | Advanced | Support
Example: |
O | |||||||||||||||||||
traceoption |
None |
Additional trace option if trace is active.
Example: |
O | |||||||||||||||||||
userid |
ERX-SRV |
Used to identify the server to the broker.
See broker ACI control block field USER-ID.
Case-sensitive, up to 32 characters.
Example: |
R | |||||||||||||||||||
The IDL library and IDL program
names that come from RPC client are used to locate the RPC server.
See library-definition and program-definition.
This two-level concept (library and program) has to be mapped to the IMS RPC Server environment.
Different mechanisms are used depending on the language:
The approach used to derive the z/OS module name for the RPC server depends on whether server mapping is used or not. See Usage of Server Mapping Files for an introduction.
If the RPC client sends a client-side type of server mapping with the RPC request, this server mapping is used first.
If no server mapping is available from step 1 above, and if server-side type of server mapping is used, the IDL library and IDL program names are used to form a key to locate the server mapping in the server-side mapping container. If a server mapping is found, this is then used.
If a server mapping is available from step 1 or 2 above, the z/OS module name of the RPC server is derived from this mapping. In this case the IDL program name can be different to the z/OS module name if it is renamed during wrapping process (see Customize Automatically Generated Server Names) or during the extraction process in the COBOL Mapping Editor.
If no server mapping is used at all, the IDL program name is used as the z/OS module name of the RPC server (the IDL library name is ignored).
To use the IMS RPC Server with COBOL
Make sure that all z/OS modules called as RPC servers
are compiled with IBM's Language Environment (see z/OS V1R4.0 Lang Env Prog Guide for more information)
use COBOL calling conventions
can be called dynamically ("fetched") from any Language Environment program
are accessible through the IMS RPC Server started task JCL STEPLIB concatenation. See Started Task JCL.
Configure the parameter marshalling for COBOL, for example:
marshalling=COBOL
Configure the parameter svm depending on whether
server-side mapping files are used or not. See Usage of Server Mapping Files.
See also Scenario I: Calling an Existing COBOL Server or Scenario II: Writing a New COBOL Server.
The approaches needed to derive the dynamic-link library (DLL) names for the RPC server are more complex for C, for the following reasons:
the limitation of 8 characters per (physical) member (DLL name in PDSE)
the maximum length of 128 characters per IDL library name (see Rules for Coding Library, Library Alias, Program, Program Alias and Structure Names under Software AG IDL File).
Either you restrict yourself in short IDL library names (up to 8 characters) and use the flexible PREFIX configuration,
or, if you need independence from the IDL library length and names, use the FIX configuration.
The parameter library is used for this purpose.
To use the IMS RPC Server with C
Make sure all dynamic-link libraries (DLLs) called as RPC servers and client interface objects are accessible through the
IMS RPC Server started task JCL STEPLIB concatenation. See Started Task JCL.
Configure the parameter marshalling for C, for example marshalling=C.
Configure the parameter library either with the FIX configuration or PREFIX configuration, depending on how you have built your DLLs. See Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000/OSD, IBM i).
See also Scenario V: Writing a New C Server.
There is a simple mechanism to derive the RPC server z/OS module name:
The IDL program name is used as the z/OS module name
The IDL library name is not used.
To use the IMS RPC Server with Assembler
Make sure all z/OS modules called as RPC Servers
are accessible through the IMS RPC Server started task JCL STEPLIB concatenation.
See Started Task JCL.
Use PL/I or COBOL calling conventions. Configure the parameter marshalling for PL/I or COBOL.
See also Scenario VI: Writing a New Assembler Server.
The IMS RPC Server supports certificates stored in RACF as keyrings. There are two ways of specifying the RACF keyring and other SSL or TLS parameters, depending on the complexity of the parameters:
as part of the Broker ID for short parameters, the simplest way
using the SSL file, a text file containing more complex parameters.
As an alternative, you can use for this purpose IBM's Application Transparent Transport Layer Security (AT-TLS), where the establishment of the SSL or TLS connection is pushed down the stack into the TCP layer.
This section covers the following topics:
Specifying the SSL or TLS Parameters as Part of the Broker ID
Using IBM's Application Transparent Transport Layer Security (AT-TLS)
For more information, see SSL or TLS and Certificates with EntireX.
To specify the SSL or TLS parameters as part of the Broker ID
In the Started Task JCL set the LE runtime option POSIX(ON), see IBM LE Runtime Options.
Add the RACF keyring <user-id>/<ring-name> and other SSL or TLS parameters to the server parameter brokerid in the Configuration File. SSL or TLS parameters are separated by ampersand (&).
Example with Transport-method-style Broker ID:
ETB024:1609:SSL?TRUST_STORE=<user-id>/<ring-name>&VERIFY_SERVER=N
Example with URL-style Broker ID:
ssl://localhost:2010?TRUST_STORE=<user-id>/<ring-name>&VERIFY_SERVER=N
Make sure the target the IMS RPC Server connects to is prepared for SSL/TLS connections as well. See the following sections:
To specify the SSL or TLS parameters in the SSL file
In the Started Task JCL set the LE runtime option POSIX(ON), see IBM LE Runtime Options.
Define a so-called SSL file in text format (for example as a PDS member) with the RACF keyring <user-id>/<ring-name> and other SSL or TLS parameters.
Example:
TRUST_STORE=<user-id>/<ring-name> VERIFY_SERVER=N
Note:
Each line in the SSL file must be terminated with hexadecimal zero.
In the Configuration File, define a DDNAME to be used in the Started Task JCL to enable the IMS RPC Server to access the SSL file defined in Step 2 above.
Example:
... SS_FILE=DD:MYSSL ...
Add a DD statement to the Started Task JCL using the DDNAME defined in Step 3 above to point to the SSL file defined in Step 2 above.
Example:
//... //MYSSL DD DISP=SHR,DSN=<high-level-qualifier>.MYPDS(SSLFILE) //...
In the Configuration File define the server parameter brokerid for SSL or TLS connections.
Example with Transport-method-style Broker ID:
ETB024:1609:SSL
Example with URL-style Broker ID:
ssl://localhost:2010
Make sure the target the IMS RPC Server connects to is prepared for SSL/TLS connections as well. See the following sections:
To set up SSL or TLS with AT-TLS
Set up the IMS RPC Server for a TCP/IP connection.
Configure the rules for the AT-TLS policy agent the IMS RPC Server matches, for example by using the job name and remote port number the IMS RPC Server connects to. Used certificates are also defined with those rules. Refer to your IBM documentation for further information.
Make sure the target the IMS RPC Server connects to is prepared for SSL/TLS connections as well. See the following sections:
To start the IMS RPC Server
Modify the member EXPSRVI
(see EntireX job library EXX970.JOBS)
according to your system requirements and copy the started task JCL
to your system PROCLIB concatenation.
See Started Task JCL.
Modify the server parameters Configuration File according to your system requirement. For details, see Configuring the RPC Server.
Start the task manually with
/s EXPSRVI
Or:
Add the task to your system automation tool(s)
To stop the IMS RPC Server
Use the operator command STOP. Examples:
/p EXPSRVI /f EXPSRVI,STOP
Or:
Add the STOP command to your system automation tool(s).
Or:
Use the System Management Hub; this method ensures that the deregistration from the Broker is correct.
See Broker Administration using System Management Hub under
UNIX |
Windows.
To switch on tracing for IMS RPC Server
Set the parameters tracelevel and tracedestination.
Dynamically change the trace level with the operator command
F EXPSRVI,TRACELEVEL=tracelevel,
for valid tracelevel values, see tracelevel.
The TRACELEVEL command without any value will report the currently active trace options, for example:
F EXPSRVI,TRACELEVEL
might reply with the operator message
Tracelevel=0 TraceFile=DD:ERXTRACE
To evaluate the return codes, see Component Return Codes in EntireX.