cdump() — Request a main storage dump

Standards

Standards / Extensions C or C++ Dependencies
C Library both  

Format

#include <ctest.h>

int cdump(char *dumptitle);

General description

  1. Creates a display of the activation stack, by calling trace in the same way as the ctrace() function does.
  2. Displays the Language Environment-formatted dump.
  3. If the source file was compiled with TEST(SYM), cdump() displays the contents of the user's variables. The output is identified with dumptitle. See the CEE3DMP Language Environment callable service in z/OS Language Environment Programming Guide, to determine where the output is written to.

To avoid infringing on the user's name space, this nonstandard function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you use LANGLVL(EXTENDED).

To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile with LANGLVL(EXTENDED). When you use LANGLVL(EXTENDED) any relevant information in the header is also exposed.

When cdump() is invoked from a user routine, the C/C++ library issues an OS SNAP macro to obtain a dump of virtual storage. The first invocation of cdump() results in a SNAP identifier of 0. For each successive invocation, the ID is increased by one to a maximum of 256, after which the ID is reset to 0.

The output of the dump is directed to the CEESNAP data set. The DD definition for CEESNAP is as follows: 
    //CEESNAP DD SYSOUT= *

If the data set is not defined, or is not usable for any reason, cdump() returns a failure code of 1. This occurs even if the call to CEE3DMP is successful. For more information see "Debugging C/C++ Routines " in z/OS Language Environment Debugging Guide.

Returned value

If successful, cdump() returns 0.

If unsuccessful, cdump() returns nonzero.

Related information

Parent topic: Library functions