TERM - Terminate program and procedure step

General

Application areas:	Starting, interrupting and terminating; see "Starting, interrupting and terminating"Debugging aids; see "Debugging aids"
Macro type:	Type S, MF format 1: standard/E/L form; see "S-type macros"

Macro description

The TERM macro performs the following functions:

• Terminate program (default value)

• Terminate program and procedure step (UNIT=STEP operand)

• Issue memory dump (DUMP operand)

• Transfer return code to program-monitoring job variable (URETCD operand)

All input/output operations initiated by the program before the execution of the macro are completed prior to program termination.

Macro format and description of operands

TERM

UNIT=PRGR / STEP

,DUMP=N / Y

,MODE=NORMAL / ABNORMAL

[,URETCD=code / addr / (r)]

,MF=S / (E,..) / L

UNIT=
Determines whether or not a distinction is to be made between modes during program termination.

PRGR
Default setting: the program is terminated.

STEP

Terminates the program, taking into account the mode in which the program was executing.

• Interactive mode:
  If the program was called in a non-S procedure, the system also branches to the next SET-JOB-STEP, EXIT-JOB, END-PROCEDURE or CANCEL-PROCEDURE command. If the program was called in an S procedure, the system also protects SDF-P error handling.

• Batch mode (ENTER file):
  The system also branches to the next SET-JOB-STEP or EXIT-JOB command.

Note

The following specifications are recommended:
UNIT=PRGR if MODE=NORMAL
UNIT=STEP if MODE=ABNORMAL

DUMP=
Determines whether a memory dump is to be issued.

N
Default setting: no memory dump is issued.

Y
Issues a memory dump unless DUMP=NO was specified in the MODIFY-TEST-OPTIONS command.

MODE=
Specifies the way in which the program is to terminate.

NORMAL
Default setting: the program is to terminate normally.
For users of job variables: The status indicator of a program-monitoring variable, if present, is set to C'$T'BLANK''.

ABNORMAL
The program is to terminate abnormally. The message
.... ABNORMAL PROGRAM TERMINATION (&00) is output.

(&00)= NRT0001 if UNIT=PRGR was specified
(&00)= NRT0101 if UNIT=STEP was specified

For users of job variables:
The status indicator of a program-monitoring job variable, if present, is set to C'$A'BLANK''.See also the Note above.

MF=

For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

The following operand is only available to users who have the software product JV (see the “JV” [22 (Related publications)] manual) at their disposal:

URETCD=code
Specifies a 1- to 4-byte alphanumeric value in decimal (C'cccc') or hexadecimal
(X'xxxxxxxx') form. The program returns this value as a return code to the programmonitoring job variable (left-justified, bytes 4-7).

Note

If the operand is missing, the value C'    ' is returned to the program-monitoring job variable.
This operand is ignored if no program-monitoring job variable has been defined.

addr
Relative virtual address of a 4-character alphanumeric value. The program returns this value as a return code to the program-monitoring job variable (bytes 4-7).

(r)
Register containing a 4-character alphanumeric value. This value is returned to the program-monitoring job variable as a return code (bytes 4-7). Register R0 is destroyed if URETCD=(r) is specified.

Functional description

When this macro is executed the following occurs:

• Any STXIT routine defined for the event class TERM is activated.
• All files assigned to the program and still open are closed.

• Memory assigned to the program is deallocated.

• AIDSYS is called with the event “TERM”.

• Bytes 8-30 are deleted in the physical device table for each released device. The first byte in the operation list is set to X'FF'. The program start address is set to 0 (4 bytes) in the program table entry.

• The system then changes over to command mode.

Notes on the macro call

• The operand is ignored if an invalid address is specified in the URETCD operand.

• Register R1 contains the operand list address.

  If the operand list address is invalid or invalid operands were specified,
  TERM UNIT=STEP,MODE=ABNORMAL,DUMP=Y
  is executed and the following error message is issued:

  %.... ABNORMAL PROGRAM TERMINATION NRT0601

• When the TERM macro with the operand DUMP=Y is called, the message

  PROCESSING INTERRUPTED AT... appears.

  Output of the memory dump depends on the value of the DUMP operand specified in the MODIFY-TEST-OPTIONS command. TERM activates one of the following messages in the case of DUMP=STD (default value):

  • in interactive mode:

    DUMP DESIRED ? REPLY (Y=YES, N=NO)

    Whether or not a dump is produced depends on the response to the query.

  • in batch mode and in procedures:

    SYSTEM REGULATIONS PROHIBIT DUMP

    No dump is produced.

  The dump is output to disk in unedited form as a PAM file (see the CDUMP2 macro). The file containing the dump is created under the user ID of the user who requested it. As soon as the dump is complete, the message

  DUMP WRITTEN,FILENAME=$userid.DUMP.tsn.i

  and the title line of the dump are output.
  If two or more dumps are requested for the same TSN, they are numbered consecutively (“i”). The file can be evaluated with the aid of the analysis program DAMP.