Send message to program (STXIT routine)
Component: | BS2000 |
Functional area: | Job processing |
Domain: | JOB |
Privileges: | STD-PROCESSING |
Function
The INFORM-PROGRAM command enables a nonprivileged user to send a message to an interrupted program in the user’s own task.
The interrupted program is continued at the address defined in the STXIT macro for the event: “message to the program”. If the program does not contain a STXIT routine for this event, the INFORM-PROGRAM command is rejected and an error message is issued. The occurrence of the “message to the program” event is independent of a message that the user can additionally specify in the MSG operand.
A message specified in the MSG operand will, if specified in the STXIT macro, be transferred to an area in the program defined expressly for that purpose.
The STXIT mechanism is described in the “Executive Macros” manual [22].
Privileged functions
Systems support (TSOS or OPERATING privilege) can also use the command to send a message to a loaded program in a noninteractive task.
If the program does not have an STXIT routine for this event, the command is accepted but has no effect. If there is no program loaded in the task, the command is rejected.
Using this privileged function, systems support can among other things terminate specific database applications gracefully before system shutdown by informing them that the “message to the program” event has occurred. If the database has been programmed to process the event, it can take steps to shut itself down.
Format
INFORM-PROGRAM | Alias: IFPG | ||||||||||||||||||||||||
| |||||||||||||||||||||||||
Operands
MSG = *NO / <c-string 1..64 with-low>
Text of the message to be sent to the program.
The default is *NO, which means that no message will be sent.
The length of the message is limited to 64 characters. Shorter messages have a null byte appended to the right to indicate end-of-text in the receive area. If no area for message transfer was defined in the STXIT macro, the specified message is ignored. If no message is specified although an area has been defined, a null byte is transferred.
JOB-IDENTIFICATION = *OWN / *TSN(...) / *MONJV(...)
Indicates the form of identification used for the task in which the target program is running. An interrupted program in the user’s task (*OWN) or in some other nonnteractive task (*TSN or *MONJV) is to be informed that the “message to the program” event has occurred. Additionally, the user can send a message comprising up to 64 characters to the program (see MSG operand).
JOB-IDENTIFICATION = *OWN
The user informs an interrupted program running in his own task.
JOB-IDENTIFICATION = *TSN(...)
Only privileged users (OPERATING or TSOS privilege) are allowed to select this value.
The task in which the target program is running is identified by its TSN. The target must not be an interactive task.
TSN = <alphanum-name 1..4>
Task sequence number.
JOB-IDENTIFICATION = *MONJV(...)
Only privileged users (OPERATING or TSOS privilege) are allowed to select this value.
The task in which the target program is running is identified by its monitoring JV. The target must not be an interactive task.
MONJV = <filename 1..54>
Name of the job variable monitoring the job.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | No errors | |
64 | EXC0920 | Specified job ID invalid | |
64 | EXC0921 | Command not permitted for interactive tasks | |
64 | EXC0922 | No program loaded | |
64 | EXC0923 | No STXIT interface defined for this event in specified program | |
64 | EXC0924 | No STXIT routine defined for this event in specified program | |
64 | EXC0925 | STXIT routine already activated | |
64 | EXC0090 | Insufficient storage space |