A PRODAMP procedure consists of a number of statements. Each statement is terminated by a semicolon. Since there are no declarations in PRODAMP, each statement generates code which can be interpreted only when the procedure is executed.
PRODAMP incorporates the following statements:
Statement name | Function |
ARRANGE | Define symbol attributes |
Table 12: Overview of PRODAMP statements
ARRANGE
Define symbol attributes
The ARRANGE statement can be used to declare the names, lengths, relative addresses and types of symbols.
ARRANGE WINDOW can be used to specify that a particular dump window is to be displayed as the top window on screen. In addition, it is possible to specify that values from the PRODAMP procedure are to be entered in the input fields in the window. The keywords and their assignments are given in figure 66.
Figure 66: Header line of a dump window.
ARRANGE WINDOW
ARRANGE WINDOW moves the specified window to the top of the window chain in DAMP. After several ARRANGE WINDOW statements for different windows, followed by the screen display in each case, the last window which was defined thus appears as the topmost window on the screen. The other windows are displayed in the reverse order, provided there is enough space to accommodate their defined sizes.
ARRANGE WINDOW specifications are not permitted for the help window (W1), PROC window(s) and other special windows and are rejected. The parameters TID, TSN and LENGTH may be declared for the status window (W2) and the stack window (W3); for W3, also the PCB with which a PCB can be selected from the PCB chain of the task via its sequence number.
ARRANGE WINDOW acts just like an input in the header line of a diagnostic window. Each possible input in the header has a corresponding keyword in the ARRANGE statement. The only exception to this is the parameter NUMBER, via which the desired window number is specified.
ARRANGE
Data structures which are not stored in a symbol file can be made available on the fly by means of the ARRANGE statement. ARRANGE is also always necessary when unstructured dump data is to be addressed (see "Example 5 for ARRANGE").
The symbols (re)defined via ARRANGE are available only within the PRODAMP procedure: they are not placed in the binary symbol tree of DAMP. This means that these changes have no effect when a window is overlaid with a DSECT.
New symbols must be defined completely, i.e. LENGTH, TYPE and RELATIVE must be specified explicitly. Otherwise, PRODAMP attempts to fill out the missing specifications with information from the symbol file; if the symbol cannot be found, PRODAMP aborts execution of the procedure.
Conversely, existing characteristics can be reset explicitly by specifying the keyword UNDEFINED for them. The next time this symbol is accessed, the missing characteristic is then filled out with information from the symbol file.
Example 1 for ARRANGE WINDOW
ARRANGE WINDOW: NUMBER=5, ADDRESS=0, LENGTH=8, TID=X'ABC', OUTPUT='ASS' ; END ARRANGE ;
Window 5 is to display the user memory of task ABC, starting at address 0. The output is to be disassembled (OUTPUT='ASS'). Furthermore, the size of the window is to be 8 lines.
Example 2 for ARRANGE WINDOW
ARRANGE WINDOW: NUMBER=7, NAME='IDMFILE', DSECT = 'IDMTFT', OUTPUT='CBM', ADDRESS=TFT_AD; END ARRANGE ;
Window 7 is to display a memory area starting at address TFT_AD. The area is to be edited symbolically in the format of DSECT IDMTFT. The DSECT is positioned such that the DSECT IDMFILE is at the base address TFT_AD and the field IDMFILE is in the first line of the window. The window start address is TFT_AD + offset(IDMFILE).
Example 3 for ARRANGE
ARRANGE .ESTK#ICL : TYPE = STRING ; END ARRANGE ; IF 'P' = STK1.ESTK#ICL THEN ...
The field ESTK#ICL in DSECT ESTK is redefined. It is defined as DS XL1, which means that it is interpreted as a bit pattern, but it contains a letter. Assignment of the type STRING makes it possible to interpret this field as a letter in subsequent statements.
Example 4 for ARRANGE
ARRANGE .STDHD : RELATIVE = 0, LENGTH = 8, TYPE = STRING ; .PAR_1 : RELATIVE = 8, LENGTH = 4, TYPE = NUMERIC ; .PAR_2 : RELATIVE =12, LENGTH = 1, TYPE = STRING ; .PAR_3 : RELATIVE =13, LENGTH = 1, TYPE = PATTERN; END ARRANGE ; P_LATTE := .... ; FRST_PAR := P_LATTE.PAR_1 ; ....
Within PRODAMP, a DSECT is constructed, e.g. for a newly developed interface whose parameter list has not yet been passed officially. The fields of the parameter list can now be addressed symbolically using the newly defined names; the related base address must, of course, be specified as well. A similar method is used to pass parameters between PRODAMP procedures.
Example 5 for ARRANGE
ARRANGE .BYTE : TYPE=NUMERIC,LENGTH=1,RELATIVE=0; END ARRANGE; INT_AD := STK.ESTK#ICR; "Address of the paging error" OPCODE := INT_AD.BYTE; "Machine instruction at this point" IF OPCODE = X'D2' THEN ......
ARRANGE can be used to address unstructured data of the diagnosis object (such as coding, for example).
Example 6 for ARRANGE
ARRANGE .HALFWORD: OFFSET = 0, LENGTH = 2, TYPE = NUMERIC; END ARRANGE WORD := PTR.HALFWORD
If a field is defined as NUMERIC with LENGTH=2, then special care must be taken to ensure that the sign is taken into account when the contents of the file are assigned to a variable.
If HALFWORD contains, for instance, the sequence of characters C'AB' at the address indicated by PTR, this does not correspond to the numeric value X'C1C2' = 49602 after the field has been defined. Instead, it corresponds to the value X'FFFFC1C2' = -15943, which is the value subsequently assigned to the variable WORD. If the sign for the contents is to be ignored, the field must be defined with TYPE=PATTERN. The general rule for TYPE=NUMERIC is that the sign is taken into account if the length is an even value and the value transferred is always positive if the length is an odd value.
Example 7 for ARRANGE
ARRANGE
.WAIT_FACTOR: LENGTH = 1, TYPE = STRING,
REFERENCE = .NKLCB_MDL.COPY_PARAMETER.USER_ALLOCATION
END ARRANGE;
The elements of a substructure can also be redefined using ARRANGE. To do this, you must use the name REFERENCE in order to localize the symbol within a reference chain.
FOLLOW
Monitor variable
The FOLLOW statement is used to monitor variables. This is possible only if the variable has already been declared, i.e. initialized.
Following execution of the FOLLOW statement, all assignments to the specified variable are logged in an EDT area (by default, area 8). The output includes the number of the line in which the variable is assigned, the name of the variable, and its value after assignment.
In addition, every change to the CURRENT.ERROR value is logged.
If the EDT area is changed during procedure execution by means of @WRITE (“@PROC XX”), the output for variable monitoring is likewise directed to the new EDT area.
FOLLOW is very useful for searching for errors in PRODAMP procedures.
Variable monitoring can be activated but not deactivated, i.e. it is not terminated until the end of the procedure or until leaving the procedure by means of RETURN.
Example for FOLLOW
The procedure
1) S := ' '*8; 2) STR := '12XY34'; 3) NUM := ' '; 4) I := 0; 5) A := 0; FOLLOW A; 6) WHILE I <= 5 DO 7) EXTRACT ( NUM,STR,I ); 8) INSERT ( NUM,S,3 ); 9) A := DEC_BINARY ( S ); 10) I := I + 1; 11) END WHILE;
generates the following log:
TEST (0) %STMT 9: 'A' <- 1 ( X'00000001' ) TEST (0) %STMT 9: 'A' <- 2 ( X'00000002' ) TEST (0) %STMT 9: 'A' <- 1 ( X'00000001' ) TEST (0) %STMT 10: 'CURRENT.ERROR' <- 4 TEST (0) %STMT 9: 'A' <- 1 ( X'00000001' ) TEST (0) %STMT 9: 'A' <- 3 ( X'00000003' ) TEST (0) %STMT 10: 'CURRENT.ERROR' <- 0 TEST (0) %STMT 9: 'A' <- 4 ( X'00000004' )
Output of the change to the CURRENT.ERROR value caused by a standard procedure comes after the statement that caused it. The example also shows that DEC_BINARY returns an undefined value if the string is not a decimal number.
IF
Issue conditional statements
The IF statement can be used to make the execution of other statements contingent on specified conditions. The condition to be fulfilled is defined by combining several expressions with the aid of logical operators (see "Operators").
Example 1 for IF
IF PCB.ESTKGR15 <> 0 THEN RC := PCB.ESTKGR15 MOD 256 ; MESSAGE ( 'Returncode '+HEX_STRING(RC)+' for $REQM.' ); END IF;
If the contents of field ESTKGR15 are not equal to zero, i.e. if register 15 contains a return code, the message given after it is displayed on the screen.
Example 2 for IF
IF 'TSOS ' = .EJTPUSR THEN
IF 'HELGA' + ' '*49 = .EJTPXPRG THEN
DANGER := 100 ;
END IF ;
ELSIF 'SERVICE ' = .EJTPUSR THEN
DANGER := 180 ;
ELSE
DANGER := 0 ;
END IF;
The user and the program used are queried in fields EJTPUSR and EJTPXPRG. The results determine what value is set for the DANGER variable.
Example 3 for IF
EVIPLFLG := B'00000100' ; 'SYSTEM LOADING COMPLETED' EVCL2REQ := P'02' ; 'CLASS 2 MEMORY REQUESTED' IF EVIPLFLG + EVCL2REQ IN .EVSVMIND THEN
Two fields are defined. A check is made as to whether the contents of these fields can be found in the EVSVMIND field.
Example 3 is interesting for another reason: it deals with concrete equates from the DSECT SVMT. Since DAMP does not store the equates in the
symbol file, the corresponding bit patterns have to be defined in PRODAMP.
INTERRUPT
Interrupt procedure
The INTERRUPT statement enables the use to interrupt a procedure and branch to the DAMP program, where it is then possible to enter any DAMP statements. Control is returned to the procedure by means of the RESUME-PRODAMP-PROGRAM statement.
INTERRUPT is useful, for example, when a chain of data structures has to be examined sequentially. For instance, if the INTERRUPT statement is contained in a loop that localizes the data structures one after the other and assigns them to a screen window, the user can, with the added aid of the RESUME-PRODAMP-PROGRAM statement, as it were hop from one link of the chain to the next.
Example for INTERRUPT
INTERRUPT WINDOW=4
The parameter WINDOW= causes the entire DAMP screen to be refreshed. If several outputs are sent one after the other to the same window by means of INTERRUPT, this can often be somewhat irritating. The refresh operation can be avoided by using INTERRUPT without an explicit window specification; in this case, only the modified fields on the screen are rewritten.
RETURN
Leave procedure prematurely
Issuing the RETURN statement in a PRODAMP procedure returns control to the point where the procedure was called. This may be either another procedure or the DAMP dialog.
RETURN is also generated implicitly by the compiler at the end of each procedure.
RETURN WINDOW
Terminate procedure prematurely
In contrast to a simple RETURN, the statement RETURN WINDOW=<window-number> not only exits the current procedure, but aborts the entire call hierarchy. In addition, <window-number> specifies the number of the diagnosis window that is to be displayed in the dialog at the topmost position on the DAMP screen after aborting the procedure.
Example for RETURN
RETURN WINDOW = CURRENT.WNDNO;
This statement fully exits the procedure and sets the diagnosis window to the one specified in the CURRENT.WNDNO field.
TRACE
Control tracing
The statements TRACE ON and TRACE OFF activate and deactivate tracing. All source line numbers encountered between TRACE ON and TRACE OFF are logged in an EDT area (unless otherwise specified, area 8). Both statements can be entered anywhere within a procedure.
If, in the course of procedure execution, the EDT procedure area is changed by means of WRITE (“@PROC XX), the trace is also output to the new area.
Activation and deactivation of the trace are contingent upon the dynamic statement sequence.
TRACE is extremely useful for searching for errors in PRODAMP procedures.
Example for TRACE
Execution of the procedure PROCNAME:
1) IF CURRENT.LEVEL < 4 THEN 2) TRACE ON; 3) I := 1234; 4) PROCNAME; 5) I := 5678; 6) END IF;
causes the following line numbers to be logged:
PROCNAME (0) %STMT 3 PROCNAME (0) %STMT 4 PROCNAME (1) %STMT 3 PROCNAME (1) %STMT 4 PROCNAME (2) %STMT 3 PROCNAME (2) %STMT 4 PROCNAME (3) %STMT 3 PROCNAME (3) %STMT 4 PROCNAME (3) %STMT 5 PROCNAME (3) %STMT 6 PROCNAME (3) %STMT 7 PROCNAME (2) %STMT 5 PROCNAME (2) %STMT 6 PROCNAME (2) %STMT 7 PROCNAME (1) %STMT 5 PROCNAME (1) %STMT 6 PROCNAME (1) %STMT 7 PROCNAME (0) %STMT 5 PROCNAME (0) %STMT 6 PROCNAME (0) %STMT 7
The procedure name is output first, followed by the value of CURRENT.LEVEL in parentheses, to enable the subprogram levels of the procedure to be distinguished. Then the line number of the processed statement is output. At the end of a procedure PRODAMP always implicitly generates a RETURN statement.
As a result, the log will contain STMT 7, which is not contained in the above procedure.
If tracing is activated, any further TRACE ON statements will be ignored. The first TRACE OFF statement deactivates tracing.
WHILE
Form program loops
The WHILE statement can be used to form loops.
Example for WHILE
WHILE ADDR <= MAX DO
IF ADDR.TABVAL = BAD_VAL THEN
RETURN ;
END IF ;
ADDR := ADDR + TAB_LEN ;
END WHILE ;
As long as the variable ADDR does not become greater than the variable MAX, the subsequent statement sequence will be processed repeatedly.
Assignment
The simplest form of statement is the assignment. The assignment operator is the character combination “:=”. This operator must be preceded by the name of a variable and followed by an expression, i.e. the name of a variable, a symbol, a literal, a function call or an arithmetic expression.
The data type of a variable is defined by the first static assignment (i.e. in the sequence of the source) to this variable, as shown in table 9 (Data types). The data type on the right is determined and transferred, taking into consideration any existing type assignments. If the data type on the right is undefined, it is set to numeric. A data type is undefined if, for example, the first operand is a symbol; all symbols, including those defined with the PRODAMP statement ARRANGE, have the value “undefined” during compilation.
Examples
A_FCB := X'ABC'; FNAM := A_FCB.ID1FILE; TEXT := 'The specified FCB does not exist.'; XY := FALSE;
In the above examples (assuming that these are statically the first assignments to the variables concerned), A_FCB will therefore be defined as numeric, TEXT as a string with a length of 33, and XY as a bit pattern.
Since the type for the symbol ID1FILE cannot be determined at compilation time, FNAM receives the default type “numeric”. (Otherwise, the symbol file which is to be used later for procedure execution would have to be assigned during compilation, even if the procedure is intended for use with a completely different version of BS2000.) For this reason, it is best to declare variables by assigning them an initial value in cases where (possibly nonnumeric) data from the diagnosis object is to be assigned to them later with the aid of a symbol.
Examples
A_FCB := X'ABC' ; FNAM := ' ' * 54 ; FNAM := A_FCB.ID1FILE ;
The right side of an assignment may also consist of function calls (for standard functions) and expressions.
If a string is assigned to a string of another length that has already been initialized, the source string is truncated in the case of a shorter target string, or padded with blanks in the case of a longer target string.