| 1 | Scope type | Input | Char(10) |
| 2 | Qualified scope program name | Input | Char(20) |
| 3 | Scope program data | Input | Char(*) |
| 4 | Scope program data length | Input | Binary(4) |
| 5 | Message key | Output | Char(4) |
| 6 | Error code | I/O | Char(*) |
The Send Scope Message (QMHSNDSM) API sends a scope message to a call stack entry.
Scope messages are a way to call a program when the call stack entry that called the QMHSNDSM API ends or when the job using this API ends. The exit can be normal or abnormal. The three scope types, *EXT, *PGM, and *CSE, indicate when the scope handling program should be called. To have the scope handling program run at job or routing step ending, specify *EXT for the scope type parameter. The difference between program scoping (*PGM) and call stack entry (*CSE) scoping is how they handle a transfer control. When a transfer control occurs, the scope handling program is called for scope type *PGM because the program or ILE procedure ended, but the scope handling program is not called for scope type *CSE because the call stack is still active.
When a scope message is sent in a multithreaded job with a scope type of *PGM or *CSE, the scope handling program runs in the thread that used the QMHSNDSM API to send the scope message. When a multithreaded job uses a scope type of *EXT, the scope handling program runs in the initial thread when the job or routing step ends.
You must also specify a scope-handling program to be run when the job, program or call stack entry exits. You must have at least *EXECUTE authority to the scope-handling program library and at least *USE authority to the program. If the user has below the minimum authorization, the scope message is sent but an authorization violation is signaled when the scope-handling program is called and it is not run. Any adopted authority the sending program may have does not affect the user's authority to the scope-handling program. The scope-handling program runs in the same state as the sender of the scope message.
This API returns the message key which can be used to end scoping by deleting the message.
The type of scoping to be done. Valid values are:
| *EXT | Scope handling program is called when the caller's job or routing step ends. |
| *PGM | The scope-handling program is called when the caller's program ends or a transfer control is issued. |
| *CSE | The scope handling program is called only when the call stack entry ends. A transfer control does not cause the scope handling program to be called. |
The name of the scope handling program and the library in which it resides. The first ten characters represent the program name, the second ten characters the library name.
The library can have these special values:
| *LIBL | The library list is used to find the scope handling program |
| *CURLIB | The current library is used to find the scope handling program |
Data that is passed to the scope handling program as its one and only parameter.
The user is responsible for the format of this data. Any pointers contained in the data must begin on a 16-byte boundary.
This data is copied to another area in storage when the scope message is sent. When the scope program is called, a space pointer pointing to the copied data is passed to the scope handling program.
The length, in bytes, of the scope program data. The valid range is 0 through 32 767. If a data length of zero is specified, a null pointer is passed to the scope handling program.
The key to the scope message being sent.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2401 E | Not authorized to library &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9805 E | Object &2 in library &3 destroyed. |
| CPF9810 E | Library &1 not found. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |