%ON

With the %ON command you define events and subcommands. When a selected event occurs, AID processes the associated subcmd.

• With write-event you define a write access event, accessing a memory area. Whenever the program writes to the specified memory area, AID is to interrupt the program and process the subcmd.

• With event you define one of the other events (normal or abnormal program termination, a supervisor call (SVC), a program error or any event for which AID is to interrupt the program in order to process the subcmd.

• With subcmd you define a command or a command sequence and perhaps a condition. When event occurs and this condition is satisfied, subcmd is executed.

Kommando	Operand
%ON	{write-event | event} [<subcmd>]

If the subcmd operand is omitted, AID inserts the subcmd <%STOP>.

The subcmd of an %ON command for an event which has already been defined does not overwrite the existing subcmd, rather the new subcmd is prefixed to the existing
subcommand. This means that chained subcommands are processed in accordance with the LIFO principle. This does not apply to write-event. The entry of a new write-event overwrites an existing one.

Once an event is entered it applies until it is deleted with %REMOVE or until the end of the program.

The base qualification E=VM must apply for %ON (see %BASE).

The %ON command does not alter the program state.

tDDDDDDDDDDDDDh
write-event

gDDDDDDDDDDDDDu

The %WRITE keyword activates write monitoring. It is followed by the memory area to be monitored, in parentheses. If the program changes a byte within the specified area, the program is interrupted and the subcmd is executed. The interrupt is effected after the instruction that caused the change at the memory location; it may also occur in a runtime routine.

Only one write-event can be defined at any one time. The entry of a new write-event overwrites an existing one. Other events can, however, be registered at the same time. If an event arrives at the same time as a write-event, AID processes the subcommand associated with write-event first.
The write-event can be deleted with %REMOVE %WRITE without specifying the memory reference.

The following interaction occurs between %ON write-event and other AID commands:

• If a %CONTROLn or a %TRACE is registered with a criterion on the machine code level, the entry of %ON write-event is rejected with an error message.

• If a machine instruction has been overwritten with the internal AID mark (X’0A81’) by a %CONTROLn or %TRACE with a symbolic criterion, AID does not notice the write access by this instruction.

• Also if a machine instruction has been overwritten with the internal AID mark by the test point declared with %INSERT, AID does not notice the write access by the instruction.

In order to ensure unbroken write monitoring it is advisable to delete all %CONTROLn and %INSERT commands using %REMOVE and to delete any %TRACE commands that may still be entered by continuing with %RESUME after the %ON.

The memory area to be monitored can be any memory object, however it is addressed. It is defined by the start address and the implicit or explicit length. The maximum length of the area is 64 Kbytes, otherwise an error message is output.

If the address of the specified memory object is overloaded in the case of a program with an overlay structure, the corresponding area in the newly loaded program section.

write-event-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - -
%write ( [{• | S=srcname•[PROC=program-id•]}] {   C=segmentname
                                                | C=sharename
                                                | dataname
                                                | 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.
In addition, there must be a period between the PROC qualification and the following operand part.

S=srcname

This need only be specified if write-event is not to be declared for the current compilation unit.

PROC=program-id

This need only be specified if you reference a data name or statement name that is not contained in the current program (see chapter “COBOL-specific addressing”) or is not unique in the current compilation unit.

If srcname in the S qualification and program-id are not the same, instead of both of these you should write only the PROG qualification.

The C qualifications listed below cannot be preceded by a qualification. The C qualification takes the user away from the symbolic level.
It is not permissible to write a symbolic operand directly afterwards (see section “Symbolic memory references”), only a compl-memref.

C=segmentname

The memory area to be monitored comprises the segment designated with this specification.

C=sharename

The memory area to be monitored comprises the object module designated with this specification.

dataname

is the name of a data item as defined in the source program or of a COBOL special register. It can be identified and indexed in the same way as in the COBOL program (see section “Symbolic memory references”, dataname).

dataname is an alphanumeric string consisting of up to 30 characters.

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

identifier

If dataname is not unambiguous within a program, it is assigned to a particular group item with IN or OF. dataname must be assigned as many identifiers as are required to designate it unambiguously. If it is not identified, AID processes dataname if a data definition is provided for it at level 01 or 77. If this is not the case, an error message is issued.

index

If dataname is the name of an element in a table, it can be indexed and subscripted; the notation differs from COBOL only in that indexes must be separated by a comma.
If the name of a table element is specified without an index, the entire table is referenced.
index may be specified as follows:

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

COBOL special registers

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

{ statement-name  | source-reference } ->

designates 4 bytes of the program code from the address contained in the address constant. If a different number of bytes is to be searched, you must specify a corresponding length modification.

statement-name

must be specified in one of the following formats:

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

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

must be specified in one of the following formats:

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 following operations may occur in compl-memref (see AID Core Manual (Related publications) [1]):

• byte offset (•)

• indirect addressing (->)

• type modification (%A, %S, %SX)

• length modification (%L(...), %L=(expression), %Ln)

• address selection (%@(...))

compl-memref designates an area of 4 bytes starting from the calculated address. If a different number of bytes is to be searched, a corresponding length modification must be added. When modifying the length of data items you must pay attention to area boundaries or switch to machine code level using %@(dataname)->. If a 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.

event

A keyword is used to specify an event (program error, abnormal termination of the program, supervisor call, etc.) upon which AID is to process the subcmd specified. The response to an event code that has been processed with a STXIT routine cannot be a subcmd that has been defined for that event. If a subcommand is executed in relation to the %ANY event, at the subsequent termination of the program there is no query as to whether a dump is to be output. It may be necessary for the user to initiate output of the dump in the subcommand with /CREATE-DUMP.

If several %ON commands with different event declarations are simultaneously active and satisfied, AID processes the associated subcommands in the order in which the keywords are listed in the table below. If various %TERM events are applicable, the associated subcommands are processed in the opposite order in which the %TERM events have been declared (LIFO rule as for chaining of subcommands). If a write-event occurs at the same time as another event, the subcommand relating to the write-event is processed first. For selection of the SVC numbers and event codes see Executive Macros (Related publications) [8].

event	subcmd is processed:
%ERRFLG (zzz)	after  the occurrence of an error with event code zzz and before abortion of the program.
%INSTCHK	after  the occurrence of an addressing error, an        impermissible supervisor call (SVC), an        operation code which cannot be decoded,        a paging error or a privileged operation and before abortion of the program.
%ARTHCHK	after  the occurrence of a data error, divide error        exponent overflow or a zero mantissa and before abortion of the program.
%ABNORM	after  the occurrence of one of the errors        covered by the previously described events
%ERRFLG	after  occurrence of an error with any event.
%SVC(zzz)   %SVC	before execution of the supervisor call (SVC) with        the specified number before execution of any supervisor call (SVC).
%LPOV(x...x) %LPOV	after  loading of the segment with the specified name. after  loading of any arbitrary segment        (the name is output with %D %LINK)
%TERM(N[ORMAL]) %TERM(A[BNORMAL]) %TERM(D[UMP]) %TERM(S[TEP]) %TERM	before normal termination of a program. before abnormal termination of a program, but after  output of a memory dump. before output of a memory dump with subsequent        termination of the program before termination of the program with subsequent        branching within procedures before termination of a program with because of a        events described above.
%ANY	before termination of a program with because of a        program error or as a result of the        %TERM events described above.

zzz	may be specified in one of two formats:
	n #ff’	unsigned decimal number of up to three digits two-digithexadecimalnumber'
	The following applies for the value zzz: ≤ zzz ≤ 255 No check is made whether the specified number of the error weight or the SVC number is meaningful or permissible.

subcmd

is processed whenever the specified event occurs in the course of program execution. If the subcmd operand is omitted, AID inserts a <%STOP>.

For a complete description of subcmd refer to the AID Core Manual (Related publications) [1].

subcmd-OPERAND  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<[subcmdname:] [(condition):] [ { AID-command | BS2000-command } {;...}]>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

A subcommand may comprise a name, a condition and a command part. Every
subcommand has its own execution counter. The command portion can consist of either an individual command or a command sequence; it may contain AID and BS2000 commands as well as comments.

If the subcommand contains a name or condition but no command part, AID merely increments the execution counter when the declared event occurs.

subcmd does not overwrite an existing subcommand for the same event. Instead, the new subcommand is prefixed to the existing one. The %CONTROLn, %INSERT, %JUMP and %ON commands are permitted in subcmd. The user can form up to 5 nesting levels. An example can be found under the description of the %INSERT command.

The commands in a subcmd are executed one after the other; then the program is continued. The commands for runtime control immediately alter the program state, even in a
subcommand. They abort subcmd and continue the program (%CONTINUE, %RESUME, %TRACE) or halt it (%STOP). They should only be placed as the last command in a subcmd, since any subsequent commands of the subcmd will not be executed. Likewise, deletion of the current subcommand via %REMOVE makes sense only as the last command in subcmd.

Examples

1. %ON %LPOV (MONA12) <%D 'MONA12 GELADEN'; %STOP>
   Each time the segment MONA12 is loaded AID outputs the message ’MONA12 GELADEN’ and halts the program.

2. %ON %ERRFLG (108)

   %ON %ERRFLG (#6C')'

   Both specifications designate the same program error (mantissa equals zero).

3. %ON %ERRFLG (107) <%D 'ERROR'>
   This event code does not exist, therefore the subcmd defined for this event will never be started.

4. %ON %WRITE(PROG=HPROG.TABLE) <%D %HLLOC(%PC ->),TABLE F1=MAX>
   Whenever data has been overwritten in TABLE in the main program HPROG, the symbolic localization information about the current program count and the contents of TABLE are output. The output is sent to the file that was assigned to the link name F1. The program then continues.
   A search can then be run in this file to establish when TABLE was overwritten.