Symbolic memory references

Symbolic memory references may include all file, data and statement names from the program which are contained in the LSD records, as well as the source references generated by the compiler and the AID keywords.
No LSD records are generated for 88 levels, the NATIVE alphabet and for definitions from the REPORT-SECTION (apart from LINE-COUNTER, CBL-CTR and PAGE-COUNTER). Consequently you cannot access this data with AID.

All symbolic memory references can be subjected to the operations described in AID Core Manual (Related publications) [1]. All operands in which that is possible contain the entry compl-memref. In accordance with the restrictions described, the user can then switch between the memory references as described in this manual and those for debugging on machine code level (see Debugging on Machine Code Level (Related publications) [2]).

filename

is the name of a file from a file definition in the FILE-SECTION of the DATA DIVISION. AID outputs the following information in response to the %DISPLAY and %SDUMP commands: the file status and, if the file is open, the contents of the data record area and any record key. In addition, the address and length selector can be used on filename.

Example

<FILE(size),format> file-name

_FILE_NAME = |file-name-complete|

_OPEN_MODE = {CLOSE | OPEN-INPUT | etc.}

_RECORD    =

[|]Content-of-the-current-record-(first-<80-symbols)[|][...]

file-name-complete is a fully qualified name of the file file-name . The length of the record of the file is size bytes. _RECORD contains a character string ( format =C) or bytes (X) of the current record (followed by three periods if the output is incomplete).

dataname

stands for all the names of data items defined in the DATA DIVISION in the source program, for the COBOL special registers and the figurative constants. Data items can be data records, group items and tables, or elements in these. They can be identified and indexed.
dataname is an alphanumeric string up to 30 characters in length. It can be specified in all commands for output and modification of information; these are the %DISPLAY, %MOVE, %SDUMP and %SET commands, but also the %FIND command (search for a string) and the %ON command (write monitoring).

dataname [identifier][...] [(index[,...])]

identifier

If dataname is not unambiguous within a program unit, it can be identified by being assigned to a particular data item with IN or OF. dataname must be assigned as many identifiers as are required to designate it unambiguously. If it is not identified, there must be a definition on level 01 or 77 which AID then processes, otherwise an error message will be issued.

In complex memory references, identifier cannot always be specified.

identifier is specified as follows:

{ IN | OF }  data-item-name

index

If dataname is the name of an element in a table, it can be indexed and subscripted as in a COBOL statement. In contrast to COBOL, multiple indexes have to be separated by a comma.

Data definitions which are subordinate to a dataname with an OCCURS clause must be assigned as many indexes in the %SET or %SDUMP as have to be specified for access in a COBOL statement. The index entry for the data name that is addressed with dataname can be omitted from the %DISPLAY, %FIND and %MOVE, and it is then only necessary to specify index entries for higher index levels (see example). Otherwise it is possible to specify a dataname without index in the %DISPLAY, %FIND and %MOVE if the dataname was itself defined with the OCCURS clause. This has the effect of addressing all elements with that name.

index is specified as follows:

{  n |  index-name | dataname | TALLY | arithmetic-expression }

n
is an integer with a value 1 ≤ n ≤ 2³¹-1.

index-name
is the symbolic name defined in the INDEXED BY clause for indexing a table level.

dataname
designates a numerical data item (not floating point) from the DATA DIVISION that can be identified. It must be contained in the same program unit as the table.

TALLY
is the special register generated by the COBOL compiler for each program.

arithmetic-expression
AID calculates the value for index. Valid entries are the arithmetic operators (+,,/,*) and the above-listed operands n, dataname and TALLY. index-name can only be combined with n and may only be used to index the table level to which it was assigned via the INDEXED BY clause.

Example

01  TABLE.
  02  GROUP1                           OCCURS 10.
      04  ELEMENT1    PIC X(5).
      04  ELEMENT2    PIC 9(2)         OCCURS 6.
  02  GROUP2          PIC 9(2)         OCCURS 12.
01  FIELD             PIC X(70).
01  INPUT-STRUCTURE.
  02  GR1.
      04  ELEM1       PIC X(5).
      04  ELEM2       PIC 9(2).
  02  GR2             PIC 9(2)         OCCURS 12.

The various data names can be addressed in an AID command in the following way:

%DISPLAY GROUP1

All elements GROUP1(1) to GROUP1(10) are output.

%MOVE GR1 INTO GROUP1

This command overwrites all elements GROUP1(1) to GROUP1(10) with the contents of GR1.

%MOVE GR1 INTO GROUP1(1)

The first element GROUP1(1) is overwritten.

%MOVE GROUP2 INTO GR2

The entire contents of GROUP2(1) to GROUP2(12) are transferred to GR2(1) to GR2(12). It is not possible, on the other hand, to write the following command:

%SET GROUP2 (1) INTO GR2

Full indexing is required in the %SET command, as in COBOL statements.

%SET GROUP2 (1) INTO GR2 (12)

%SET GR2 (ELEM2) INTO ELEMENT2 (5,ELEM2)

Range of indexes

You can specify a range of indexes:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
array (index{,...})
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

index1 : index2
This designates the range between index1 and index2. Both must lie within the index limits, and index1 must be less than or equal to index2.

*
This designates the entire index range of the dimension. In the case of singledimensional arrays, this is equivalent to using the array name without indexing.

You can only use range specification in the %DISPLAY command. Array names with range specifications must not be used in address calculations.
Modifications of type or length are not permitted.

Examples

%D array (*,3)

In a two dimensional array, all elements belonging to the first dimension and whose second dimension index is 3 are output.

%D array (1 : 3,*,5 : 15)

The following elements are output from a three dimensional array:

• • • The index of the first dimension is 1, 2 or 3,
    • The index of the second dimension ranges from the lower index limit to the upper index limit
    • The index of the third dimension ranges from 5 to 15.

COBOL special registers

Only those special registers may be specified that have been created by the COBOL compiler for the program and that have already been supplied with the current values.

For instance, SORT special registers may be specified here only if the program contains a sort section.

LINAGE-COUNTER
RETURN-CODE
SORT-CCSN
SORT-CORE-SIZE
SORT-EOW
SORT-FILE-SIZE
SORT-MODE-SIZE
SORT-RETURN
TALLY

Figurative constants

dataname is one of the COBOL names for figurative constants or the name of a symbolic character which is defined in the SPECIAL-NAMES paragraph. HIGH-VALUE and LOW-VALUE always represent the alphanumeric value that corresponds to them by defaultor in accordance with the definition in the PROGRAM COLLATING SEQUENCE clause.

ZERO
SPACE
HIGH-VALUE
LOW-VALUE
QUOTE
symbolic character

statement-name

designates the address of the first instruction in a section or paragraph in the PROCEDURE DIVISION.

{ L'section' | L'paragraph' [IN L'section'] }

In the %CONTROLn, %DISASSEMBLE, %INSERT, %JUMP and %TRACE commands, an alphanumeric section or paragraph name can be specified without L’...’ since in these commands this name cannot be confused with a data name. If in a complex memory reference statement-name is followed by a pointer ( -> ), the L’...’ format must be used. If a paragraph name is not unambiguous within a program, it must be identified by the section name of the section in which it was defined: L'paragraph' IN L'section'

You thus define the address in the %DISPLAY, %FIND, %MOVE and %SET commands. %DISASSEMBLE, %INSERT and %JUMP are used to define the memory location at this address. %CONTROLn and %TRACE are used to define the entire section or the entire paragraph

source-reference

is an address constant for the compiler-generated designation of a statement. Its structure varies in accordance with the SDF option TEST-SUPPORT with the operand STM-REFERENCE.

STM-REFERENCE=LINE-NUMBER

S’n[verb[m]]’

n
is the line number in the PROCEDURE DIVISION, assigned by the compiler. It is not permitted to enter leading zeros. In this case the source-reference is unambiguous within a compilation unit. You specify S’n’ for lines with paragraph or section names only if no COBOL verb is present.

verb
is the defined abbreviation of a COBOL verb in the statement line designated with n.You specify S’nverb’ for lines containing a COBOL verb.

m
is a single-digit number > 1. m is specified only if the same COBOL verb appears more than once in a line and the first COBOL verb is not to be addressed. It is thus declared to be the m-th COBOL verb within the line.

STM-REFERENCE=COLUMN1-TO-6
S’xverb[m]’

x
is the unchanged contents of columns 1 to 6 of a source program line. Any blanks included must be specified.
If a source code line cannot be uniquely identified by x...x within the compilation unit as a whole, the source reference is not unambiguous either. Paragraphs and sections cannot be addressed via a source reference in this case.

verb
is the designated abbreviation of a COBOL verb in the statement line identified by x. S’xverb’ must be specified for lines containing a COBOL verb.

m
is a single-digit number > 1.
It identifies the m-th COBOL verb within a line. A line in this case is understood to be all statements up to a new line number.

In %FIND and %ON write-event, the source reference must be followed by the pointer operator. This identifies four bytes of the machine code starting from the address that is stored in the address constant. You thus define the address in the %DISPLAY, %MOVE and %SET commands. %DISASSEMBLE, %INSERT and %JUMP are used to define the memory location at this address. In the %CONTROLn and %TRACE commands you can define an area using two source references.

Example

%DISPLAY S'95ADD2'

The program was compiled with STM-REFERENCE=LINE-NUMBER. The source
reference specifies the address associated with the second ADD statement stored in line 95 in the LSD records. This is the address of the memory location of the first command generated for this statement.

abbr.    COBOL verb

abbr.   COBOL verb

ACC    ACCEPT ADD    ADD ADDC   ADD CORRESPONDING ALLO   ALLOCATE ALT    ALTER CALL   CALL CANC   CANCEL CLO    CLOSE COM    COMPUTE CON    CONNECT CONT   CONTIUE DEL    DELETE DIS    DISPLAY DIV    DIVIDE DSC    DISCONNECT END    END-xxx ENTR   ENTRY ERA    ERASE EVAL   EVALUATE EXI    EXIT [PARAGRAPH/SECTION] EXIT   EXIT {PROGRAM/METHOD} FET    FETCH FIN    FINISH FND    FIND FRE    FREE GEN    GENERATE GET    GET GO     GOBACK GOT    GO TO IF     IF INIT   INITIALIZE

INI    INITIATE INSP   INSPECT INV    INVOKE KEE    KEEP MOD    MODIFY MOV    MOVE MOVC   MOVE CORRESPONDING MRG    MERGE MUL    MULTIPLY OPE    OPEN PER    PERFORM or EXIT PERFORM PERT   TEST OF PERFORM RAIS   RAISE REA    READ REDY   READY REL    REALSE RET    RETURN REW    REWRITE SEA    SEARCH SET    SET SOR    SORT STA    START STO    STOP STOR   STORE STRG   STRING SUB    SUBTRACT SUBC   SUBTRACT CORRESPONDING TER    TERMINATE UNST   UNSTRING WRI    WRITE

Table 1: List of COBOL verbs and their abbreviations