Version 9.5 SP1	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

Application error codes enable the RPC server to return customer-invented errors back to the RPC client in a standardized way without defining an error code field in the IDL.

This document covers the following topics:

• Returning Application Errors from a Server under z/OS Batch to a Client

• Returning Application Errors from a Server under z/OS CICS to a Client

• Returning Application Errors from a Server under z/OS IMS to a Client

Returning Application Errors from a Server under z/OS Batch to a Client

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 Batch 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 Batch RPC server with RETURN_CODE=YES.

Returning Application Errors from a Server under z/OS CICS to a Client

Using EXEC CICS ABEND ABCODE

This approach applies to the following CICS scenarios:

• Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE)

• Using the COBOL Wrapper for CICS with Channel Container Calling Convention (z/OS)

• Using the COBOL Wrapper for CICS with DFHCOMMAREA Large Buffer Interface (z/OS and z/VSE)

The CICS feature EXEC CICS ABEND ABCODE(myabend) may be used to indicate application error codes. According to IBM CICS standards, ABEND codes starting with the letter A are reserved for CICS itself and should not be used in your RPC server.

The CICS RPC Server follows these IBM CICS standards and sends back the RPC protocol message

1. 10010018 Abnormal termination during program execution. This is returned when an ABEND code starting with the letter "A" is received from CICS, which is a CICS ABEND.

2. 10010045 CICS ABEND myabend was issued. This is returned when an ABEND code starting with a letter other than "A" is received from CICS, which is an application error situation forced by your RPC server.

Using RETURN-CODE Special Register

This approach applies to the following CICS scenarios:

• Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE)

• Using the COBOL Wrapper for CICS with DFHCOMMAREA Large Buffer Interface (z/OS and z/VSE)

CICS applications that use the DFHCOMMAREA as communication area (EXEC CICS LINK applications) may return error codes if the LINKed application has a C main entry and if this application is running in the same CICS (non-DPL program) as the CICS RPC Server. Under these circumstances, IBM's Language Environment for C provides the application return code to EIBRESP2, where it can be detected by the CICS RPC Server.

The following provided modules need to be linked to your application.

• ERXRCSRV, a C main module that calls the intermediate COBOL subroutine RCCALL and catches the error from your RPC server and provides it to the CICS RPC Server. This module is available as source in the source data set EXP951.SRCE as well as precompiled in the load data set EXP951.LD00, so a C compiler is not needed.

• RCCALL, a COBOL subroutine calling your RPC server. This module is available as source in the CICS example server data set EXP951.DVCO.

A step-by-step description is given below, but for ease of use we recommend using the job RCIGY. See below.

To set up your server to be able to return application errors manually

1. Change the CALL statement of the RCCALL program below which your RPC server is called instead of "MyCobol" below

    IDENTIFICATION DIVISION.
      PROGRAM-ID.    RCCALL.
   
   ****************************************************************
   *                                                               
   *  CICS RPC Server                                              
   *                                                               
   *  Returning Application Errors from RPC Server to RPC Client   
   *                                                               
   *  This program calls your target COBOL Server.                 
   *                                                               
   *  For further information and explanation refer to             
   *  - "Writing Applications with the COBOL Wrapper"              
   *  in the delivered documentation.                              
   *                                                               
   *  $Revision: n.n $  
   *                                                               
   *                                                               
   *  Copyright (C) 1997 - 20nn Software AG, Darmstadt, Germany    
   *  and/or Software AG USA, Inc., Reston, VA, United States of   
   *  America, and/or their licensors.                             
   *                                                               
   ****************************************************************
   
    ENVIRONMENT DIVISION.
   
    DATA DIVISION.
      WORKING-STORAGE SECTION.
   
      LINKAGE SECTION.
   
      01 DFHCOMMAREA.
         10 DFHCOMM-DUMMY                  PIC X.
   
    PROCEDURE DIVISION USING DFHCOMMAREA.
   
    MAIN SECTION.
         CALL "my-cobol" USING DFHEIBLK DFHCOMMAREA.
   
    MAIN-EXIT.
         EXIT PROGRAM.
   
    END PROGRAM RCCALL.
   

2. In your RPC server, do not use EXEC CICS RETURN, because this prevents the return of the application error code to the CICS RPC server. If you are using a COBOL RPC server generated with the COBOL Wrapper, comment out or remove this line.

3. Compile the RCCALL program with a COBOL compiler supported by the COBOL Wrapper.

4. Link the compiled RCCALL program, the delivered ERXRCSRV module and your RPC server together to a CICS program to be called by the CICS RPC Server. See also Using the COBOL Wrapper for the Server Side for supported CICS scenarios.

To set up your server to be able to return application errors using job RCIGY

• Execute RCIGY as provided in the CICS example source data set EXP951.DVCO.

  This enhanced job will

  1. modify RCCALL as needed (step 1 from the manual approach, see above),

  2. add the modified RCCALL code to your COBOL input source (step 2 from the manual approach, see above),

  3. linkedits with ERXRCSRV (step 3 from the manual approach, see above).

Returning Application Errors from a Server under z/OS IMS to a Client

Follow the rules under Returning Application Errors from a Server under z/OS Batch to a Client and Using the COBOL Wrapper for IMS BMP (z/OS).

Note:
To enable this feature, configure the IMS RPC server with RETURN_CODE=YES.

www.softwareag.com

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

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT