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.
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.
XDR routines must be written in C.
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.
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.
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.
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 |
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).
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.
Write the converter as described in Write theCICS ONC RPC converter, using reference information supplied in Reference information for the converter functions.
This step is optional. See Writing the resource checker for details.
This step puts the programs you have written into CICS load libraries.
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.
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.
If you need a resource checker, you must link it into a CICS load library. It must be called DFHRPRSC.
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.
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.