The EntireX RPC Server for z/VSE Batch allows standard RPC clients to communicate with RPC servers on the operating system z/VSE under Batch. It supports the programming language COBOL and works together with the COBOL Wrapper and IDL Extractor for COBOL. This document covers the following topics:
The name of the delivered example configuration file is RPCPARM.CFG
(see sublibrary EXP960).
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)
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.
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, 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.
Example: |
R | ||||||||||||||||
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 .
Example: |
R | ||||||||||||||||
codepage |
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 |
||||||||||||||||||
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 Designer documentation.
Example: |
O | ||||||||||||||||
etblnk |
BKIMB |
Define the broker stub to be used. See Administering Broker Stubs under z/VSE for available stubs.
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 | The password for secured access to the broker.
Example: |
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.
When the number of specified cycles is reached and a connection to the broker is not possible, the RPC Server for Batch stops. Example: The server waits up to 30 minutes before it terminates due to a missing broker connection. |
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 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.
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.
Case-sensitive, up to 32 characters.
Corresponds to SERVICE attribute of the broker attribute file.
Example: |
R | ||||||||||||||||
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 DLBL name ERXSVM .
If this DLBL 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 Step 3: Customize the Startup JCL - RUNRPC.J under Installing the z/VSE EntireX RPC Servers.
There are also client-side mapping files that do not require configuration here; see
Server Mapping Files in the Designer in the Designer documentation.
Example: For the example above, define the DLBL name // DLBL MYSVM,'ENTIREX.SVMDEV.KSDS',0,VSAM,CAT=VSESPUC 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 and worker model DYNAMIC .
Example: |
O | ||||||||||||||||
tracelevel |
None |
Trace level for the server. See also Activating Tracing for the RPC Server.
tracelevel = None | Standard | Advanced | Support
Example: |
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: |
O | ||||||||||||||||
workermodel |
SCALE,1,3,slowshrink |
|
O |
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:
The approach used to derive the z/VSE 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/VSE module name of the RPC server is derived from this mapping. In this case the IDL program name can be different to the z/VSE 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/VSE module name of the RPC server (the IDL library name is ignored).
To use the RPC Server for Batch with COBOL
Make sure that all z/VSE modules called as RPC servers
are compiled with IBM's Language Environment (see LE/VSE V1R4 Programming Guide 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 JCL LIBDEF
chain.
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 names for the RPC Server for Batch are more complex for C, for the following reasons:
the limitation of characters per (physical) member name
the maximum length of 128 characters per IDL library name. See Rules for Coding Library, Library Alias, Program, Program Alias and Structure Names in the IDL Editor documentation.
You need to restrict yourself to short IDL library names.
To use the RPC Server for Batch with C
Configure the parameter marshalling
for C, for example
marshalling=C
See Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000, IBM i).
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 and Certificates with EntireX in the Platform-independent Administration documentation.
Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This facility is similar to z/OS Application Transparent - Transport Layer Security (AT-TLS). ATLS is supported by the BSI stack only.
Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup
job BSTTATLS
.
If the rules match, the socket connection is turned into an SSL connection .
Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.
BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6). | |
ATLS rules are defined manually. See Sample ATLS Daemon Configuration below. | |
BSTTATLS is associated with a TCP/IP stack. | |
Application using TCP connection. | |
BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections. |
To set up SSL with ATLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
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
Configure ATLS to turn the TCP/IP connection to an SSL connection, see above.
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:
To start the RPC Server for Batch
Run the job RPCRPC.J
.
To stop the RPC Server for Batch
Use the following console command:
task_id
STOP
Or:
Use the command-line utility ETBCMD
.
To activate tracing for the RPC Server for Batch
Set the parameter tracelevel
.
Temporarily change the trace level with the operator command
port_number
TRACELEVEL=tracelevel
See description of tracelevel
parameter for supported trace levels.
The TRACELEVEL
command without tracelevel
option will report the
currently active trace.