The user library interface to DUMPANALYZER has two entry points, which are invoked through DUMPANALYZER commands. Dump file information is provided to the two entry points in the user library interface through a mechanism called the USER_DUMP_INFO procedure.
The two entry points and their corresponding DUMPANALYZER commands are as follows:
-
The LIBDATA entry point, invoked by the command USERLIB
-
The USERCOMMAND entry point, invoked by the command USERCOMMAND
The USERLIB command and the USERCOMMAND are discussed in their respective subsections under “DUMPANALYZER Commands.”
The two entry points and the USER_DUMP_INFO procedure are discussed in the paragraphs that follow in this section.
LIBDATA Entry Point
The LIBDATA entry point is invoked by the USERLIB command. Its purpose is to display status information, such as
-
The current version of the user library
-
A list of current commands processed by the user library
LIBDATA Entry Point Declaration
The following example is a declaration in ALGOL of the heading of the LIBDATA entry point. An explanation of the parameters follows.
PROCEDURE LIBDATA (CALLV, USER_DUMP_INFO, PL, PRINT); VALUE CALLV; REAL CALLV; POINTER PL; REAL PROCEDURE USER_DUMP_INFO (UTYPE, VAL, UTAGS, UDATA, RESULT); REAL UTYPE, VAL, RESULT; ARRAY UTAGS, UDATA[0]; FORMAL; PROCEDURE PRINT (SPACES); VALUE SPACES; INTEGER SPACES; FORMAL;
The parameters used in this declaration heading for LIBDATA are as follows.
|
Parameter |
Meaning |
|---|---|
|
CALLV |
Bit 0 has the value 0 when the USERLIB command is called with a title string, and has the value 1 when the call is made without a title string. When the USERLIB command is used with a title string, the following bits indicate specific machines: Bit 47 is set if the dump is from an ASD machine Bit 46 is set if the dump is from a level GAMMA machine Bit 45 is set if the dump is from a TCP machine Bit 44 is set if the dump is from a level DELTA machine Bit 43 is set if the dump is from a level EPSILON machine Bit 42 is set if the dump is from a level Eta machine |
|
USER_DUMP_INFO (UTYPE, VAL, UTAGS, UDATA, RESULT) |
USER_DUMP_INFO is the DUMPANALYZER procedure that gives the entry point access to data contained in the dump file. The parameters of the procedure are described under “USER_DUMP_INFO Procedure,” later in this section. |
|
PL |
This is the pointer to the current DUMPANALYZER output buffer. Any information to be displayed to the user through the DUMPANALYZER output procedure should be inserted using this pointer. It points to a 3168 character array. |
|
|
This procedure provides access to the output capabilities of DUMPANALYZER. The output returned by the procedure is the contents of the current output buffer, in accordance with current DUMPANALYZER output format options. The number of characters returned as output is determined by the offset value of the PL pointer. The SPACES parameter determines how many lines of blank output will follow the characters. |
USERCOMMAND Entry Point
The USERCOMMAND entry point is invoked by the USERCOMMAND command. Its purpose is to carry out instructions that you define in the parameter string and memory address that you specify as input to the command. You can perform an analysis of any area of memory or of other information contained in the dump file.
USERCOMMAND Entry Point Declaration
The following example is a declaration in ALGOL of the heading of the USERCOMMAND entry point. An explanation of the parameters follows.
PROCEDURE USERCOMMAND (PARAMS, MEM_ADDR, USER_DUMP, PL,PRINT);
VALUE MEM_ADDR;
REAL MEM_ADDR
ARRAY PARAMS[0];
POINTER PL;
REAL PROCEDURE USER_DUMP_INFO (UTYPE, VAL, UTAGS, UDATA, RESULT);
VALUE UTYPE, VAL;
REAL UTYPE, VAL, RESULT;
ARRAY UTAGS[0], UDATA[0];
FORMAL;
PROCEDURE PRINT (SPACES)
VALUE SPACES;
INTEGER SPACES;
FORMAL;The parameters used in this declaration heading for USERCOMMAND are as follows.
|
Parameter |
Meaning |
|---|---|
|
PARAMS |
This array contains the contents of the user-specified parameter string. The number of characters in the string is specified in the first byte of the array. |
|
MEM_ADDR |
This is the <simple address> value specified by the user. If no address was specified, then its value is 0. |
|
USER_DUMP_INFO (UTYPE, VAL, UTAGS, UDATA, RESULT) |
USER_DUMP_INFO is the DUMPANALYZER procedure that gives the entry point access to data contained in the dump file. The parameters of the procedure are described under “USER_DUMP_INFO Procedure,” later in this section. |
|
PL |
This is the pointer to the current DUMPANALYZER output buffer. Any information to be displayed to the user through the DUMPANALYZER output procedure should be inserted using this pointer. It points to a 3168 character array. |
|
|
This procedure provides access to the output capabilities of DUMPANALYZER. The output returned by the procedure is the contents of the current output buffer, in accordance with current DUMPANALYZER output format options. The number of characters returned as output is determined by the offset value of the PL pointer. The SPACES parameter determines how many lines of blank output will follow the characters. |
USER_DUMP_INFO Procedure
USER_DUMP _INFO is the DUMPANALYZER procedure that gives the entry point access to data contained in the dump file. The parameters are as follows.
|
Parameter |
Meaning |
|---|---|
|
UTYPE |
Specifies the type of the data requested. |
|
VAL |
Contains the real value required for certain types of requests. |
|
UTAGS |
Returns memory tag values for certain types of requests. For E-mode Epsilon, each word that is used to return the tag also returns the word extension in fields as follows: TAG – field [ 7: 8] EXT – field [23:16] |
|
UDATA |
Contains required values or returns memory word values, depending on type of request. |
|
RESULT |
Returns an error number if the request fails. |
|
USER_DUMP_INFO |
The procedure value is returned for certain types of requests. |
The type of a request to be performed for a given call of the procedure is determined by the TYPE and SUBTYPE fields of the UTYPE parameter.
The TYPE field is [15:16] and the SUBYTPE field is [31:16]. If a request fails, bit 0 will be set and the error number will be returned in the error number field of the RESULT parameter, which is [19:16].
Whenever the UTAGS and UDATA arrays are used to return information and they are of insufficient size to store the information, they will be resized as required.
USER_DUMP_INFO Request Types
This section describes the following request types, which are handled by the USER_DUMP_INFO procedure:
-
Memory word request
-
Descriptor information request
-
Memory array request
-
TCPINFO stack request
-
TCPINFO event request
-
Stack information request
-
Extended stack information request
-
ASD information request
-
Dump information request
For any request, the following error numbers can be returned.
|
Condition |
RESULT Error Number Returned |
|---|---|
|
An invalid TYPE value was passed |
1 |
|
An invalid SUBTYPE value was passed |
2 |
|
A fault occurred while DUMPANALYZER was processing the request |
3 |
The following tables describe the parameter values for each request type.
Memory Word Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 1 SUBTYPE = 0 Memory Word Request SUBTYPE = 1 Simple Address Request SUBTYPE = 2 Simple Value Request |
|
VAL |
If SUBTYPE = 0, should contain the address of the requested memory word |
|
UTAGS |
Returns the tag value of the requested memory word in word 0 (SUBTYPES 0 and 2) The TAG is returned in field [7:8] of the UTAGS word and the E-mode Epsilon and Eta word extension EXT is returned in [23:16] of each UTAGS word |
|
UDATA |
If SUBTYPE = 1, should contain the <simple address> string, null terminated If SUBTYPE = 2, should contain the <simple value> string, null terminated |
|
RESULT Error Numbers |
Returns 100 if memory address is invalid |
|
USER_DUMP_INFO |
If SUBTYPE = 0, returns contents of requested memory word If SUBTYPE = 1, returns address of requested <simple address> string If SUBTYPE = 2, returns the value of requested <simple value> string |
Examples
To obtain the address of the descriptor for the CONFIGURATION array, use the following format:
REPLACE POINTER(INFO) BY "G CONFIGURATION", 48"00"; ADDR := USER_DUMP_INFO(ADDRV & 1 USUBTYPE,0,UTAGS,INFO,RES);
To obtain the descriptor for the CONFIGURATION array, use the following format:
REPLACE POINTER(INFO) BY "C(G CONFIGURATION", 48"00"; DESC := USER_DUMP_INFO(ADDRV & 2 USUBTYPE,0,UTAGS,INFO,RES); TAGG := UTAGS[0];
Descriptor Information Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 2 SUBTYPE = 0 Descriptor address request SUBTYPE = 1 Descriptor length request SUBTYPE = 2 Descriptor ASD request |
|
VAL |
Should contain the target descriptor |
|
UTAGS |
Word 0 should contain the tag value of the target descriptor in field [7:8] and the E-mode Epsilon and Eta word extension of the target descriptor in [23:16] |
|
UDATA |
Not used |
|
RESULT Error Numbers |
Returns 7 if the tag value is not that of a descriptor |
|
USER_DUMP_INFO |
If SUBTYPE = 0, returns ADDRESS of target descriptor If SUBTYPE = 1, returns LENGTH of target descriptor If SUBTYPE = 2, returns ASD number of target descriptor |
Memory Array Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 3 SUBTYPE = 0 Array words descriptor address request SUBTYPE = 1 Array words descriptor request SUBTYPE = 2 Array words ASD request |
|
VAL |
If SUBTYPE = 0, should contain the address of target array's descriptor If SUBTYPE = 1, should contain the descriptor to the target array If SUBTYPE = 2, should contain the ASD of the target array |
|
UTAGS |
If SUBTYPE = 1, word 0 should contain the tag value of the descriptor to the target array in field [7:8] and the E-mode Epsilon and Eta word extension of the descriptor to the target array in [23:16] |
|
UDATA |
Returns the values of the target array |
|
RESULT Error Numbers |
Returns 7 if SUBTYPE=0 and the VAL address was not that of a descriptor Returns 7 if SUBTYPE = 1 and VAL was not a valid descriptor Returns 9 if SUBTYPE = 2 and the VAL value was not a valid ASD Returns 300 if the target array was not present Returns 301 if the target array had zero length |
|
USER_DUMP_INFO |
Returns the number of words stored in the UDATA array |
TCPINFO Stack Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 5 SUBTYPE = 0 |
|
VAL |
Should contain the stack number of the target process |
|
UTAGS |
Not used |
|
UDATA |
Returns the TCPINFO for the target process |
|
RESULT Error Numbers |
Returns 4 if no TCPINFO is available for the target process Returns 10 if the dump is not from a TCP machine |
|
USER_DUMP_INFO |
Returns the number of words written to the UDATA array |
TCPINFO Event Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 6 SUBTYPE = 0 |
|
VAL |
Should contain the target event number |
|
UTAGS |
Not used |
|
UDATA |
Returns the TCPINFO for the target event |
|
RESULT Error Numbers |
Returns 4 if no TCPINFO is available for the target event Returns 10 if the dump is not from a TCP machine |
|
USER_DUMP_INFO |
Returns the number of words written to the UDATA array |
Stack Information Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 7 SUBTYPE = 0 Stack data given name request SUBTYPE = 1 Stack data given stack number request |
|
VAL |
Not used |
|
UTAGS |
Not used |
|
UDATA |
Tables 9–1 through 9–4 describe the contents and the results returned. |
|
RESULT Error Numbers |
Returns 5 if SUBTYPE=0 and UDATA array is less than 7 words Returns 8 if an invalid stack number is specified Returns 700 if a nonresident stack number is specified Returns 710 if the mix or job number associated with the stack is larger than 65535. If so, the associated fields in UDATA contain a zero value. |
|
USER_DUMP_INFO |
Returns the number of words written to the UDATA array |
Extended Stack Information Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE =10 SUBTYPE = 0 Stack data given name request SUBTYPE = 1 Stack data given stack number request |
|
VAL |
Not used |
|
UTAGS |
Not used |
|
UDATA |
UDATA Parameter Contents for Stack Information Request, SUBTYPE=0 through UDATA Parameter Returns for Extended Stack Information Request, SUBTYPE=0,1 describe the contents and the results returned. |
|
RESULT Error Numbers |
Returns 5 if SUBTYPE=0 and UDATA array is less than 7 words Returns 8 if an invalid stack number is specified Returns 700 if a nonresident stack number is specified |
|
USER_DUMP_INFO |
Returns the number of words written to the UDATA array |
UDATA Parameter Contents for Stack Information Request, SUBTYPE=0 through UDATA Parameter Returns for Extended Stack Information Request, SUBTYPE=0,1 list the UDATA parameter contents for the Stack Information Request.
Table 4. UDATA Parameter Contents for Stack Information Request, SUBTYPE=0
|
Word |
Field |
Description |
|
0 |
Optional Stack Number at which name search should start. If omitted, search will start at MCP stack number. |
|
|
5 |
47:32 |
Optional Stack Kind (4–char description, with blanks and punctuaion marks counted as characters-MPC , I.R., INTR,LIB , SEGD, JOB ,TASK, DBTS) If specified, only stacks with that KIND value will be checked. |
|
15:16 |
Length of Stack Name |
|
|
6 - end |
Stack Name of target stack. If usercodes and/or pack names are included in the name, then those elements will be checked in the name search. Otherwise, any usercode and/or pack name will match. |
Table 5. UDATA Parameter Contents for Stack Information Request, SUBTYPE=1
|
Word |
Field |
Description |
|
0 |
Stack Number of target stack |
Table 6. UDATA Parameter Contents for Stack Information Request, SUBTYPE=0,1
|
Word |
Field |
Description |
|
0 |
Stack Number |
|
|
1 |
31:16 |
Job Number |
|
15:16 |
Task Number |
|
|
2 |
BOSR |
|
|
3 |
Stack Length |
|
|
4 |
PIB Address |
|
|
5 |
47:32 |
Stack Kind (4 char description - MPC, I.R., INTR,LIB , SEGD, JOB ,TASK, DBTS) |
|
15:16 |
Length of Stack Name If SUBTYPE=0, this is same length passed in. |
|
|
6 - end |
Stack Name If SUBTYPE=0, this is same name passed in. |
Table 7. UDATA Parameter Returns for Extended Stack Information Request, SUBTYPE=0,1
|
Word |
Field |
Description |
|
0 |
Stack Number |
|
|
1 |
Job Number |
|
|
2 |
Task Number |
|
|
3 |
BOSR |
|
|
4 |
Stack Length |
|
|
5 |
PIB Address |
|
|
6 |
47:32 |
Stack Kind (4 char description - MPC, I.R., INTR,LIB , SEGD, JOB, TASK, DBTS) |
|
15:16 |
Length of Stack Name If SUBTYPE=0, this is same length passed in. |
|
|
7 - end |
Stack Name If SUBTYPE=0, this is same name passed in. |
ASD Information Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 8 SUBTYPE = 0 Returns ASD table entry SUBTYPE = 1 Returns total number of ASD table entries SUBTYPE = 2 Returns maximum number of allocated ASD table entries |
|
VAL |
If SUBTYPE = 0, should contain the target ASD number |
|
UTAGS |
If SUBTYPE = 0, returns the tags of the ASD table entry words for the target ASD |
|
UDATA |
If SUBTYPE = 0, returns ASD table entry words for the target ASD |
|
RESULT Error Numbers |
If SUBTYPE = 0, returns 9 if an invalid ASD number is specified |
|
USER_DUMP_INFO |
If SUBTYPE = 0, returns the number of words written to the UDATA array If SUBTYPE = 1, returns the total number of ASD table entries If SUBTYPE = 2, returns the maximum number of allocated ASD table entries |
Dump Information Request
|
Parameter |
Value |
|---|---|
|
UTYPE |
TYPE = 9 SUBTYPE = 0 |
|
VAL |
Not used |
|
UTAGS |
Not used |
|
UDATA |
Returns dump information, as shown in UDATA Parameter Returns for Dump Information Request. |
|
RESULT Error Numbers |
No specific values for this request |
|
USER_DUMP_INFO |
Returns the number of words written to the UDATA array |
UDATA Parameter Returns for Dump Information Request lists UDATA parameter returns for the Dump Information Request.
Table 8. UDATA Parameter Returns for Dump Information Request
|
Word |
Field |
Description |
|
0 |
Machine type |
|
|
1 |
Processor Model Number |
|
|
2 |
Dump Reason Word 1 |
|
|
3 |
Dump Reason Word 2 |
|
|
4 |
Dump Reason Word 3 |
|
|
5 |
Dump Date (YYMMM) |
|
|
6 |
Dump Time (Time of day in 2.4 microseconds) |
|
|
7 |
Clock (Time since H/L in 2.4 usecs) |
|
|
8 |
[31:16] |
Length of MCP name |
|
[15:16] |
Word index location of MCP name |
|
|
9 |
[47:16] |
MCP release level |
|
[31:16] |
MCP cycle level |
|
|
[15:16] |
MCP patch level |
|
|
10 |
MCP creation timestamp, in Time (6) format |
|
|
11 |
D0 Address |
|
|
12 |
System serial number |
|
|
13 |
[31:16] |
Length of Hostname |
|
[15:16] |
Word index of Hostname |
Sample ALGOL User Library
An example program, *EXAMPLE/DUMPANALYZER/USERLIB/ALGOL, is provided that can be used as a starting point for developing a DUMPANALYZER User Library program. It contains library entry point declarations, useful defines and the code and defines necessary to process four different types of requests from DUMPANALYZER. The request handling code also contains sample help text using an Output Message Array. The request handling code is easy to extend to handle additional types of requests.
