This document covers the following topics:
To call an existing COBOL server
Use the IDL Extractor for COBOL to extract the Software AG IDL and, depending on the complexity, also a server mapping file. See When is a Server Mapping File Required? in the EntireX Workbench documentation. If your COBOL server uses PCB pointers, see IMS-specific PCB Pointers.
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 in the XML/SOAP Wrapper documentation
See Client and Server Examples for z/OS IMS BMP in the COBOL Wrapper documentation 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, also a server mapping file. See When is a Server Mapping File Required? in the EntireX Workbench documentation. Write your COBOL server and proceed as described under Using the COBOL Wrapper for the Server Side. If your COBOL server uses PCB pointers, see IMS-specific PCB Pointers.
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 in the XML/SOAP Wrapper documentation
See Client and Server Examples for z/OS IMS BMP in the COBOL Wrapper documentation 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.
If your PL/I server uses PCB pointers, generate one or more server interface objects, using the IDL File extracted in Step 1 above. For more information see Extraction Result in the IDL Extractor for PL/I documentation. See also IMS-specific PCB Pointers.
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 in the XML/SOAP Wrapper documentation
See Client and Server Examples for z/OS IMS BMP in the PL/I Wrapper documentation 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. If your PL/I server uses PCB pointers, see IMS-specific PCB Pointers.
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 in the XML/SOAP Wrapper documentation
See Client and Server Examples for z/OS IMS BMP in the PL/I Wrapper documentation for PL/I RPC Server examples.
To write a new C server
Use the C Wrapper to generate a C server skeleton and a C server interface object. Write your C server and proceed as described under Using the C Wrapper for the Server Side (z/OS, UNIX, Windows, BS2000, IBM i).
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 in the XML/SOAP Wrapper documentation
To write a new Assembler (IBM 370) server
Build an RPC server in Assembler. Here are some hints:
The RPC server is dynamically callable (no pre-initialization required).
The parameter interface is either compatible with the COBOL or PL/I calling convention (IDL level parameter will be passed in the address list).
The alignment of integer or float data types is considered. The HASM Assembler aligns integer or float data types to appropriate boundaries. For example:
...
MyLabel DSECT
MyField1 DS H I2
MyField2 DS F I4
MyField3 DS E F4
MyField4 DS L F8The RPC Server for IMS will not align these data types by default.
To force alignment by definition in your IDL file
(see the aligned attribute within the attribute-list) before generating your RPC client.
For information on whether your client supports the aligned attribute, see Mapping the aligned Attribute to
C |
COBOL |
DCOM |
.NET |
Java |
Natural |
PL/I.
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 in the XML/SOAP Wrapper documentation
The RETURN-CODE special register (an IBM extension to the COBOL
programming language) is used by your RPC server to report an error.
Upon return, the value contained in the RETURN-CODE special register is
detected by the RPC Server for IMS and sent back to the RPC client instead of the
application's data.
For IBM compilers the RETURN-CODE special register has the implicit
definition:
RETURN-CODE GLOBAL PICTURE S9(4) USAGE BINARY VALUE ZERO
Special registers are reserved words that name storage areas generated by the compiler. Their primary use is to store information produced through specific COBOL features. Each such storage area has a fixed name, and must not be defined within the program. See your compiler documentation for more information.
The following rules apply to application error codes:
The value range for application errors is 1-9999. No other values are allowed.
On the RPC client side, the error is prefixed with the error class 1002 "Application User Error" and presented as error 1002nnnn.
No application data is sent back to the RPC client in case of an error.
It is not possible to return an error text to the RPC client.
Example
. . .
IF error occurred THEN
MOVE <error-number> TO RETURN-CODE
GO TO MAIN-EXIT
END-IF.
. . .
MAIN-EXIT.
EXIT PROGRAM.
END PROGRAM RETCODE.
Note:
To enable this feature, configure the RPC Server for IMS with
return_code=yes.
The RPC Server for IMS issues a SYNC | ROLB call under the following circumstances:
The server issues an IMS SYNC call after a successful non-conversational request or an end-of-conversation.
After abnormal termination of a non-conversational request or a conversation due to an error, the server performs
an IMS ROLB call to back out any pending database modifications.