By means of %INSERT you can specify a test point and define a subcommand. Once the program sequence reaches the test point, AID processes the associated subcommand. In addition, the user can also specify whether AID is to delete the test point once a specific number of executions has been counted and halt the program afterwards.
With test-point you may define the address of a command in the program prior to whose execution AID interrupts the program run and to process subcmd.
With subcmd you may define a command or a command sequence and perhaps a condition. Once test-point has been reached and the condition has been satisfied, subcmd is executed.
With control you can declare whether test-point is to be deleted after a specified number of passes and whether the program is then to be halted.
Command | Operand |
%IN[SERT] | test-point [<subcmd>] [control] |
A test-point is deleted in the following cases:
When the end of the program is reached.
When the number of passes specified via control has been reached and deletion of testpoint has been specified.
If a %REMOVE command deleting the test-point has been issued.
If no subcmd operand is specified, AID inserts the subcmd <%STOP>.
The subcmd in an %INSERT command for a test-point which has already been set does not overwrite the existing subcmd; instead, the new subcmd is prefixed to the existing one. The chained subcommands are thus processed according to the LIFO rule (last in, first out).
%REMOVE can be used to delete a subcommand, a test point or all test points entered.
test-point can only be an address in the program which has been loaded, therefore the base qualification E=VM must have been set (see %BASE) or must be specified explicitly.
%INSERT does not alter the program state.
test-point |
must be the address of an executable machine instruction generated for a COBOL statement. test-point is immediately entered by targeted overwriting of the memory position addressed and must therefore be loaded in virtual memory at the time the %INSERT command is input. Since, by entering test-point, the program code is modified, a test point which has been incorrectly set may lead to errors in program execution (e.g. data/addressing errors).
When the program reaches the test-point, AID interrupts the program and starts the subcmd.
test-point-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - [•][qua•][...] { C=segmentname | C=sharename | program-id | statement-name | source-reference | compl-memref } - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
•
If the period is in the leading position it denotes a prequalification, which must have been defined with a preceding %QUALIFY command. Consecutive qualifications must be separated by a period. In addition, there must be a period between the final qualification and the following operand part.
qua
Qualifications must be specified if an address operand is not valid for the current AID work area, the current compilation unit or the current program, or if it is not unambiguous in some other way.
E=VM
Since test-point can only be entered in the virtual memory of the program which has been loaded, specify E=VM only if a dump file has been declared as the current base qualification (see %BASE command).
S=srcname
Need only be specified if test-point is not to be contained within the current compilation unit.
PROC=program-id
Need only be specified if a statement name is not in the current program or if it is not unique in the current compilation unit (see chapter “COBOL-specific addressing”).
If srcname in the S qualification and program-id are the same, only the PROG qualification need be written.
Only the base qualification or the CTX qualification can be placed before the C qualifications listed below. The C qualification takes the user away from the symbolic level. No symbolic operands can be written directly afterwards (see section “Symbolic memory references”), only a compl-memref.
C=segmentname
With this specification you set test-point to the start address of the designated segment.
C=sharename
With this specification you set test-point to the start address of the designated reusable program.
program-id
This specification is possible after an explicit PROC/PROG qualification or if the current interrupt point is in the program that is identified by program-id. The effect is to set test-point to the first executable statement of the designated program.
statement-name
designates the address of the first instruction in a section or paragraph in the PROCEDURE DIVISION.
{ L'kapitel' | L'paragraph' [IN L'kapitel'] }
An alphanumeric section or paragraph name can be specified without L’...’ since this name cannot be confused with a data name in this command.
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'
source-reference
designates the address of the first instruction generated for a statement in the PROCEDURE DIVISION and must be specified in one of the following formats (see chapter “COBOL-specific addressing”):
S’n’
for lines with paragraph or section names in which no COBOL verb occurs. This specification is not possible for programs which have been compiled with STMT-REFERENCE=COLUMN1-TO-6.
S’nverb[m]’ | S’xverb[m]’
for lines containing a COBOL verb.
compl-memref
The result of compl-memref must be the start address of an executable machine
instruction. compl-memref may contain the following operations (see AID Core Manual (Related publications) [1]):
byte offset (•)
indirect addressing (->)
type modification (%A)
length modification (%Ln)
address selection (%@(...))
If compl-memref begins with a statement name or source reference, it must be followed by a pointer operator ( -> ). In this case statement-name must be specified with L’...’. Without the pointer operator the statement name and source reference can be used anywhere where hexadecimal numbers can be written.
Example: %INSERT L'PUTOUT' ->.4
test-point is set to the second instruction after the PUTOUT paragraph. The first instruction was 4 bytes long.
Type modification makes sense only if the contents of a data item can be used as an address or if you take the address from a register.
Example: %1G.2 %AL2 ->
The last two bytes from AID register %1G are used as the address.
subcmd |
A subcommand is processed whenever program execution reaches the address designated by test-point.
If the subcmd operand is omitted, AID inserts a <%STOP>.
A complete description of subcmd can be found in the AID Core Manual (Related publications) [1].
subcmd-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<[subcmdname:] [(condition):] [ { AID-command | BS2000-command } {;...}]>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
A subcommand may contain a name, a condition and a command part. Every subcommand has its own execution counter. The command portion can comprise a single command or a command sequence and may contain AID and BS2000 commands as well as comments.
If the subcommand consists of a name or a condition but the command part is missing, AID merely increments the execution counter when the test point is reached.
subcmd does not overwrite an existing subcommand for the same test-point, rather the new subcommand is prefixed to the existing one. The subcmd of an %ON or %INSERT may contain the commands %CONTROLn, %INSERT, %JUMP and %ON. Nesting over a maximum of 5 levels is possible.
The commands in a subcmd are executed one after the other; program execution is then continued. The commands for runtime control immediately alter the program state, even in a subcommand. They abort the subcmd and start the program (%CONTINUE, %RESUME, %TRACE) or halt it (%STOP). They are thus only effective as the last command in a subcmd, since any subsequent commands in the subcmd would fail to be executed. Likewise, deletion of the current subcommand via %REMOVE makes sense as the last command in subcmd only.
control |
specifies whether test-point is to be deleted after the n-th pass and whether the program is to be halted with the purpose of inserting new commands.
If no control operand has been specified, AID assumes the defaults 231-1 (for n) and K.
control-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ONLY n [ { K | S | C}
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
n | is a number with the value 1 <= n <= 231-1, specifying after how many test-point passes the further declarations for this control operand are to go into effect. |
K | test-point is not deleted (KEEP). Program execution is interrupted, and AID expects input of commands. |
S | test-point is deleted (STOP). Program execution is interrupted, and AID expects input of commands. |
C | test-point is deleted (CONTINUE). No interruption of the program. |
Examples
%IN S'48MOV'test-point is specified with a source reference and is set to the memory location of the instruction code generated for the MOVE in statement line 48.%IN ST3 <%DISPLAY PERSNR> ONLY 10 Stest-point is designated by the paragraph name ST3. Whenever the program sequence arrives at the first statement in paragraph ST3, the %DISPLAY command of the subcmd is executed. When test-point is reached for the 10th time, AID sets the program to STOP and deletes the test point, at which time you may enter new commands.%IN ST2 <%DISPLAY TEXTDAT, 'ST2'>%IN ST3 <%DISPLAY 'INSERT1', TEXTDAT; %IN PUTOUT<%D 'INSERT2', -I,J,K, NUMB-TABLE; %IN S'172' <%D 'INSERT3' ,I,J; %REMOVE PUTOUT>>>With the first %INSERT command, paragraph ST2 is set as the test-point. If, after the end of command input, the program execution reaches ST2, the subcommand is executed. It consists of a %DISPLAY command (for data name TEXTDAT) and the literal ’ST2’. Afterwards the program is continued.
By means of the second %INSERT command, test-point ST3 is declared. This %INSERT command contains two other nested %INSERT commands. Their test-point values are still inactive for AID. They do not become active until the test-point of the %INSERT command in whose subcmd they are defined is reached.
When program execution reaches paragraph ST3, the corresponding subcmd is executed, i.e. the %DISPLAY command for the literal ’INSERT1’ and the variable TEXTDAT is executed and the test-point PUTOUT is set.
The subcmd for test-point PUTOUT is still inactive. Thus, in the program to be tested, the following three test-points have been set at this stage in the program run: ST2, ST3 and PUTOUT.
As the subcmd for test-point ST3 does not contain any %STOP command, the program is continued after execution of subcmd. If program execution is not interrupted for some other reason, e.g. an error or the occurrence of an event declared by %ON, and finally reaches the symbolic address PUTOUT, then the %D command ’INSERT2’, I, J, K, NUMB-TABLE is executed. Furthermore, subcmd contains a further %INSERT command, whose test-point this time is specified with source-reference S’172’.
If the position marked S’172’ is reached during further program execution, AID executes the %DISPLAY command for the literal ’INSERT3’ and the contents of data items I and J. By way of the second command in this subcmd, the %REMOVE PUTOUT command, test-point PUTOUT is deleted. This is necessary, for instance, if a test-point is located in a loop and this would lead to an undesirable chaining of nested subcommands. Without the %REMOVE command, the following subcmd would be created for test-point S’172’ during the second pass of PUTOUT:
<%D 'INSERT3', I,J; %D 'INSERT3',I,J>- %OUT %DISPLAY P=MAX %IN S'73SET'
<%D 'I GE 10',I,CHAR(I),K,NR-C(I,K)>
%IN S'73SET' <(I LT 10): %D 'I LT 10',I,CHAR(I); %CONT>
First, all outputs of the %DISPLAY command are directed to SYSLST.
The two subsequent %INSERTs create the following subcommand at test-point S’73SET’:<(I LT 10): %D 'I LT 10',I,CHAR(I); %CONT; %D 'I GE 10',I,CHAR(I),-K,NR-C(I,K)>Every time the program sequence reaches the statement with the name 73SET, a check is made whether index I contains a value < 10. If the condition is satisfied, AID writes the comment ’I LT 10’ and the contents of I and CHAR(I) to SYSLST and, as a result of %CONTINUE, continues the program (with tracing, if the subcommand interrupted a %TRACE).
If the value of I is ≥ 10, AID writes the comment ’I GE 10’ and, in addition to I and CHAR(I), also the values of index K and table element NR-C(I,K) to SYSLST and likewise continues the program. In this case, too, any active %TRACE is continued.