Administering the RPC Server for Batch

The EntireX RPC Server for z/OS Batch 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 and works together with the COBOL Wrapper and IDL Extractor for COBOL. This document covers the following topics:

Customizing the RPC Server

The following elements are used for setting up the RPC Server for Batch:

Configuration File

The name of the delivered example configuration file is CONFIG (see source library EXP109.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 RPC Server for Batch. The following settings are important:

  • connection information such as broker ID, server address (class, name, service)

  • scalability parameters

  • trace settings

  • etc.

For more information see Configuring the RPC Server.

IBM LE Runtime Options

Depending on the feature the RPC Server for Batch 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 IBM Z Publications Library Archive.

Feature LE Runtime Options Description
Trap abends of called RPC server programs ABTERMENC(RETCODE) (1) Required to also trap the LE abends within a server program.
Level of information if called RPC server program terminates by unhandled condition TERMTHDACT(UADUMP) (1) Forces a U4039 system dump for abends not trapped by the server.
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 RPC Server for Batch 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.

Started Task JCL

The name of the started task is EXPSRVB (see EntireX job library EXX109.JOBS). The started task contains the following:

  • the target server libraries of the called COBOL or PL/I server

  • 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

    Example using the DD name CONFIG: 

    CFG=DD:CONFIG

  • LE runtime options used; see IBM LE Runtime Options

  • etc.

Configuring the RPC Server

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 case-insensitive.

  • 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, that is, 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 in the RPC Programming documentation.

Example:
brokerid=myhost.com:1971

 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). Case-sensitive, up to 32 characters. Corresponds to CLASS attribute of the broker attribute file.

Example:
class=MyRPC

R
codepage no codepage transferred

The codepage tells the broker the encoding of the data. The application must ensure the encoding of the data matches the codepage. The RPC server itself does not convert your application data. The application's data is shipped and received as given. Often, the codepage must also match the encoding used in the RPC server environment for file and terminal IO, otherwise unpredictable results may occur.

By default, no codepage is transferred to the broker. It is assumed the broker's locale string defaults match. See Locale String Mapping If they do not match, provide the codepage here.

Example:
codepage=ibm-273

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.

O
compresslevel N Enforce compression when data is transferred between broker and server. See Data Compression in EntireX Broker.

compresslevel=0|1|2|3|4|5|6|7|8|9|Y|N

0-9 0=no compression
9=max. compression
N no compression
Y compression level 6

Example:
compresslevel=6

 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 Designer documentation.
YES Activates the deployment service. The RPC server registers the deployment service in the broker.
NO The deployment service is deactivated. The RPC server does not register the deployment service in the broker.

Example:
deployment=yes

 O
etblnk BROKER Define the broker stub to be used. See Administering Broker Stubs for available stubs.

Example:
etblnk=broker

 O
extractor NO The extractor service is a prerequisite for remote extractions. See Extractor Service.

extractor=YES|NO

Example:
extractor=yes

 O
impersonation NO Defines if RPC requests are executed under the RPC user ID of the calling RPC client.

Depending on settings, different levels of checks are done prior to RPC server execution. See also Impersonation under Introduction to the RPC Server for Batch.

impersonation=NO|YES|AUTO[,sameuser|,anyuser]

NO The RPC request is executed anonymously, which means the user ID of the calling RPC client is not used. RPC requests are executed under the user ID of the RPC server.
YES The RPC request runs impersonated under the supplied RPC client user ID. The RPC Server for Batch validates the RPC client user ID/password pair against the mainframe security repository.
AUTO Same as option YES above, except that no password validation is performed, that is, the calling RPC client is treated as already authenticated. For this setting, make sure the RPC client is correctly authenticated; use either

  • a secure broker (validation must be against the correct mainframe security repository where the user IDs are defined) and option sameuser
    or

  • your own security implementation (option anyuser is supported for compatibility reasons if you need different broker and server user IDs - the customer-written security implementation must validate the calling RPC client using the RPC client user ID).

The following options are available for AUTO:

  • sameuser
    The RPC Server for Batch checks whether the broker client user ID matches the RPC client user ID. This is the default if AUTO is used.

  • anyuser
    The RPC client user ID is used for impersonation. The broker client user ID is ignored.

Example:
impersonation=auto,anyuser

Using impersonation requires additional installation steps. See Using z/OS Privileged Services in the z/OS installation documentation.

O
library no default library = search_logic [- library]
where search_logic is one of FIX(dllname) | PREFIX(prefix) | PREFIX(), and
  library can be repeated up to four times, that is, five entries are possible.

This parameter applies to programming language C only. Do not set if other programming languages for RPC server are used.

FIX(dllname) The IDL library name coming from the RPC client is ignored, thus long IDL library names can be used. You have to define the DLL names for all client interface objects and RPC servers.
PREFIX(prefix) The IDL library name coming from the RPC client is used to form the DLL name. As prefix you can define any character. If an RPC client sends, for example, "SYSTEM" as the IDL library name and "D" is defined as prefix, the DLL name derived is "DSYSTEM". This configuration restricts the IDL library names to max. 7 characters.
PREFIX() The IDL library name coming from the RPC client is used as DLL name. This configuration restricts the IDL library names to max. 8 characters.

Example PREFIX configuration (this configuration matches the standard names produced by the C Wrapper):
library=PREFIX(D)-PREFIX()

Example FIX configuration:
library=FIX(MYSTUBS)-FIX(MYRPCS)

 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.
NO No logon/logoff functions are executed.
YES Logon/logoff functions are executed.

Example:
logon=no

 O
marshalling COBOL The RPC Server for Batch can be configured to support either COBOL, PL/I or C. See also Locating and Calling the Target Server.
marshalling=(LANGUAGE=COBOL|PLI|C)
COBOL Server supports COBOL. The COBOL servers are called directly without a server interface object. So-called server mapping files are used to call the COBOL server correctly if one is available. See Usage of Server Mapping Files.
PLI Server supports PL/I. See prerequisites for PL/I Wrapper.
C Server supports C. The modules are called using a server interface object built with the C Wrapper.
O
password no default The password for secured access to the broker. If possible (write access) the password is encrypted and written to parameter password.e. The parameter password is removed. To change the password, add the parameter password with the new password as value. If the Configuration File is an inline data set in the Started Task JCL, password encryption does not take place.

Example:
password=MyPwd

 O
restartcycles 15 Number of restart attempts if the broker is not available. This can be used to keep the RPC Server for Batch running while the broker is down for a short time. A restart cycle will be repeated every 60 seconds.

Note:
Internally, the server waits in periods of 10 seconds (performing six times more cycles), which you can see in the server output.

When the number of specified cycles is reached and a connection to the broker is not possible, the RPC Server for Batch stops.

Example:
restartcycles=30

The server waits up to 30 minutes (30*6*10 seconds) before it terminates due to a missing broker connection.

 O
return_code NO Enable application-specific errors.
return_code=(NO|YES)
NO No tests of COBOL special register RETURN-CODE for application-provided error.
YES After execution of the RPC server, tests COBOL special register RETURN_CODE for application provided error. See Returning Application Errors.

Example:
return_code=yes

 O
runoption no default This parameter is for special purposes. It provides the RPC Server for Batch with additional information. The runoptions are normally set to meet the platform's requirements. Set this parameter only if a support representive provides you with an option and asks you to do so.

Example:
runoption=<option>
runoption=<option>

 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. Case-sensitive, up to 32 characters. Corresponds to SERVER of the broker attribute file.

Example:
servername=mySrv

 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. Case-sensitive, up to 32 characters. Corresponds to SERVICE attribute of the broker attribute file.

Example:
service=MYSERVICE

 R
svm ERXSVM Usage and location of server-side mapping files (Designer files with extension .svm) at runtime; see Server-side Mapping Files in the RPC Server. If the svm parameter is omitted, 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 at runtime, the server-side mapping container must be installed and configured; see Installing the Server-side Mapping Container for an RPC Server for Batch (Optional) under Installing the EntireX RPC Servers under z/OS.

Server mapping files with extension .svm are no longer supported at design time by the Designer. You can still use them at runtime in a server-side mapping container. All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping files with extension .cvm. See When is a Server Mapping File Required?
We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation.

svm = no|ddname

no No server-side mapping files are used.
ddname DD name of the server-side mapping container in the started task JCL of the RPC Server for Batch.

Example:
svm=MYSVM

For the example above, define the DD name MYSVM in the started task JCL of the RPC Server for Batch (see Started Task JCL) as:
//MYSVM DD DISP=SHR,DSN=<svm.cluster>

See also Usage of Server Mapping Files.

O
timeout 60 Timeout in seconds, used by the server to wait for broker requests. See WAIT under Broker ACI Fields for more information. Also influences restartcycles and worker model DYNAMIC.

Example:
timeout=300

 O
tracedestination DD:ERXTRACE

The name of the destination file for trace output. See also Activating Tracing for the RPC Server.

tracedestination=DD:ddname, where ddname is the name of the trace file.

Example:
tracedestination=DD:MYTRACE

The DD name MYTRACE must be defined in the started task of the RPC Server for Batch (see Started Task JCL): 

//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

None No trace output.
Standard For minimal trace output.
Advanced For detailed trace output.
Support This trace level is for support diagnostics. Use only when requested by Software AG Support.

Example:
tracelevel=standard

 O
traceoption None Additional trace option if trace is active. See also Activating Tracing for the RPC Server.
None No additional trace options.
STUBLOG If tracelevel is Advanced or Support, the trace additionally activates the broker stublog.
NOTRUNC Normally if a data buffer larger than 8 KB is traced, the buffer trace is truncated. Set this option to write the full amount of data without truncation.

Note:
This can increase the amount of trace output data dramatically if you transfer large data buffers.

Example:
traceoption=(STUBLOG,NOTRUNC)

 O
userid ERX-SRV The user ID for access to the broker. The default ERX-SRV will be used if this parameter is omitted or specified without a value: "userid=".

Example:
userid=MyUid

 O
workermodel SCALE,1,3,slowshrink The RPC Server for Batch can be configured to

  • use a DYNAMIC worker model, which adjusts the number of worker threads to the current number of client requests: 

    workermodel=(SCALE,from,thru
              [,slowshrink|fastshrink])

  • use a FIXED number of worker threads: 

    workermodel=(FIXED,number)
FIXED A fixed number of worker threads is used by the RPC Server for Batch.
SCALE The number of worker threads is adjusted to the current number of client requests. With the from value, the minimum number of active worker threads can be set. This allows you to define a certain number of threads - not used by the currently executing RPC request - to wait for new RPC client requests to process. In this way the RPC server is ready to handle many RPC client requests arriving at the same time. The thru value restricts the maximum number of all worker threads concurrently.

  • slowshrink
    Default. The RPC server stops all worker threads not used in the time specified by the timeout parameter, except for the number of workers specified as minimum value.

  • fastshrink
    The RPC server stops worker threads immediately as soon as it has finished its conversation, except for the number of workers specified as minimum value.

Example:
workermodel=(SCALE,2,5)
O

Locating and Calling the Target Server

The IDL library and IDL program names that come from the 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 RPC Server for Batch environment. Different mechanisms are used depending on the language:

COBOL

The z/OS module name for the RPC server called is taken from the server mapping if one is available. See Usage of Server Mapping Files for an introduction. If no server mapping is used, the IDL program name is used as the z/OS module name of the RPC server and the IDL library name is ignored.

Start of instruction setTo use the RPC Server for Batch with COBOL

  1. Make sure that all z/OS modules called as RPC servers

    • are compiled with IBM's Language Environment (see IBM Z Publications Library Archive for more information)

    • use COBOL calling conventions

    • can be called dynamically ("fetched") from any Language Environment program

    • are accessible through the RPC Server for Batch started task JCL STEPLIB concatenation. See Started Task JCL.

  2. Configure the parameter marshalling for COBOL, for example: 

    marshalling=COBOL

See also Scenario I: Calling an Existing COBOL Server or Scenario II: Writing a New COBOL Server.

PL/I

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.

Start of instruction setTo use the RPC Server for Batch with PL/I

  1. Make sure that all z/OS modules called as RPC servers

    • are compiled with IBM's Language Environment (see IBM Z Publications Library Archive for more information)

    • use PL/I calling conventions

    • can be called dynamically ("fetched") from any Language Environment program

    • are accessible through the RPC Server for Batch started task JCL STEPLIB concatenation. See Started Task JCL.

  2. Configure the parameter marshalling for PL/I, for example marshalling=PLI.

See also Scenario III: Calling an Existing PL/I Server or Scenario IV: Writing a New PL/I Server.

C

The approaches needed to derive the dynamic-link library (DLL) names for the RPC server are more complex for C, for the following reasons:

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.

Start of instruction setTo use the RPC Server for Batch with C

  1. Make sure all dynamic-link libraries (DLLs) called as RPC servers and client interface objects are accessible through the RPC Server for Batch started task JCL STEPLIB concatenation. See Started Task JCL.

  2. Configure the parameter marshalling for C, for example marshalling=C.

  3. 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, Linux, Windows, BS2000).

See also Scenario V: Writing a New C Server.

Assembler (IBM 370)

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.

Start of instruction setTo use the RPC Server for Batch with Assembler

  • Make sure all z/OS modules called as RPC Servers

    • are accessible through the RPC Server for Batch 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.

Using SSL/TLS with the RPC Server

RPC servers can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based servers are always SSL clients. The SSL server can be either the EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

SSL delivered on a z/OS mainframe will typically use the Resource Access Control Facility (RACF) as the certificate authority (CA). Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client/server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must be uniquely identifiable by owner and label, and also unique by serial number plus data set name (DSN).

For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used, where the establishment of the SSL connection is pushed down the stack into the TCP layer.

Using IBM's Application Transparent Transport Layer Security (AT-TLS)

Configure the AT-TLS rules for the policy agent (PAGENT) graphics/no4.gif using an appropriate client graphics/no1.gif and the z/OS Management Facility (z/OSMF) graphics/no2.gif. Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by using the application graphics/no5.gif job name and remote TCP port number. If the rules match, the TCP connection is turned into an SSL connection graphics/no6.gif. Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.

graphics/adminRpc_ssl_config-batch.png

graphics/no1.gif Client to interact with z/OS Management Facility (z/OSMF).
graphics/no2.gif AT-TLS rules are defined with z/OSMF policy management.
graphics/no3.gif Policy Repository with AT-TLS rules stored as z/OS files.
graphics/no4.gif Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
graphics/no5.gif Application using TCP connection.
graphics/no6.gif If AT-TLS rules match, the TCP connection is turned into an SSL connection.

Notes:

  1. The client graphics/no1.gif may vary per operating system, for example a Web browser for z/OS 2.1.
  2. z/OSMF graphics/no2.gif includes other administration and management tasks in addition to policy management.
  3. Policy Management graphics/no3.gif includes other rules, such as IP filtering, network address translation etc.

Start of instruction setTo set up SSL with AT-TLS

  1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

  2. Set up the RPC Server for Batch for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example: 

    ETB024:1699:TCP

  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF) See z/OSMF Considerations in the z/OS Administration documentation. The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

  4. Make sure the SSL server to which the RPC Server for Batch connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:

Starting the RPC Server

Start of instruction setTo start the RPC Server for Batch

  1. Modify the member EXPSRVB (see EntireX job library EXX109.JOBS) according to your system requirements and copy the started task JCL to your system PROCLIB concatenation. See Started Task JCL.

  2. Modify the server parameters Configuration File according to your system requirement. For details, see Configuring the RPC Server.

  3. Start the task manually with

    /s EXPSRVB

    Or:
    Add the task to your system automation tool(s)

Stopping the RPC Server

Start of instruction setTo stop the RPC Server for Batch

  • Use the operator command STOP. Examples: 

    /p EXPSRVB
/f EXPSRVB,STOP

    Or:
    Add the STOP command to your system automation tool(s).

Activating Tracing for the RPC Server

Start of instruction setTo switch on tracing for the RPC Server for Batch

  1. Set the parameters tracelevel, traceoption and tracedestination. See Configuring the RPC Server.

  2. Start the RPC Server for Batch. See Starting the RPC Server.

  3. Temporarily change the trace level with the operator command

    F EXPSRVB,TRACELEVEL=tracelevel,

    for valid tracelevel values, see tracelevel.

    The TRACELEVEL command without any value will report the currently active trace options, for example: 

    F EXPSRVB,TRACELEVEL

    might reply with the operator message

    Tracelevel=0 TraceFile=DD:ERXTRACE

Start of instruction setTo switch off tracing