Send Scope Message (QMHSNDSM) API

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 is called from the same state as the sender of the scope message. For example, IBM APIs cannot be specified as a scope handling program if the API is system state. Instead, a user program that invokes the API must be created and that user program would be specified as the scope handling program for this API.

This API returns the message key which can be used to end scoping by deleting the message.

Authorities and Locks

Scope program

*USE

Scope program library

*EXECUTE

Required Parameter Group

Scope type

INPUT; CHAR(10)

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.

Qualified scope program name

INPUT; CHAR(20)

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

Scope program data

INPUT; CHAR(*)

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.

Scope program data length

INPUT; BINARY(4)

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.

Message key

OUTPUT; CHAR(4)

The key to the scope message being sent.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Error Messages

[ Back to top | Message Handling APIs | APIs by category ]