Scenarios and programmer information

A compilation of scenarios and programmer information.

COBOL scenarios

Following are a few COBOL scenarios.

Scenario I: Calling an existing COBOL server

To call an existing COBOL server:
  1. Use the IDL Extractor for COBOL to extract the EntireX IDL and, depending on the complexity, also a server mapping file. See When is a server mapping file required? under Server Mapping Files for COBOL in the Designer documentation. If your COBOL server uses PCB pointers, see IMS-specific PCB pointers.
  2. 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 Designer 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 CICS in the COBOL Wrapper documentation for COBOL RPC Server examples.

Scenario II: Writing a new COBOL server

To write a new COBOL server

  1. 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? under Server Mapping Files for COBOL in the Designer 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.
  2. 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 Designer 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.

PL/I scenarios

Following are a few PL/I scenarios.

Scenario III: Calling an existing PL/I server

To call an existing PL/I server:
  1. Use the IDL Extractor for PL/I to extract the EntireX IDL.
  2. 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.
  3. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:
    • use the IDL Tester. See EntireX XML tester in the Designer 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 CICS in the PL/I Wrapper documentation for PL/I RPC Server examples.

Scenario IV: Writing a new PL/I server

To write a new PL/I server:
  1. 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.
  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:
    • use the IDL Tester, see EntireX XML tester in the Designer 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 CICS in the PL/I Wrapper documentation for PL/I RPC Server examples.

C scenarios

Scenario V: Writing a new C server

To write a new C server:
  1. 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, Linux, Windows).
  2. 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 Designer documentation
    • generate an XML mapping file (XMM) and use the XML Tester for verification, see EntireX IDL tester in the XML/SOAP Wrapper documentation

Assembler scenarios

Scenario VI: Writing a new assembler server

To write a new Assembler (IBM 370) server:
  1. 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                      F8
    • The 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 | .NET | Java | Natural | PL/I.
  2. 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 Designer documentation
    • generate an XML mapping file (XMM) and use the XML Tester for verification, see EntireX IDL tester in the XML/SOAP Wrapper documentation

Returning application errors

Using RETURN-CODE special register (COBOL only)

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.

Automatic syncpoint handling

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.