EntireX	Version 9.7	SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

This document covers the following topics:

• COBOL Scenarios

• PL/I Scenarios

• C Scenarios

• Assembler Scenarios

• Aborting RPC Server Customer Code and Returning Error to RPC Client

• Automatic Syncpoint Handling

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 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.

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 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.

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? 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.

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 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.

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 Software AG IDL.

2. If your PL/I server uses PCB pointers, generate one or more server interface objects, using the Software AG 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 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 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 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.

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, UNIX, Windows, BS2000/OSD, IBM 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 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

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 IMS RPC Server 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.

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 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

Aborting RPC Server Customer Code and Returning Error to RPC Client

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 IMS RPC Server 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 IMS RPC Server with return_code=yes.

Automatic Syncpoint Handling

The IMS RPC Server issues a SYNC | ROLB call under the following circumstances:

• After a successful non-conversational request or an end-of-conversation, the server issues an IMS SYNC call.

• 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.

www.softwareag.com

Copyright © 1997-2014 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT