Working with procedures (special window: PROC)

Every PRODAMP procedure can be called either from the DAMP program level or as a subroutine. In the first case, the procedure is called either after compilation by specifying MODE=Xqt or MODE=Go, by means of the DAMP statement RESUME-PRODAMP-PROGRAM (with the option of passing parameters), or using the DAMP statement START-PRODAMP-PROGRAM, should the PRODAMP procedure be in a library in the form of an object (here also with the option of passing parameters).

A PRODAMP procedure can be called as a subroutine only if it is stored in object form in a library or if it has already been compiled and is currently in a PROC window. The procedure is then called by specifying its name together with the list of parameters, if appropriate. The procedure name is identical to the element name of the PRODAMP object in the library (see section "Archiving private procedures").

Creating private procedures

The creation of PRODAMP procedures comprises two components: editing and compilation.

In order to create a procedure, the PRODAMP compiler must first be assigned to one of the dump windows. This is done using the following statement:

START-PRODAMP-EDITOR WINDOW=<w>, SOURCE=filename

WINDOW	Specifies the window (4 to 9 or 21 to 99) in which the PRODAMP procedure is to be edited, compiled and possibly executed.
SOURCE	Specifies a file that already contains a PRODAMP source file. This file is then read immediately into the specified window. This specification is optional.

A window being used by a PRODAMP procedure is not reset when the dump file is switched by means of the DAMP statement OPEN-DIAGNOSIS-OBJECT.

Input fields in the PROC window

Figure 67: Dump window to which the PRODAMP compiler has been assigned

Within a procedure that has been read in or written, it is possible to scroll back (+nn) and forth (-nn) or position to a specific line (#nn) in the same way as in EDT. You can also enter text in the header line and in the text lines. Entries in the header line (“Procedure”, “Version” and “Mode”) initiate PRODAMP functions, while entries in the program lines are regarded as changes to these lines.

Meanings of the three fields in the header line

Mode	Mode; specifies what is output in the dump window or what action the PRODAMP compiler is currently performing or is to perform. Entering one of the following strings and sending the screen off by hitting the   key triggers the corresponding action.
=Beg =Cmp =Dsp	(Begin); positions the window to line 1 of the source file. (Compile); starts the compiler for the current contents of the window. (Display); default setting for modifying source file lines within the PRODAMP window.
=Edt	(Edit); transfers the current PRODAMP procedure to an EDT area. Major changes to the PRODAMP source file should always be made in EDT. The PRODAMP window permits only simple editing functions (scrolling, overwriting, deleting). When the editor is terminated by means of END, HALT or RET, the edited source file is transferred back to the PRODAMP window and the EDT area is then cleared.
=Go =Inf	is equivalent to “compile + execute + begin”. (Inform); outputs a list of the source elements contained in the current source library and releases a lock set using Lck (Lock). If the keyword OBJECT is entered in the “Procedure” field, the display switches to the directory of the object elements. By the same token, entering SOURCE restores the original display.
=Lck	(Lock); has the same effect as Read, but also locks the element of the source library to be read against concurrent accesses. The lock is released using Update, New or Inform. New and Inform do not change the original contents of the library. Only Update overwrites the old data.
=New	clears the PRODAMP window so that a new PRODAMP procedure can be displayed. Any lock set by Lck (Lock) is canceled. The system does not request confirmation. The PRODAMP window is cleared without a request for confirmation.
=Rea	(Read); an element is read from the selected source library. As for M=Wrt, the element name and the version are taken from the fields “Procedure” and “Version” in the header line. If no version is specified, DAMP automatically accesses the highest existing version.
=Sav	(Save); stores a PRODAMP object in the selected object library. The name specified in the “Procedure” field is used as the element name, and the number specified in the “Version” field is used as the version number. An element with the same name and version will be overwritten without first asking for confirmation.
=Upd	(Update); in the selected source library the element with the name specified in the “Procedure” field and the version specified in the “Version” field is overwritten. Any lock set using Lck is released. If there was no element with this version, an error message is issued. In this case, Mode=Wrt must be used.
=Wrt	(Write); the current source is written to the library set via ASSIGN or to the default library. The name specified in the “Procedure” field is used as the element name, and the number specified in the “Version” field is used as the version number. If no version is specified, DAMP automatically assumes 001. An existing element with the same name and version will not be overwritten unless explicitly requested by way of Mode=Upd.
=Xqt	(execute); executes a compiled PRODAMP procedure.
Procedure	Displays the name of the procedure currently being output.
Version	Specifies the version of the procedure with the specified name.

Useful information for practical application

The following sequence of actions is recommended when trying out PRODAMP for the first time:

• Start PRODAMP using START-PRODAMP-EDITOR.

• Switch to EDT via Mode=Edt.

• Edit the PRODAMP procedure in EDT.

• If desired, save the procedure by means of WRITE.

• Return to DAMP by entering HALT.

• Compile the procedure via Mode=Cmp.

• If necessary, correct any syntax errors in the PROC window or using EDT again.

• Execute the syntactically correct procedure via Mode=Xqt.

• If necessary, debug the procedure.

Common errors

• A symbol which can be localized automatically is entered without the period that forms part of the symbol. As a result, PRODAMP does not recognize this as a symbol, but interprets it as a variable.

• When using symbols, the programmer forgets that the types and lengths of the symbols are not known until runtime. If a value is assigned to a variable which has not been initialized, the variable can thus receive only the default type (numeric, length 4). It is therefore best to declare all variables by initializing them.

• After accessing the object to be diagnosed, you forget to check the value of the pseudo-symbol CURRENT.ERROR and continue working with meaningless values.

• The rules governing truncation and padding when assigning string variables of different lengths to each other are not taken into account.

• When the object library is switched, object modules which were loaded from the first object library are not deleted from memory. If, for example, a procedure with the name “PROC” is loaded from one object library by means of the START-PRODAMP-PROGRAM statement, “START-PRODAMP-PROGRAM PROC” will still call this procedure after switching to another object library, even if the new library contains another procedure with the same name.

Cleaning up addresses

In addressing mode 31, PRODAMP cleans up the addresses in the following cases during execution:

• if a numeric variable is used as the base for a symbolic access.

  Example

  P := X'82CD0000';
  A := P.ESTKGR0;
  

  Here, depending on the addressing mode, only X'02CD0000' or X'82CD0000' is used in the second statement to form the address.

• if the numeric variable is used as the input for the standard function LOCATION.

  For DAMP, the addressing mode is a global constant that depends on the HSI. On /390 servers, DAMP uses 31-bit addressing. On x86 servers, DAMP uses 32-bit addressing. It may therefore be necessary, particularly when using PRODAMP procedures for the diagnosis of user programs, to clean up the addresses there “manually” into 24-bit addresses.

  Example

  X'887C240C' MOD X'01000000' produces X'007C240C'.

Passing parameters to PRODAMP

There are four ways of passing parameters to PRODAMP:

• by means of RESUME-PRODAMP-PROGRAM

• by means of START-PRODAMP-PROGRAM

• by making the appropriate entry in the procedure window, and then compiling and starting the run. In this case, the procedure should be written so that the variables which are to accept the parameters are contained in the first lines of the procedure. Then issue a MODIFY-SCREEN-LAYOUT statement to arrange the windows so that only these initial lines (with the parameter variables) are visible in the PRODAMP window. If you then overwrite the values for the parameters in this window with the current values and select the option “Go” (for “compile and go”), the procedure is recompiled and executed with the new values.

• by means of the standard PRODAMP procedure READ_WINDOW

Effects of PRODAMP on the list output

All pages in the diagnosis object which are referenced during execution of a PRODAMP procedure are regarded as referenced pages for a subsequent list output (just like pages referenced during a DAMP dialog). They are thus automatically included in a minimum list output. This feature can be used to explicitly reference in PRODAMP all the pages that are definitely to be printed.

Using EDT as a “replacement window”

The PRODAMP statements WRITE and READ, which write into and read from an EDT area, can be used to obtain pseudo-formatted dialog outputs. For this, only the following PRODAMP statements are necessary:

WRITE ('desired information');
....
WRITE ('desired information');
WRITE ('@COL 80 O & C'' '''); 'Truncate all lines to max. 80 characters'
WRITE ('@PRO9');              'Switch to procedure area 9'
WRITE ('@DEL');               'Delete'
WRITE ('@@PRINT1-.$VN);       'Enter PRINT statement'
WRITE ('@END');               'Switch back procedure area'
WRITE ('@DO9');               'Display the lines on the screen'

Truncation of the lines is necessary because the WRITE statement always pads the PRODAMP string with blanks up to the maximum length (133). 

Example: guided input

ABC := ' '*4; XYZ := ' '*10;
WRITE ('@PRO9');
WRITE ('@DEL');
WRITE ( '@@CREATE1READ''PLEASE ENTER ABC''' );
WRITE ('@END');
WRITE ('@DO9');
READ ( ABC );
WRITE ( '@DEL' );
WRITE ('@PRO9');
WRITE ('@DEL');
WRITE ( '@@CREATE1READ''PLEASE ENTER XYZ''' );
WRITE ('@END');
WRITE ('@DO9');
READ ( XYZ );
WRITE ( '@DEL' );

The WRITE “@D” statements are needed to ensure that the READ statement starts at the first record of the EDT area each time. The sequence of statements shown above could be abbreviated as follows:

ABC := ' '*4; XYZ := ' '*10;
WRITE ('@PRO9');
WRITE ('@D');
WRITE ( '@@CREATE1READ''PLEASE ENTER ABC''' );
WRITE ( '@@CREATE2READ''PLEASE ENTER XYZ''' );
WRITE ('@END');
WRITE ('@DO9');
READ ( ABC );
READ ( XYZ );
WRITE ( '@D' );

Reading via READ always uses the actual length of the EDT record. The remaining characters of the string variable remain unchanged.

In addition, the string variables should always be initialized, since the default length of 133 will otherwise be assumed. 

List output via the COMMAND statement

Any DAMP statements issued via COMMAND must be formulated as if they had been entered in batch or procedure mode.
This is especially important for printing lists. For this reason, the required specifications must be entered by means of the ADD-LIST-OBJECTS statement.

Example

COMMAND ('START-LIST-GENERATION');         "Switch to LIST mode"
COMMAND ('ADD-LIST-OBJECTS GLOBAL=OVERVIEW');
COMMAND ('ADD-LIST-OBJECTS TASK=(C''UCON'')');
COMMAND ('PRINT-LIST');

Calling private procedures

A PRODAMP object stored in the selected object library can be started directly by means of the DAMP statement:

START-PRODAMP-PROGRAME procname, PAR=(par1, par2, ...)

In this case, it is not necessary to know where the source module is stored or to assign a PRODAMP window. “procname” is the element name of the object module to be executed. The element with the highest existing version number is always executed. The optional parameters may be specified numerically, as decimal or hexadecimal numbers, or as strings enclosed within single quotes. The parameter types and the order in which they are specified must match the specifications in the parameter area defined within the procedure.

Example

ARRANGE
.P1 : RELATIVE=0,LENGTH=4,TYPE=NUMERIC;
.P2 : RELATIVE=4,LENGTH=1,TYPE=STRING;
.P3 : RELATIVE=5,LENGTH=4,TYPE=NUMERIC;
.P4 : RELATIVE=9,LENGTH=9,TYPE=STRING;
END ARRANGE;
N := PARAMETER.P1;
IF 'X' = PARAMETER.P2 THEN
....
END IF;

A procedure which uses the above parameters must therefore be called via a statement like this:

START-PRODAMP-PROGRAM procnam, PAR = (1234,'Z ',X 'AEFF','ABCDEFGHI')

This assigns the value 1234 to parameter P1, the letter “Z” to parameter P2, the hexadecimal number X'AEFF' to P3, and the string 'ABCDEFGHI' to parameter P4.

The parameters must be specified consecutively in the ARRANGE statement and must not be aligned. Each numeric parameter (decimal or hexadecimal) specified in the START-PRODAMP-PROGRAM statement is placed right-justified in a 4-byte field.

Numeric values can also be interpreted as bit patterns or as hexadecimal strings within the procedure.

Execution of a DAMP statement causes the entire input string to be converted into uppercase letters. This also applies to the parameters.

Interrupting private procedures

The INTERRUPT (see "Statements") and RETURN (see "Statements") statements can be used to interrupt execution of a procedure.

For both statements it is possible to specify a window which appears in the DAMP screen mask whenever there is an interrupt. If no window is specified, the current window appears.

RESUME-PRODAMP-PROGRAM resumes execution of the interrupted procedure at the place where it was interrupted. If no procedure was active, the procedure loaded in the PRODAMP window is started from the beginning.

Detecting and recovering execution errors

If the PRODAMP interpreter detects an error during procedure execution, it aborts the PRODAMP procedure and outputs two error messages in the message lines of the DAMP screen. The first message contains the name of the aborted PRODAMP procedure and the number of the procedure line in which the error occurred. The second message describes the error. 

Pressing the key and entering the statement INFORM-PROGRAM MSG='*CANCEL' can be used to provoke a runtime error. This makes it possible, for example, to terminate an endless loop and output a message indicating the name of the procedure and the number of the error line.

PRODAMP supports two facilities for error diagnosis: tracing (see "Statements") and variable monitoring (see "Statements").

Archiving private procedures

PRODAMP source and object modules can be stored in PLAM libraries as members of type S or C and loaded from these libraries when needed. Modules addressed using the ENTER_MODULE procedure are expected to be of the element type R.
Unless otherwise specified, the same library is used for all types. This library has the name SYS.USRDMP.DAMP.<ver>.
Element types C and R must be contained in the same library.

Other libraries can be specified by means of the DAMP statement ASSIGN-PRODAMP-LIBRARIES:

ASSIGN-PRODAMP-LIBRARIES [SOURCE=source-lib] [,OBJECT=object-lib]
or
ASSIGN-PRODAMP-LIBRARIES SOURCE=liname, OBJECT=*SOURCE

The specified libraries are then assigned for the desired types (if OBJECT=*SOURCE is specified, the library is assigned for all types). To switch back to the standard library, you may specify *STD instead of SYS.USRDMP.DAMP.<ver>. This switches to the library set in the user options (see “Setting user options”). SHOW-PRODAMP-LIBRARIES causes the current PRODAMP library assignments to be displayed.

PRODAMP source modules are saved and loaded exclusively via the PRODAMP window, namely by entering the appropriate code in the “Mode” field of the header line (see "Working with procedures (special window: PROC)").

Mode=Wrt	(Write); the current source module is written either to the library selected by means of ASSIGN-PRODAMP-LIBRARIES or to the default library.
Mode=Rea	(Read); an element from the currently selected source module library is read.
Mode=Upd Mode=Inf	(Update); the specified element is overwritten. (Inform); a list of the existing source members in the currently selected library is displayed.

PRODAMP object modules can be created by way of the PRODAMP window, but they can be loaded (and simultaneously started) only via the START-PRODAMP-PROGRAM statement.

The code “Sav” is used in the “Mode” field of the PRODAMP window in order to save an object module (after successful compilation):

Mode=Sav

(Save); a PRODAMP object module is saved in the selected object library.

Examples

The following examples are concrete applications of the diagnostic language. Each example illustrates a particular aspect of the language.

Example 1: HEX calculator

This very simple example implements a hexadecimal calculator with the aid of PRODAMP. A MODIFY-SCREEN-LAYOUT statement should be entered beforehand to ensure that the first line of the PRODAMP window is visible on the screen. Modifying the expression and entering the option “Go” in the header line causes the “result” to be displayed in both hexadecimal and decimal form in line 2 of the DAMP screen.
The object being diagnosed is not accessed in this example.

A := X'14' + X'3B' * 24 ; "ENTER THE DESIRED CALCULATION HERE
MESSAGE ('RESULT HEX: '+HEX_STRING(A)+', DEC: '+DEC_STRING(A) );

Example 2: Searching the TFT chain of the current task

The following procedure searches through the TFT chain of the current task. Each TFT is output in window 4 in the format of the TFT DSECT. The user can then page forward to the next TFT with the aid of RESUME, or other DAMP statements can be issued.

IF CURRENT.TID = 0 THEN
  MESSAGE ( 'No TID/TSN given' );
  RETURN;
  END IF;
TFT := .ETCBTFT; ——————————————————————————————————————————————————————  (1) 
IF TFT = 0 THEN
  MESSAGE ( 'No TFT found' );
  RETURN;
  END IF;
RET_WND := CURRENT.WNDNO; —————————————————————————————————————————————  (2) 
ARRANGE
  WINDOW: NUMBER=4,DSECT='IDMTFT',NAME='IDMFRLNK'; ————————————————————  (3) 
END ARRANGE;
WHILE TFT <> 0 DO
  ARRANGE
  WINDOW: NUMBER =4,ADDRESS = TFT; ————————————————————————————————————  (4) 
END ARRANGE;
  INTERRUPT; ——————————————————————————————————————————————————————————  (5) 
TFT := TFT.IDMFRLNK;
  END WHILE;
RETURN WINDOW = RET_WND; ——————————————————————————————————————————————  (6) 

(1)	The anchor of the TFT chain is in ETCBTFT. Since DAMP can localize the TFT automatically, it is not necessary to specify a base address. The task specified by TID or TSN in the PRODAMP window is taken.
(2)	The number of the current window (usually the PRODAMP window) is saved so that it can be displayed again later as the topmost window.
(3)	The settings for window 4 which do not change during execution are declared outside the loop. The NAME is specified because the TFT DSECT begins with an EQU * statement, which would cause the first field to be split.
(4)	Only the address for the window is redefined within the loop. All other settings (including the number) are fixed in the first ARRANGE statement and remain unchanged. Interrogation of CURRENT.ERROR was omitted in this example because an unallocated memory area will automatically result in output of the error message “Requested memory area not accessible”. By default, the current task is displayed (i.e. the task set in the PRODAMP window). It is possible to specify the additional information TID=CURRENT.TID, but this is redundant.
(5)	INTERRUPT interrupts the procedure and displays the current window on the screen. Due to the ARRANGE statement, window 4 is the topmost window in this display. The user can resume procedure execution by issuing a RESUME statement, causing the next TFT to be displayed.
(6)	After output of the last TFT, control is returned to the window which was saved at the beginning of the procedure.

Example 3: Changing the current task

This example shows how you can avoid scrolling “endlessly” in the status window to find a task with a specific characteristic when analyzing a SLED file. It illustrates how to use PRODAMP to search for tasks which have generated a system dump and to make each of these tasks (one at a time) the current task. In other words, after execution of the procedure, the DAMP status window (window 2) is positioned such that the PCB chain of the selected task is displayed.

TASK := 0;
WHILE CURRENT.ERROR = 0 DO ————————————————————————————————————————————  (1) 
NEW_TASK ( TASK );
  IF CURRENT.ERROR=0 THEN
    IF .ETCBCDSY <> 0 THEN ————————————————————————————————————————————  (2) 
      ARRANGE WINDOW: NUMBER = 2,TID=TASK; END ARRANGE; ———————————————  (3) 
      INTERRUPT ;
    END IF;
  END IF;
TASK := TASK + 1; —————————————————————————————————————————————————————  (4) 
END WHILE;

(1)	Since the NEW_TASK procedure sets CURRENT.ERROR when no more tasks can be found, this is the criterion for terminating the loop for all active tasks.
(2)	The ETCBCDSY field contains the number of system dump requests for the task. This field is a TCB field and can thus be localized automatically by DAMP. To this end, DAMP uses the TCB of the current task, which is set correctly by NEW_TASK.
(3)	An ARRANGE statement for window 2 with an ITN specification positions the window to the entry point for this task.
(4)	For the scan, the TID must be incremented by 1. NEW_TASK then returns the next active task.

Example 4: Outputting memory areas to SYSLST

This example shows how the standard procedures DUMP_MEMORY and SET_HEADER can be used to output any desired memory areas to SYSLST. 

TFT@ := .ETCBTFT;
WHILE TFT@ <> 0 DO
  P2FCB@ := TFT@.IDMP2FL;
  IF P2FCB@ <> 0 THEN
    SET_HEADER ( '*** P2-FCB FOR FILE '+TFT@.IDMFILE+' ****', 2, 10);
    DUMP_MEMORY ( P2FCB@, 0, LENGTH( 'ID2FCB','DS' ) );
  END IF;
  TFT@ := TFT@.IDMFRLNK;
END WHILE;

This procedure lists the P2-FCB of each open file.