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.

Last updated

Changed in 2021.
Changed for PUT00.

Format

#include <tpf/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: A 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: Determines whether the address in snapc_tag is an indirection. To indicate an indirection that points to a 31-bit address, code the defined term SNAPC_INDIR or SNAPC_IND31. To indicate an indirection that points to a 64-bit address, code the defined term SNAPC_IND64. If snapc_tag is not an indirection, code the defined term SNAPC_NOINDIR. The SNAPC_INDIR argument permits application compatibility between the TPF 4.1 and z/TPF systems. To indicate that the data will be translated using an ASCII translate table, code the defined term SNAPC_ASCII. The EBCDIC translation table is used as the default. If no storage list exists, code the defined term NULL.
The defined term SNAPC_F2GLOBAL indicates that the location of the area to be dumped (in snapc_tag) is a pointer to the 8-character name of a format-2 global record that will be used to get a format-2 global record address to dump. If the length of the area to be dumped is zero, the entire format-2 global record (up to a maximum of 32 KB), for the failing I-stream and subsystem user (SSU) will be dumped.

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

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 SNAPC_ECB defined term to take the subsystem and subsystem user names and the terminal address from the ECB. This argument is an integer.

Code the SNAPC_TRACE parameter to force the ECB trace (macro and function trace) to be dumped. The SNAPC_TRACE parameter dumps the 23 most recent function or macro trace entries, so there will only be 23 entries in the postprocessed SNAPC dump. Use the SERRC macro if more entries are required to solve the problem.

Note: SNAPC_NOECB is ignored for C language.

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. If coded as a valid 4-character basic assembler language (BAL) shared object (SO) function name, the SNAPC dump will display the name of the function and the name of the shared object.

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 <tpf/tpfeq.h>
#include <tpf/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):
}