CICS ONC RPC user-replaceable programs

Stabilized feature: CICS® support for Open Network Computing Remote Procedure Call (ONC RPC) is stabilized. Consider exposing and orchestrating applications as API services by using z/OS Connect Enterprise Edition or CICS web services, or by writing web applications in Java or Node.js. See also Stabilization notices and discontinued functions.

Servicing a client request involves not only a CICS program, but a converter program and XDR routines. For compatibility with earlier releases of CICS you can use a resource checker program to validate incoming client requests, or you can use CICS security facilities.

XDR routines

You need to provide one or two XDR routines for each 4-tuple. You always need an inbound XDR routine, and unless the client call is nonblocking, you need an outbound XDR routine as well. For information about XDR (eXternal Data Representation), see XDR routines and library functions.

The XDR routines for each 4-tuple are specified by using the connection manager.

Resource checker module

CICS ONC RPC provides an interface to a resource checker (which you write).

Converters

You can also supply a converter for each program-version-procedure-protocol 4-tuple.

Each converter can contain up to three functions.
Getlengths function
The Getlengths function might be called by the connection manager when a 4-tuple is registered. Getlengths can supply the following information:
  • The length of the input and output data for the CICS program
  • Whether the output data overlays the input data in the communication area

Because its processing is done before any client requests are received, It is appropriate to use Getlengths to provide the values of data lengths that do not vary from call to call. Refer to Lengths of the CICS program input and output data for a fuller description of when Getlengths should be used for this purpose.

Decode function
The Decode function is called by the server controller on receipt of a client request. Decode can do the following:
  • Supply the length of the input and output data for the CICS program. If the parameter lengths vary from call to call, Decode should return them for the current call.
  • Reconstruct the data from the client as a communication area for the CICS program. CICS ONC RPC data flow illustrates the kinds of data that Decode might have to handle. The incoming data might include pointers, and Decode must gather up the incoming data into the communication area.
  • C®onvert data structures from C format to the format appropriate to the programming language in which the CICS program is written.
  • Process data from the client that is not intended for the CICS program. For example the data from the client might include the name of the CICS program to be called, and Decode can feed this information back to the server controller.
Encode function
The Encode function is called by the alias when the CICS program ends. Encode can do the following:
  • Reconstruct the data from the communication area into the form expected by the client. CICS ONC RPC data flow illustrates the kinds of data that Encode might have to handle. The client might expect to receive data accessed by pointers, and Encode must build this structure from the data in the communication area.
  • Convert data structures from the format appropriate to the programming language in which the CICS program is written into C format.

Not all 4-tuples need a converter with all three functions. You use the connection manager to specify the converter and the use of Getlengths, Decode, and Encode for each 4-tuple.

The way that particular language data structures are stored is documented in the appropriate language manuals, and a correspondence between C data types and those in other languages is given in the z/OS Language Environment Programming Guide.

For detailed instructions on the writing of converters, refer to Write the CICS ONC RPC converter.

Converters run as CICS programs under the connection manager, server controller, and aliases. Converters must reside in the same CICS system as CICS ONC RPC.