OpenVMS Debugger Manual

You cannot use the DEPOSIT command with entry or label variables or formats, or with entire arrays or structures. You cannot use the EXAMINE command with entry or label variables or formats; instead, use the EVALUATE/ADDRESS command.

You cannot use the EXAMINE command to determine the values or attributes of global literals (such as GLOBALDEF VALUE literals) because they are static expressions. Instead, use the EVALUATE command.

You cannot use the EXAMINE, EVALUATE, and DEPOSIT commands with compile-time variables and procedures. However, you can use EVALUATE and DEPOSIT (but not EXAMINE) with a compile-time constant, as long as the constant is the source and not the destination.

Note that an uninitialized automatic variable does not have valid contents until after a value has been assigned to it. If you examine it before that point, the value displayed is unpredictable.

You can deposit a value into a pointer variable either by depositing another pointer's value into it, thus making symbolic reference to both pointers, or by depositing a virtual address into it. (You can find out the virtual address of a variable by using the EVALUATE/ADDRESS command, and then deposit that address into the pointer.) When you examine a pointer, the debugger displays its value in the form of the virtual address of the variable that the pointer points to.

The debugger treats all numeric constants of the form n or n.n in PL/I language expressions as packed decimal constants, not integer or floating-point constants, in order to conform to PL/I language rules. The internal representation of 10 is therefore 0C01 hexadecimal, not 0A hexadecimal.

You can enter floating-point constants using the syntax nEn or n.nEn.

There is no PL/I syntax for entering constants whose internal representation is Longword Integer. This limitation is not normally significant when debugging, since the debugger supports the PL/I type conversion rules. However, it is possible to enter integer constants by using the debugger's %HEX, %OCT, and %BIN operators, because nondecimal radix constants are assumed to be FIXED BINARY. For example, the EVALUATE/HEXADECIMAL 53 + %HEX 0 command displays 00000035.

C.14 RPG II (VAX Only)

The follow subtopics describe debugger support for RPG II.

C.14.1 Operators in Language Expressions

The following operators are supported in language expressions when the language is set to RPG II:

Kind	Symbol	Function
Prefix	+	Unary plus
Prefix	--	Unary minus (negation)
Infix	+	Addition
Infix	--	Subtraction
Infix	*	Multiplication
Infix	/	Division
Infix	=	Equal to
Infix	NOT =	Not equal to
Infix	>	Greater than
Infix	NOT <	Greater than or equal to
Infix	<	Less than
Infix	NOT >	Less than or equal to
Prefix	NOT	Logical NOT
Infix	AND	Logical AND
Infix	OR	Logical OR

C.14.2 Constructs in Language and Address Expressions

Supported constructs in language and address expressions for RPG II follow:

Symbol	Construct
( )	Subscripting

C.14.3 Data Types

Supported RPG II data types follow:

RPG II Data Type	Operating System Data Type Name
Longword binary numeric	Longword Integer (L)
Word binary numeric	Word Integer (W)
Packed decimal	Packed Decimal (P)
Character	ASCII Text (T)
Overpunched decimal	Right Overpunched Sign (NRO)
Arrays	(None)
Tables	(None)

C.14.4 Setting Breakpoints or Tracepoints

With RPG II programs, you can set breakpoints using source line numbers, logic cycle labels, user-defined tag names, and subroutine labels. Debugging RPG II programs is somewhat different from debugging programs in other languages, and the additional topics explain where and how you can set breakpoints or tracepoints.

C.14.4.1 Specifications

The following paragraphs describe where you can set breakpoints (or tracepoints) in specifications, using line numbers.

The RPG II program cycle determines the order in which program lines are processed. When setting breakpoints or tracepoints, you can reference the line numbers that RPG II assigns to your program and appear in a listing file or in a debugger source display. The line numbers you specify in columns 1 through 5 of a specification are not used.

The compiler assigns line numbers only to certain specifications at specific points in the logic cycle; therefore, you can specify a breakpoint or tracepoint at these points in the program:

• A breakpoint at a File Description specification occurs before an input or update file is opened or just before an output file is created. The line number of this breakpoint corresponds to the File Description specification for this file.
• A breakpoint at an Input specification occurs before the fields are loaded with data from a record. The line number of this breakpoint corresponds to the record definition in an Input specification.
• You can set two breakpoints for each Calculation specification. The first breakpoint occurs just after testing control-level indicators, if used, and just before testing conditioning indicators. The second breakpoint occurs just before executing the operation code. Use the following syntax:

  SET BREAK line-number.statement-number
  

  
  For example, assume that a Calculation specification begins with line number 25. The SET BREAK 25.1 command enables you to test indicators. The SET BREAK 25.2 command puts a breakpoint just before the operation code is executed. If a Calculation specification has no conditioning indicators, the SET BREAK 25 command puts a breakpoint just before the operation code is executed.
  You can specify statement numbers only with Calculation specifications that have conditioning indicators.
• A breakpoint at an Output specification occurs after the output buffer has been built but before the record is output. The line number of the breakpoint corresponds to the record definition in an Output specification.

You can specify an RPG II label as a breakpoint or a tracepoint. The following RPG II labels, which correspond to specific points in the logic cycle, are provided in addition to user-defined tags. Note that these labels do not appear in the source code but are accessible from the debugger. The labels do appear in the machine code listing.

RPG II Label	Description and Breakpoint Behavior
*DETL	Breaks just before outputting heading and detail lines
*GETIN	Breaks just before reading the next record from the primary or secondary file
*TOTC	Breaks just before performing total-time calculations
*TOTL	Breaks just before performing total-time output
*OFL	Breaks just before performing overflow output
*DETC	Breaks just before performing detail-time calculations

For example:

DBG> SET BREAK *TOTL

The EXAMINE command enables you to look at the contents of a variable, the current table entry, an array element, or the I/O buffer.

• To examine an array variable, use array syntax as in the following example:

  DBG> EXAMINE ARR3(9)    ! Display element 9 of array ARR3
  DBG> EXAMINE ARRY(1:7)  ! Display elements 1-7 of array ARRY
  

• Specifying a table name enables you to examine the entry retrieved from the last LOOKUP operation.
• To display the contents of the I/O buffer, specify the name of the input file, update file, or output file, followed by the string $BUF. For example, the following command displays the contents of the I/O buffer for the input file INPUT:

  DBG> EXAMINE INPUT$BUF
  

• The following command displays the ASCII equivalent of the string STRING, which is 6 characters long:

  DBG> EXAMINE/ASCII:6 STRING
  

• To examine a variable which contains the at sign (@), use %NAME as follows:

  DBG> EXAMINE %NAME 'ITEM@'
  

• To examine a nonexternal indicator, precede it with the string *IN. For example:

  DBG> EXAMINE *IN56
  *IN56:  "0"
  

  
  If an indicator is set off, 0 is displayed. If an indicator is set on, 1 is displayed.
  You cannot examine external indicators in this manner. To examine external indicators, you must first link the program with the /NOSYSSHR qualifier; then, use the CALL command, as in the following example which displays the value of U5:

  DBG> CALL RPG$EXT_INDS(5)
  value returned is 0
  

Note the following points when using the DEPOSIT command:

• You can deposit a single value into an element of an array using array syntax as in the following example, which deposits the value 150 into element 2 of array ARR:

  DBG> DEPOSIT ARR(2) = 150
  

• You can deposit multiple values into an array of character strings, by using the /ASCII qualifier with the DEPOSIT command. For example, assume PARTS is an array of 10 elements in program INV.RPG, each a character string of length 3. The following DEPOSIT command deposits the strings P04, P05, and P06 into elements 4, 5, and 6, respectively, of array PARTS:

  DBG> DEPOSIT/ASCII PARTS(4) = "P04P05P06"
  DBG> EXAMINE PARTS(4:6)
  INV\PARTS 
      (4):     'P04' 
      (5):     'P05' 
      (6):     'P06'
  

• Values deposited into numeric fields are aligned on the decimal point. Shorter fields are padded with zeros to the left and right of the decimal point.
• Values deposited into character fields are left justified. If the value contains fewer characters than the character field, the field is padded on the right with spaces.
• To set a nonexternal indicator on or off with the DEPOSIT command, precede the indicator with the string *IN. Depositing the value 1 or 0 sets the indicator on or off, respectively. For example, the following command sets indicator 56 on:

  DBG> DEPOSIT *IN56 = "1"
  

The EDIT command invokes the RPG II editor rather than the DEC Language-Sensitive Editor.

C.15 SCAN (VAX Only)

The following subtopics describe debugger support for SCAN.

C.15.1 Operators in Language Expressions

Supported SCAN operators in language expressions follow:

Kind	Symbol	Function
Prefix	+	Unary plus
Prefix	--	Unary minus (negation)
Infix	+	Addition
Infix	--	Subtraction
Infix	*	Multiplication
Infix	/	Division
Infix	&	Concatenation
Infix	=	Equal to
Infix	<>	Not equal to
Infix	>	Greater than
Infix	>=	Greater than or equal to
Infix	<	Less than
Infix	<=	Less than or equal to
Prefix	NOT	Complement
Infix	AND	Intersection
Infix	OR	Union
Infix	XOR	Exclusive OR

C.15.2 Constructs in Language and Address Expressions

Supported constructs in language and address expressions for SCAN follow:

Symbol	Construct
( )	Subscripting
. (period)	Record component selection
->	Pointer dereferencing

C.15.3 Predefined Symbols

Supported SCAN predefined symbols follow:

Symbol	Meaning
TRUE	Boolean True
FALSE	Boolean False
NIL	Nil pointer

C.15.4 Data Types

Supported SCAN data types follow:

SCAN Data Type	Operating System Data Type Name
BOOLEAN	(None)
INTEGER	Longword Integer (L)
POINTER	(None)
FIXED STRING ( n)	TEXT with CLASS=S
VARYING STRING ( n)	TEXT with CLASS=VS
DYNAMIC STRING	TEXT with CLASS=D
TREE	(None)
TREEPTR	(None)
RECORD	(None)
OVERLAY	(None)

There is no specific support for the following data types:

• FILE
• TOKEN
• GROUP
• SET

You can use the names of the following SCAN constructs in debugger commands:

• procedures
• macros
• constants
• variables
• labels

Note the following points about SCAN breakpoints, tracepoints, and watchpoints.

C.15.6.1 Breakpoints and Tracepoints

You can set breakpoints and tracepoints on procedures, trigger macros, syntax macros, and labels, as well as line numbers. For example:

DBG> SET BREAK find_keyword    ! break on a trigger macro
DBG> CANCEL BREAK exit         ! cancel break on label
DBG> SET BREAK compare_trees   ! break on a procedure

Conventional breakpoints and tracepoints are not especially convenient for monitoring SCAN's picture matching. Where do you set a breakpoint or tracepoint to observe the tokens built by your program? There is no statement in your program on which to set such a breakpoint.

To solve this problem, VAX SCAN defines several events. By setting breakpoints or tracepoints on these events, you can observe the picture matching process.

The following event keywords are defined for SCAN programs:

Event Keyword	Description
TOKEN	A token is built.
PICTURE	An operand in a picture is being matched.
INPUT	A new line of the input stream is read.
OUTPUT	A new line of the output stream is written.
TRIGGER	A trigger macro is starting or terminating.
SYNTAX	A syntax macro is starting or terminating.
ERROR	Picture matching error recovery is starting or terminating.

Use these keywords with the /EVENT qualifier of the following commands:

• (SET,CANCEL,ACTIVATE,DEACTIVATE) BREAK
• (SET,CANCEL,ACTIVATE,DEACTIVATE) TRACE

For example, the following command sets a breakpoint that triggers whenever a TOKEN is built:

DBG> SET BREAK/EVENT=TOKEN

Recognition of SCAN events is enabled automatically by the debugger if the main program is written in SCAN. If you are debugging a program written in another language that calls a SCAN routine, proceed as follows to set up the SCAN environment:

1. Enter the SET LANGUAGE SCAN command to enable recognition of language-dependent operators, expressions, and other constructs (see the SET LANGUAGE command).
2. Enter the SET EVENT_FACILITY SCAN command to enable recognition of SCAN events (see the SET EVENT_FACILITY command). The SHOW EVENT_FACILITY command identifies the current facility and its events.

Note the following points about SCAN watchpoints:

• Variables declared at MODULE level are static by default.
• Variables declared at PROCEDURE or MACRO level are automatic (nonstatic) by default.
• DYNAMIC STRING variables are dynamically built. The storage used to hold the value of the string can change when the value of the string changes. Thus, the storage the debugger is watching may not be the correct storage if the string's value is changed.

The following subtopics explain how to examine and deposit into the following SCAN variables:

• STRING
• FILL
• POINTER
• TREE
• TREEPTR
• RECORD
• OVERLAY

If you deposit into a FIXED STRING variable, truncation will occur if the deposited string is longer than the size established by the declaration of that variable.

If you deposit into a VARYING STRING variable, truncation will occur if the deposited string is longer than the maximum size established by the declaration of that variable.

If you deposit into a DYNAMIC STRING variable, truncation will occur if the deposited string is longer than the current size of the variable.

With FIXED and DYNAMIC STRING variables, if the deposited string is shorter than the current size of the variable, the unfilled portion of the variable will be blank padded to the right, with the new string left justified in the variable.

In the case of VARYING STRING variables, the current size of the variable storage space will be adjusted to the size of the deposited string.

C.15.7.2 FILL Variables

Examining a FILL variable causes the contents of the specified variable to be displayed as a string, by default, and so may have little meaning. If the characteristics (or type) of the fill are known, the appropriate qualifier applied to the command will produce a more meaningful display. The following command example shows a fill x that is known to be a single floating number:

DBG> EXAMINE/FLOAT x

You can examine a POINTER by name to find the address of the variable it points to. Use the operator that combines the minus sign and the greater than symbol (-->) to examine the variable that is based on the POINTER.

Consider these declarations and assignments:

TYPE symnode: RECORD 
                 ptr:  POINTER TO symnode, 
                 vstr: VARYING STRING( 20 ), 
              END RECORD; 
 
DECLARE x   : symnode; 
DECLARE xptr: POINTER TO symnode; 
xptr        = POINTER(x); 
x.vstr      = 'prehensile'; 

The following command displays the value of the vstr component of x:

DBG> EXAMINE x.vstr
POINTER\MAINPOINTER\X.VSTR: 'prehensile'

The following command displays the value of vstr based on the POINTER:

DBG> EXAMINE xptr->.vstr
POINTER\MAINPOINTER\XPTR->.VSTR: 'prehensile '

You can examine the contents of the nodes in a tree using the following syntax:

EXAMINE tree_variable([subscript],...)

You cannot deposit into a TREE variable.

If you specify the name of a tree with the EXAMINE command, the debugger displays the contents of all nodes and leaves of the tree. For example:

DBG> EXAMINE voters

You can specify an interior node by entering the subscript for that node. For example:

DBG> EXAMINE voters('salem')

You can examine the leaf node in a tree by specifying all subscripts leading to the desired leaf. For example:

DBG> EXAMINE voters('salem',ward2)

If you examine a TREEPTR variable, such as cityptr or wardptr, the debugger displays the address of that tree node. You examine what a TREEPTR variable is pointing to as follows:

DBG> EXAMINE cityptr->

If you specify a RECORD by name with the EXAMINE command, all components of the RECORD are presented. To examine individual components of the RECORD, specify the full name of each component.

The general format is as follows:

EXAMINE recordname

EXAMINE recordname.componentname.componentname...

You examine an OVERLAY in the same way. All components are again presented; thus, if a four-byte region is a FILL(4), an INTEGER, and a VARYING STRING(2), the four bytes will be displayed three different ways.

C.16 Language UNKNOWN

The following subtopics describe debugger support for language UNKNOWN.

C.16.1 Operators in Language Expressions

Supported operators in language expressions for language UNKNOWN follow:

Kind	Symbol	Function
Prefix	+	Unary plus
Prefix	--	Unary minus (negation)
Infix	+	Addition
Infix	--	Subtraction
Infix	*	Multiplication
Infix	/	Division
Infix	**	Exponentiation (VAX specific)
Infix	&	Concatenation
Infix	//	Concatenation
Infix	=	Equal to
Infix	<>	Not equal to
Infix	/=	Not equal to
Infix	>	Greater than
Infix	>=	Greater than or equal to
Infix	<	Less than
Infix	<=	Less than or equal to
Infix	EQL	Equal to
Infix	NEQ	Not equal to
Infix	GTR	Greater than
Infix	GEQ	Greater than or equal to
Infix	LSS	Less than
Infix	LEQ	Less than or equal to
Prefix	NOT	Logical NOT
Infix	AND	Logical AND
Infix	OR	Logical OR
Infix	XOR	Exclusive OR
Infix	EQV	Equivalence

C.16.2 Constructs in Language and Address Expressions

Supported predefined symbols for language UNKNOWN follow:

Symbol	Meaning
TRUE	Boolean True
FALSE	Boolean False
NIL	Nil pointer

C.16.4 Data Types

When the language is set to UNKNOWN, the debugger understands all data types accepted by other languages except a few very language-specific types, such as picture types and file types. In UNKNOWN language expressions, the debugger accepts most scalar OpenVMS calling standard data types.

• For language UNKNOWN, the debugger accepts the dot-notation for record component selection. For example, if C is a component of a record B which in turn is a component of a record A, then C can be referenced as A.B.C. Subscripts can be attached to any array components; for example, if B is an array, then C can be referenced as A.B[2,3].C.
• For language UNKNOWN, the debugger accepts brackets and parentheses for subscripts. For example, A[2,3] and A(2,3) are equivalent.

This appendix contains the source code for the programs used in many figures of Chapter 8, Chapter 9, and Chapter 10, EIGHTQUEENS.C AND 8QUEENS.C. These programs are presented here only to assist in understanding the procedures described in those chapters.

D.1 EIGHTQUEENS.C

Example D-1 contains EIGHTQUEENS.C, the single-module program that solves the eightqueens problem.

Example D-1 Single-Module Program EIGHTQUEENS.C

extern void setqueen(); 
extern void removequeen(); 
extern void trycol(); 
extern void print(); 
    int a[8];     /* a : array[1..8]  of boolean */ 
    int b[16];    /* b : array[2..16] of boolean */ 
    int c[15];    /* c : array[-7..7] of boolean */ 
    int x[8]; 
 
/* Solve eight-queens problem */ 
main() 
{ 
    int i; 
    for (i=0; i <=7; i++) 
 a[i] = 1; 
    for (i=0; i <=15; i++) 
 b[i] = 1; 
    for (i=0; i <=14; i++) 
 c[i] = 1; 
    trycol( 0 ); 
} /* End main */ 
 
void trycol( j ) 
    int j; 
{ 
    int m; 
    int safe; 
    m = -1; 
    while (m++ < 7) 
       { 
       safe = (a[m] ==1) && (b[m + j] == 1) && (c[m - j + 7] ==1); 
       if (safe) 
            { 
     setqueen(m, j); 
     x[j] = m + 1; 
     if (j < 7) 
  trycol(j + 1); 
     else 
  print(); 
     removequeen(m, j); 
     } 
       } 
} /* End trycol */ 
 
void setqueen(m, j) 
    int m; 
    int j; 
{ 
    a[m] = 0; 
    b[m + j] = 0; 
    c[m - j + 7] = 0; 
} /* End setqueen */ 
 
void removequeen(m, j) 
    int m; 
    int j; 
{ 
    a[m] = 1; 
    b[m + j] = 1; 
    c[m - j + 7] = 1; 
} /* End removequeen */ 
 
void print() 
{ 
    int k; 
    for (k=0; k<=7; k++) 
 { 
 printf(" %d", x[k]); 
 } 
    printf("\n"); 
} /* End print */ 

  4538P057.HTM
  OSSG Documentation
  22-NOV-1996 13:03:01.83

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal