Developing an ONC RPC application for CICS ONC RPC

ONC RPC applications are always developed as client/server pairs. The process described in this section takes account of this, but concentrates on the server, because CICS® ONC RPC affects this and not the client. For details of the client development process, read the documentation of the ONC RPC system running on the client machine.

The process of developing all the material needed for an ONC RPC application using CICS ONC RPC is summarized in Figure 58, which should be compared with Figure 32, which showed the process for ONC RPC without CICS ONC RPC.

Figure 58. Program development with CICS ONC RPC
 Diagram showing an RPCL program processed by RPCGEN to produce a client stub; XDR routines; header files; and a Server stub. The Client stub and header files are compiled to form the client stub object and the client application source is compiled to form the client object. These are then linked to form the client application. The header files and XDR routines are compiled to form the XDR object, which is linked to form the XDR program. The header files and Converter program source are compiled to form the Converter Object, which is linked to form the Converter.

The figure shows the development process when RPCGEN is used to create source text from the interface definition in the RPCL program. If you do not use RPCGEN, you must supply some of its output--XDR routines and header files--yourself. The development of the CICS program to service client requests is not shown.

The sequence of development of an ONC RPC application is summarized below. Each step is described in detail in the sections following the summary.

  1. Decide what data is to be sent from client to server and what is to be returned. If the data structures the client uses are not simple, you might choose to use RPCGEN to help with managing the data. If you choose to use RPCGEN, some of its output is useful for writing the user-replaceable programs for CICS ONC RPC.
  2. Decide the format of the communication area to be used by the CICS program. If the client is to use an existing CICS program, the format is already decided.
  3. Write the XDR routines. If the translations you need can be done by an XDR library function supported by the connection manager (see Table 26), you do not need to write an XDR routine. If you used RPCGEN, it has generated source for XDR routines. In any other case you must write the XDR routines yourself.

    XDR routines must be written in C.

  4. Write the converter. If you used RPCGEN, and you are going to write your converter in C, the header files produced by RPCGEN describe the data structures that Decode receives and Encode returns. The format of the CICS program communication area is also used by Decode and Encode.
  5. Write the resource checker, if required. You may want to write your own resource checker to validate incoming client requests. CICS ONC RPC security tells you about this and other security facilities available for use with CICS ONC RPC. Writing the resource checker gives you details on writing a resource checker.
  6. Compile and link the user-replaceable programs. If you used RPCGEN, the header files are needed for the compilation of the XDR routines and the converter if it is in C.
  7. Define the server application set to CICS. This means defining programs for the CICS program, any XDR routines that are not just XDR library functions, and the converter. One or more alias transaction definitions may also be required, see Defining CICS ONC RPC resources to CICS.
  8. Use the connection manager to define a 4-tuple and save it in the CICS ONC RPC data set. The definition specifies the CICS program, XDR routines, and converter, as described in Defining the attributes of a 4-tuple.

Step 1--Decide what data is to be sent

This step is outside the scope of this manual. What you do depends on the nature of the data to be sent with the request and with the reply. Defining data with RPCL and the use of RPCGEN are described in Sun Microsystems’ publication Network Programming.

Step 2--Decide the format of the communication area

This step is also outside the scope of this manual. You are reminded that if the CICS program that services a client request is not in the same CICS region as CICS ONC RPC, the maximum communication area length is 35 000 bytes. If the CICS program resides in a server other than CICS Transaction Server for OS/390®, other restrictions might also apply.

Step 3--Write the XDR routines

If you used RPCGEN in Step 1, you use the XDR source programs generated by RPCGEN. If the XDR source uses the xdr_char or xdr_u_char XDR library functions, you must use the C #define directive to make the compiler use the xdr_text_char function instead.

If the translations you need can be done by an XDR library function supported by the connection manager (see Table 26), you do not need to write an XDR routine. Instead you specify one of the XDR library functions described below when you register a 4-tuple with the connection manager.

If you write your own XDR routine, you need to use the XDR library functions. The full C definitions of these functions are documented in the TCP/IP for MVS: Programmer’s Reference .

CICS ONC RPC supports only the functions listed below. You should use only these functions in your own XDR routines. These functions convert C data types to XDR formats, and XDR formats to C data types.

Some of these function names cannot be used in the connection manager when specifying XDR library functions for the inbound and outbound XDR routines for a 4-tuple. In the column headed CM, an asterisk means that the XDR library routine can be specified in the connection manager, while a blank means that it cannot.

Table 26. Supported XDR library functions
XDR library function CM C type
xdr_int * int
xdr_u_int * unsigned int
xdr_long * long
xdr_u_long * unsigned long
xdr_short * short int
xdr_u_short * unsigned short int
xdr_float * float
xdr_bool * bool_t (see note)
xdr_double * double
xdr_enum enum
xdr_void * void
xdr_array variable-length array
xdr_opaque fixed-length uninterrupted data
xdr_bytes variable-length array of bytes
xdr_pointer object references, including null pointers
xdr_reference object references
xdr_char * character
xdr_u_char * unsigned character
xdr_text_char * text character
xdr_string null-terminated character arrays
xdr_vector fixed-length array with arbitrary element size
xdr_wrapstring * variable-length null-terminated character arrays
xdr_union discriminated union
Note:
bool_t is not a built-in C data type; it is defined in an ONC RPC header (as a C int).

Names of user-written XDR routines are subject to the same restrictions as CICS programs.

You must take care when writing your own XDR routines. These run in the CICS address space and can overwrite CICS code and other user application storage, because they are defined with EXECKEY(CICS).

Code page conversions

Conversion between ASCII and EBCDIC (or vice versa) is done by XDR library functions supplied as part of TCP/IP for MVS™. The relevant XDR routines are xdr_text_char, xdr_string, and xdr_wrapstring. These routines use EBCDIC-to-ASCII and ASCII-to-EBCDIC translate tables, which are loaded at TCP/IP for MVS initialization from a data set containing one of the possible translate tables provided with TCP/IP for MVS.

Thus all ONC RPC requests from all clients use the same translate table. There is no provision for ONC RPC data from different client workstations or from different client end users to have different character sets.

Various single-byte character set (SBCS) translate tables are provided with TCP/IP for MVS, one of which is generated during TCP/IP for MVS customization. If none of these is suitable, you could provide your own, as described in the TCP/IP for MVS: Customization and Administration Guide .

TCP/IP for MVS 3.1 provides several code pages for double-byte character sets (DBCS). If you want to include DBCS in ONC RPC data you have to write your own XDR routines to convert the double-byte characters.

Step 4--Write the converter

Write the converter as described in Write theCICS ONC RPC converter, using reference information supplied in Reference information for the converter functions.

Step 5--Write a resource checker

This step is optional. See Writing the resource checker for details.

Step 6--Compile and link

This step puts the programs you have written into CICS load libraries.

Converter

The header files needed to compile the converter are discussed in Organizing the converter.

The program is linked into a CICS load library, since it is a normal CICS program.

XDR routines

If your XDR routines are not just XDR library functions, you must compile each XDR routine separately and link it into a CICS load library. If you used RPCL to define the data, the XDR source and header files for the compilation have been generated by RPCGEN.

Resource checker

If you need a resource checker, you must link it into a CICS load library. It must be called DFHRPRSC.

Step 7--Make CICS definitions

You must define the CICS program, converter program, resource checker, and any XDR routines that are not just library routines to CICS. See Defining CICS ONC RPC resources to CICS.

Step 8--Make a connection manager entry

Use the connection manager to define each 4-tuple. Completing an entry for a 4-tuple in the connection manager ensures that you provide CICS ONC RPC with all the information that it needs to service the client request.

The fields used to define each 4-tuple are described in Defining the attributes of a 4-tuple.

Related concepts
ONC RPC concepts
ONC RPC remote procedures and CICS programs
CICS ONC RPC user-replaceable programs
Related tasks
Write theCICS ONC RPC converter
Related reference
Reference information for the converter functions
[[ Contents Previous Page | Next Page Index ]]