gtpc2m6yC/C++ Language Support User's Guide

snapc-Issue Snapshot Dump

This function causes the system error routine to issue a snapshot dump and display, optionally, a message (pointed to by msg) at the prime CRAS. Code action. as either SNAPC_EXIT to exit the ECB or as SNAPC_RETURN to return to the calling program.

Format

#include <tpfapi.h>
void   snapc(int action, int code, const char *msg,
            struct snapc_list **listc, char prefix, int regs,
            int ecb, const char *program);

action
The action of the ECB after the snapshot dump. This argument is an integer. Code the defined term SNAPC_EXIT to force the ECB to exit, or SNAPC_RETURN to cause a return to the calling program.

code
The identification number for the snapshot dump. This argument is an integer and should be a unique number ranging from 0 to X'7FFFFFFF'.

msg
This argument is a pointer to type char, which is a message text string to be displayed at the CRAS console and appended to the dump. The string must be terminated by \0 and must not exceed 255 characters.

If no message is desired, code the defined term NULL.

listc
This argument is a pointer to an array of pointers that point to type struct snapc_list, indicating areas of storage to be displayed on the dump. The snapc_list structure has four fields:

snapc_len
type short int, the length of the area to be dumped. Code zero for snapc_len to indicate no more areas are to be dumped.

snapc_name
character string, the name of the data area. snapc_name must be 8 characters long, left justified, and padded with blanks.

snapc_tag
the location of the area to be dumped.

snapc_indir
whether the address in snapc_tag is an indirection. To indicate an indirection, code the defined term SNAPC_INDIR. If snapc_tag is not an indirection, code the defined term SNAPC_NOINDIR.

If no storage list exists, code the defined term NULL.

Note:
There is a limit of 50 entries in the snapc_list array.

prefix
Specifies the prefix of the snapshot dump code. This argument is a character. It allows each application to have its own SNAPC code name space. You can use any uppercase alphabetic characters in the following ranges: A-H and J-V. The letters I and W--Z are reserved for IBM use. There is no default for this parameter.

regs
Code the defined term SNAPC_REGS to include the registers in the snapshot dump, or SNAPC_NOREGS to exclude the registers. This argument is an integer.
Note:
SNAPC_REGS is ignored for ISO-C.

ecb
Code the defined term SNAPC_NOECB to force the names of the subsystem and subsystem user to that of the basic subsystem. This renders the terminal address not available (N.A.). Code the defined term SNAPC_ECB to take the subsystem and subsystem user names and the terminal address from the ECB. This argument is an integer.
Note:
SNAPC_NOECB is ignored for ISO-C.

program
This argument is a pointer to type char, which is a text string indicating the program name to be used in the snapshot dump. The string must end in a -0 and should not be more than 16 characters. If the string exceeds this length it will be truncated. If coded as NULL , the program name is taken from the current program.

Normal Return

Void.

Error Return

Not applicable.

Programming Considerations

None.

Examples

The following example forces a snapshot dump bearing ID number 12345 and a prefix of A to be issued. The registers will be included in the dump and control will be returned to the program after the dump. The ECB will be used for the subsystem and subsystem user names, and terminal ID and the program name will be C001. The snapc_list is snapstuff and the message will be PROGRAM BLEW UP.

#include <tpfeq.h>
#include <tpfapi.h>
 
test()
{
 struct snapc_list *snapstuff[3],list[3];
 
 snapstuff[0]=(struct snapc_list *) &list[0];
 snapstuff[1]=(struct snapc_list *) &list[1];
 snapstuff[2]=(struct snapc_list *) &list[2];
 
/* Dump the 4 bytes of data in EBW000-EBW003.  */
 snapstuff[0]->snapc_len = 4;
 snapstuff[0]->snapc_name = "MYSTUFF ";
 snapstuff[0]->snapc_tag = &ecbptr()->ebw000;
 snapstuff[0]->snapc_indir = SNAPC_NOINDIR;
 
/* Dump the first 100 bytes of the core block on data level D0.  */
 snapstuff[1]->snapc_len = 100;
 snapstuff[1]->snapc_name = "DATA100 ";
 snapstuff[1]->snapc_tag = &ecbptr()->ce1cr0;
 snapstuff[1]->snapc_indir = SNAPC_INDIR;
 
 snapstuff[2]->snapc_len = 0;
 
 snapc(SNAPC_RETURN, 0x12345, "PROGRAM BLEW UP", snapstuff,
       'A', SNAPC_REGS, SNAPC_ECB, "C001");
 
 exit(0):
}

Related Information