The EntireX z/OS CICS® RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/OS under CICS. It supports the programming languages COBOL and PL/I.
This document covers the following topics:
This section covers the following topics:
RPC requests are worked off inside the RPC server in worker tasks, which are controlled by a main task. Every RPC request occupies during its processing a worker task. If you are using RPC conversations, each RPC conversation requires its own task during the lifetime of the conversation. The CICS RPC Server provides two worker models:
FIXED
The fixed model creates a fixed number of worker tasks.
The number of worker tasks (defined with ERXMAIN macro parameter MINW) does not increase or decrease during the lifetime of an RPC server instance.
It is configured by setting the ERXMAIN macro parameter ENDW to value "NEVER". Example:
ENDW=NEVER, MINW=4
SCALE
The scale model creates worker tasks depending on the incoming load of RPC requests.
A maximum number (ERXMAIN macro parameter MAXW)
of the worker tasks created can be set to restrict the system load.
The minimum number (ERXMAIN macro parameter MINW),
allows you to define a certain number of tasks - 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.
It is configured by setting the ERXMAIN macro parameter ENDW
to value "TIMEOUT" or "IMMEDIATE".
With value IMMEDIATE, worker tasks shrink fast, that is, worker tasks not used are stopped immediately as soon as it has finished its conversation,
except for the number of workers specified as minimum being active.
With value TIMEOUT, worker tasks shrink slowly,
that is, all worker tasks not used are stopped in the time specified by the
ERXMAIN macro parameter TOUT, except for the number of workers
specified as minimum being active.
Example:
ENDW=IMMEDIATE, MINW=2,MAXW=6
CICS RPC Server provides several services for ease-of-use:
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.
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 Listener Service is switched on if the SMH port number is set. See the ERXMAIN macro parameter SMH under Configuring the RPC Server.
This section covers the following topics:
The CICS RPC Server provides a user exit to influence/control the RPC logic.
The exit is called on the events START-WORKER, START-USER, CALL-START and CALL-END.
The following tasks can be performed:
 |
START-WORKER event before a CICS worker task is started. This allows you to programatically set the CICS transaction ID.
|
 |
START-USER event. Apply CICS transaction ID and user ID to impersonated worker tasks. See Impersonation.
|
 |
CALL-START event. Inspect, modify or terminate the RPC request (payload) from the RPC client.
|
 |
CALL-END event. Inspect or modify the RPC reply (payload) or give an error to the RPC client.
|
See also Writing and Configuring User Exit COBUEX02.
The server invokes the server program using CICS LINK PROGRAM and expects that the program returns with CICS RETURN.
However, if the program uses CICS ABEND CANCEL to abort for particular error situations, the RPC server cannot trap the abort.
If your server program uses CICS ABEND CANCEL you need to call the delivered RPCUEX01 to inform the server that your
program is about to abort with CICS ABEND CANCEL.
|
The server program is invoked within the user task. |
|
The server program decides to abort using CICS ABEND CANCEL immediately before it calls the user exit. Then the server program can perform CICS ABEND CANCEL to abort. The CICS ABEND CANCEL terminates the user task.
|
|
The user exit posts the worker task and informs it about the abort of its associated user task. The worker task sends back the abort information to the client. |
See also Using User Exit RPCUEX01.
The CICS RPC Server can be configured to execute the RPC request impersonated under the RPC client user ID.
For this, worker tasks start additional impersonated user tasks. This can be useful, for example for accounting.
Impersonation is controlled by the ERXMAIN macro parameter IMPS. For IMPS value AUTO,
the CICS RPC Server does not validate RPC passwords, so you have to take care the RPC client is correctly authenticated,
either by using a secure EntireX Broker (validation must be against the correct mainframe security repository where
CICS user IDs are defined) or with your own security implementation.
The picture above shows the configuration impersonation=yes.
The lifetime of an impersonated user 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.
For worker tasks, the slow-shrinking worker model SCALE is used
- value TIMEOUT is forced internally - any value given in the ERXMAIN macro parameter ENDW is ignored.
The lifetime of worker tasks can be controlled with ERXMAIN macro parameter TOUT
as well as the number of workers with macro parameters MINW and MAXW.
To correctly support special COBOL syntax such as JUSTIFIED,
SYNCHRONIZE and OCCURS DEPENDING ON clauses, LEVEL-88 fields, etc.,
the CICS 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.
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 the ERXMAIN macro parameter SVM. See Configuring the RPC Server.
Note:
SVM files are used for COBOL only.
Supported interface types vary depending on the target programming language. See also Locating and Calling the Target Server.
CICS with DFHCOMMAREA Calling Convention (COBOL Wrapper | Extractor)
CICS with Channel Container Calling Convention (COBOL Wrapper | Extractor)
CICS with DFHCOMMAREA Large Buffer Interface (COBOL Wrapper | Extractor)
CICS with DFHCOMMAREA Calling Convention (PL/I Wrapper | Extractor)
The CICS RPC Server issues a SYNCPOINT command under the following circumstances:
After a successful non-conversational request or an end-of-conversation, the server issues a SYNCPOINT COMMIT command.
If you are running under CICS with impersonation,
this SYNCPOINT command is not executed by the server,
but by CICS when the user task is terminated. See Impersonation.
After abnormal termination of a non-conversational request or a conversation due to an error, the server performs
a SYNCPOINT ROLLBACK command to back out any pending database modifications.
To call an existing COBOL server
Use the IDL Extractor for COBOL to extract the Software AG IDL and, depending on the complexity of the extraction, also an SVM file.
Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:
use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation
generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester
See Client and Server Examples for z/OS CICS for COBOL RPC Server examples.
To write a new COBOL server
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.
Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:
use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation
generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester
See Client and Server Examples for z/OS CICS for COBOL RPC Server examples.
To call an existing PL/I server
Use the IDL Extractor for PL/I to extract the Software AG IDL.
Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:
use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation
generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester
See Client and Server Examples for z/OS CICS for PL/I RPC Server examples.
To write a new PL/I server
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.
Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:
use the IDL Tester; see EntireX IDL Tester in the EntireX Workbench documentation
generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester
See Client and Server Examples for z/OS CICS for PL/I RPC Server examples.
See Returning Application Errors from a Server under z/OS CICS to a Client under Writing Applications with the COBOL Wrapper.
