Initiating Deliberate Dumps

You can use the Dump COBOL (QlnDumpCobol) bindable API to deliberately cause a formatted dump of an ILE COBOL program. The QlnDumpCobol API accepts six parameters which define the:
  • Program object name
  • Library name
  • Module object name
  • Program object type
  • Dump type
  • Error code.
The following are some examples of how to call the QlnDumpCobol API and the resultant operations: 
   WORKING-STORAGE SECTION.
   01  ERROR-CODE.
       05  BYTES-PROVIDED     PIC S9(6)  BINARY VALUE ZERO.
       05  BYTES-AVAILABLE    PIC S9(6)  BINARY VALUE ZERO.
       05  EXCEPTION-ID       PIC X(7).
       05  RESERVED-X         PIC X.
       05  EXCEPTION-DATA     PIC X(64).
   01  PROGRAM-NAME           PIC X(10).
   01  LIBRARY-NAME           PIC X(10).
   01  MODULE-NAME            PIC X(10).
   01  PROGRAM-TYPE           PIC X(10).
   01  DUMP-TYPE              PIC X.
   PROCEDURE DIVISION.
       MOVE LENGTH OF ERROR-CODE  TO BYTES-PROVIDED.
       MOVE "MYPROGRAM"           TO PROGRAM-NAME.
       MOVE "TESTLIB"             TO LIBRARY-NAME.
       MOVE "MYMOD1"              TO MODULE-NAME.
       MOVE "*PGM"                TO PROGRAM-TYPE.
       MOVE "D"                   TO DUMP-TYPE.
       CALL PROCEDURE "QlnDumpCobol"  USING PROGRAM-NAME,
                                            LIBRARY-NAME, MODULE-NAME,
                                            PROGRAM-TYPE, DUMP-TYPE,
                                            ERROR-CODE.
This would provide a formatted dump of COBOL identifiers (option D) for the module object MYMOD1 in program object MYPROGRAM in library TESTLIB. 
   WORKING-STORAGE SECTION.
   01  ERROR-CODE.
       05  BYTES-PROVIDED     PIC S9(6)  BINARY VALUE ZERO.
       05  BYTES-AVAILABLE    PIC S9(6)  BINARY VALUE ZERO.
       05  EXCEPTION-ID       PIC X(7).
       05  RESERVED-X         PIC X.
       05  EXCEPTION-DATA     PIC X(64).
   01  PROGRAM-NAME           PIC X(10).
   01  LIBRARY-NAME           PIC X(10).
   01  MODULE-NAME            PIC X(10).
   01  PROGRAM-TYPE           PIC X(10).
   01  DUMP-TYPE              PIC X.
   PROCEDURE DIVISION.
       MOVE LENGTH OF ERROR-CODE  TO BYTES-PROVIDED.
       MOVE "*SRVPGM"             TO PROGRAM-TYPE.
       MOVE "F"                   TO DUMP-TYPE.
       CALL PROCEDURE "QlnDumpCobol"  USING OMITTED, OMITTED,
                                            OMITTED, PROGRAM-TYPE,
                                            DUMP-TYPE, ERROR-CODE.

This would provide a formatted dump of COBOL identifiers and file related information (option F) for the service program that called the QlnDumpCobol API.

If any of the input parameters to the QlnDumpCobol API contain data that is not valid, the dump is not performed and an error message is generated or exception data is returned. An error message is generated if the BYTES-PROVIDED field contains zero. If the BYTES-PROVIDED field contains a value other than zero, then exception data is returned in the ERROR-CODE parameter and no error message is generated.

If you do not want a user to be able to see the values of your program's variables in a formatted dump, do one of the following:
  • Ensure that debug data is not present in the program by removing observability.
  • Do not call QlnDumpCobol in the program.

For detailed information on the QlnDumpCobol API, refer to the section about COBOL APIs in the CL and APIs section of the Programming category in the IBM® i Information Center at this Web site -http://www.ibm.com/systems/i/infocenter/.