Overview of CICS ONC RPC application development process
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 1, which shows the process for ONC RPC without CICS ONC RPC. Figure 1 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.
Program development process summary
Step 1: Decide what data is to be sent
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.
This step is outside the scope of this information. 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
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.
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 z/OS®, other restrictions might also apply.
Step 3: Write the XDR routines
Write the XDR routines. If the translations you need can be done by an XDR library function supported by the connection manager (see Table 1), you do not need to write an XDR routine. Instead you specify one of the XDR library functions described later when you register a 4-tuple with the connection manager. 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®.
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.
If you write your own XDR routine, you need to use the XDR library functions. CICS ONC RPC supports only the functions listed in Table 1 in CICS ONC RPC supported XDR library functions. 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. The full C definitions of these functions are documented in z/OS Communications Server: IP Programmer's Guide and Reference.
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).
Step 4: Write the converter
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.
See Writing the CICS ONC RPC converter and Reference information for the converter functions.
Step 5: Write a resource checker
Write the resource checker, if required. You may want to write your own resource checker to validate incoming client requests. Security for ONC RPC 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.
Step 6: Compile and link
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.
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 CICS ONC RPC converter.
- 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: Define the server application set to CICS
You must define the CICS program, converter program, resource checker, and any XDR routines that are not just library routines to CICS. One or more alias transaction definitions may also be required. See Defining CICS ONC RPC resources to CICS.
Step 8: Make a connection manager entry
Use the connection manager to define each 4-tuple and save it in the CICS ONC RPC data set. 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 definition specifies the CICS program, XDR routines, and converter. The fields used to define each 4-tuple are described in EDF Terminal ID.