General
Application area: | Debugging aids; see "Debugging aids" |
Macro type: | for user and system dumps only: |
The new CDUMP2 macro is available as of BS2000/OSD-BC V3.0.
Macro description
The CDUMP generates a dump (in its own dump task) for the task which has called CDUMP. By specifying the SCOPE operand, the user can determine whether an area dump, a user dump or a system dump is to be output.
Macro formats and description of operands
In the following format diagram, separate call formats are specified for generating a system dump, user dump or area dump.
Output of an area dump
CDUMP |
SCOPE=AREA,{NUM=#n / AREAS=((start1,end1),(start2,end2),...) } ,PC=STD / addr [,TITLE=addr ] ,MODE=STD / EXPANDED [,DS@=addr] ,MF=S / E / L / C / D [,PARAM=addr / (r)] ,ID=CD / pre |
Output of a system dump
CDUMP |
SCOPE=SYSTEM ,PC=STD / addr / (r) ,EC=STD / addr / (r) ,IW=STD / PC [, {CODE= {’name’ / ddr / (r)} / INSERT= {addr / (r)}}] [,TITLE=addr / (r)] ,DIAG=NO / YES [,ELSN=addr / (r)] ,PARMOD=24 / 31 ,MF=S / L / (E,..) / D ,ID=CD / pre |
Output of a user dump
CDUMP |
[SCOPE=USER] ,PC=STD / addr / (r) ,EC=STD / addr / (r) ,IW=STD / PC [, {CODE= {’name’ / addr / (r)} / INSERT= {addr / (r)}}] [,TITLE=addr / (r)] ,DS=STD / NO / YES / listaddr ,DIV=STD / NO / YES ,PARMOD=24 / 31 ,MF=S / L / (E,..) / D ,ID=CD / pre |
The operands are described in alphabetical order below.
AREAS=
Defines the areas to be included in the dump by means of their start and end addresses. These may be specified in any form permissible for an address constant (see example). A list of up to 4 memory areas may be specified. AREAS is prohibited if MF=C/D is specified.
((start1,end1),....)
start1 = address of the first byte (start address) of the memory area to be dumped.end1 = address of the last byte (end address) of the memory area to be dumped.
CODE=
Gives a string which identifies the dump. This character string is output with message IDA0N51. This operand is permitted only in conjunction with SCOPE=USER/SYSTEM.
addr
Symbolic address of the field with any character string;
length = 7 bytes.
(r)
Register containing the address value “addr”.
'name'
name = any character string; length = 7 characters.
DIAG=
Determines whether or not a message indicating the address of the CDUMP-SVC is sent to the operator. This operand is permitted only in conjunction with SCOPE=SYSTEM.
NO
Default setting: no message is output.
YES
The message is output.
DIV=
Specifies whether DIV windows are to be included in the user dump. This operand may be specified only in conjunction with SCOPE=USER and is not evaluated unless PARMOD=31.
If PARMOD!=31 the value DIV=YES is used irrespective of the parameter specification. See also the section “Extended addressing with data spaces”.
STD
Default setting: the value set in the MODIFY-TEST-OPTIONS command determines whether DIV windows are to be included in the user dump (YES) or not (NO).
NO
No DIV windows are to be included in the user dump.
YES
All DIV windows are to be included in the user dump.
DS=
Determines which data spaces (DS) are to be included in the user dump. This operand may be specified only in conjunction with SCOPE=USER and is not evaluated unless PARMOD=31. If PARMOD!=31 the value DS=YES is used irrespective of the parameter specification. See also the section “Extended addressing with data spaces”.
STD
Default setting: the value set in the MODIFY-TEST-OPTIONS command determines whether data spaces are to be included in the user dump (YES) or not (NO).
listaddr
Address of a list of SPIDs (8 bytes per entry). The list must end with a zero entry (D(0)).
NO
No data spaces are to be included in the user dump.
YES
All data spaces (up to 100 data spaces used by the caller) are to be included in the user dump.
DS@=
Points to a data space control block (DSCB) whose DSECT is generated with MF=D. A data space and its associated areas can be defined in the DSCB. This operand may be specified only in conjunction with SCOPE=AREA.
Data structure of a DSCB:
CDDDSCB DSECT , DATA SPACE CTRL BLOCK CDDDS@ DS A Points to the next DSCB CDDSPID DS XL8 SPID of the DS CDDNUM DS H Number of areas in the DS CDDSTRT DS A Start of the first area CDDEND DS A End of the first area
By chaining DSCBs, users can specify areas of more than one data space of their task. By default, no areas of a data space are specified.
See also the section “Extended addressing with data spaces”.
addr
Symbolic address of the DSCB.
addr = NULL is the default value.
EC=
Defines the location from which the event code (interrupt weight) is to be fetched. This specification is permissible only in conjunction with SCOPE=USER/SYSTEM; for SCOPE=AREA the event code is always fetched from the calling stack.
STD
Default setting: the event code is to be fetched from the calling stack.
addr
Symbolic address of the field containing the event code.
(r)
r = Register containing the event code (right-justified)
ELSN=
Specifies the address of a field containing the number of an Error Log Sequence Block to which specific data of the error logging file has been written by the caller.
Field length = 4 bytes, which must be aligned on a word boundary. The number must be entered as a binary digit. This operand is only permitted in conjunction with SCOPE=SYSTEM.
addr
Symbolic address (name) of the field
(r)
r = Register containing the address value “addr”
INSERT=
Defines a text to be output with the message IDA0N51. This text could contain more detailed information on the cause of the dump.
The user must place this text, which may be up to 60 characters long, in a data area with the following format:
Byte 1: | Length (hexadecimal) of the text to be output (in bytes). If byte 1 has the value |
Byte 2 through n (n<=61): Text to be output.
The INSERT operand is ignored when SCOPE=AREA.
addr
Symbolic address of the data area which contains length specification and text.
(r)
r= Register with the address of the data area which contains length specification and text
IW=
Defines the location from which the interrupt weight is to be fetched. This specification is permissible only in conjunction with SCOPE=USER and only for the 24-bit interface. The operand is supported for compatibility reasons only; EC=... should be used in programs instead.
STD
Default setting: specifies that the interrupt weight is to be fetched from the calling stack.
PC
Specifies that the interrupt weight is contained in byte 1 of the field/register specified with the PC operand.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
A prefix ID (pre = 2 letters) can be specified for MF=C or MF=D, as shown in the macro format.
The following operands must be specified for area dumps: the SCOPE operand if MF=C/D/E and additionally the NUM operand if MF=C/D.
For system dumps, the SCOPE operand is mandatory if MF=C/D/E.
MODE=
Defines the scope of the diagnostic data to be output for an area dump. The operand may be specified only in conjunction with SCOPE=AREA.
STD
Default setting: ensures that only the AIDSYSD module and the areas with COMAREA, P1-PCB and TCB are dumped in addition to the specified areas in class 6 and class 5 memory (see the section describing macros and area dumps).
EXPANDED
Initiates dumping of the area with COMAREA and all other system areas as in user dump in addition to the areas specified in class 6 and class 5 memory (see the section describing macros and user dumps).
NUM=
Gives the number of areas to be dumped. NUM is permissible only in conjunction with MF=L/C/D. The start and end addresses of the areas to be dumped must be entered in the generated operand list (dynamically). If MF=C/D, NUM is mandatory.
#n
n = Number of areas to be dumped; 1 <= n <= 2048.
(The '#' character must precede the number).
PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit-interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro.
24
This specification is not permissible in conjunction with SCOPE=AREA. The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).
31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb). Data lists start with the standard header.
PC=
Defines a register or field containing the program counter to be logged.
STD
Default setting: the program counter is to be fetched from the calling stack.
addr
Symbolic address (name) of the field (word) containing the program counter.
(r)
r = Register containing the program counter. This specification is permissible only in conjunction with SCOPE=USER/SYSTEM.
SCOPE=
Defines whether a user, system or area dump is to be generated.
USER
Default setting: a user dump is generated.
SYSTEM
A system dump is generated. This specification may be entered by users with a read privilege >= 3 only.
AREA
An area dump is generated.
TITLE=
Defines a second title line for the memory dump
(length = 132 characters).
Note
This operand is still supported for reasons of compatibility only, i.e. DAMP does not process this title line. Specifying this operand therefore has no effect.
addr
Symbolic address of the field containing the title line.
(r)
r = Register containing the address value “addr”. This specification is permissible only in conjunction with. SCOPE=USER/SYSTEM
Return information and error flags
R15 / standard header:
+---------------+ | | | | | | | | | | | |a|a| +---------------+
A return code relating to the execution of the CDUMP macro is transferred in the rigtmost byte of register R15. When using the 31-bit-interface, the return code is additionally transferred in the standard header (main code).
X'aa' | Meaning |
X'00' | Dump completed without errors. |
X'04' | Dump completed using default values. |
X'08' | Dump suppressed due to /OPTION DUMP operand. |
X'0C' | Dump suppressed due to systems standards. |
X'10' | Dump suppressed due to severe CDUMP operand error. |
X'14' | Dump suppressed due to insufficient test privilege. |
X'18' | Dump suppressed due to error in DMS routines. |
X'1C' | Dump suppressed due to system error. |
X'20' | Dump suppressed due to previous interruption of CDUMP. |
X'24' | Dump suppressed due to foreign task dump error. |
X'28' | Dump suppressed due to shutdown processing. |
X'2C' | Dump suppressed by calling task. |
X'30' | All area specifications are invalid. No dump is output. |
X'34' | Incorrect specification for NUM=.... No dump is output. |
X'38' | Some dump areas are not located in the caller' s address space or the specifications are |
X'3C' | Dump suppressed since “DMS READY” has not yet been reached. |