ACTIVMSG

Purpose

You can use the ACTIVMSG command to respond to ACTIVE and UP messages from an application by changing the SA z/OS status of the application. ACTIVMSG calls the ISSUEACT command to also issue commands and replies that are defined in the automation policy for both the ID of the ACTIVE or UP message and for the new status of the application. Typically, ACTIVMSG is called from the NetView automation table.

Syntax

Read syntax diagramSkip visual syntax diagramACTIVMSGUP=NOUP=YESJOBNAME= jobnameMSGTYPE= typeEHKVAR=YESEHKVAR=NOREPLY=NOREPLY=YESPASSES=NOPASSES=YESCODE1= code1CODE2= code2CODE3= code3PID= numberASID= asid

Parameters

UP
This parameter is used to distinguish between ACTIVE messages and UP messages. ACTIVE messages indicate that the job associated with an application is working but is not yet available for use. UP messages indicate that the job associated with an application is available for use.
NO
NO should be used if you are responding to an application ACTIVE message. The application is placed in ACTIVE status if it is not there already. UP=NO is the default.
YES
YES should be used if you are responding to an application UP message. The application is placed in UP status if it is not there already. If the application is a transient job then it is placed in RUNNING status.
JOBNAME
The name of the job that the message is for. If not specified, the job name is taken from the message's job name field. You must supply a value for the job name if you are calling ACTIVMSG from a CLIST.
MSGTYPE
This parameter is used to search for command and reply entries to subsystem/msgtype-pairs in the automation control file, where subsystem is the subsystem name derived from the job name.

When a match occurs, the commands that are associated with the entries are issued. This is in addition to the entries that are associated with the ENTRY-TYPE pair subsystem/ACTIVE if UP=NO and subsystem/UP if UP=YES.

If parameter MSGTYPE is not specified, the message identifier of the message that ACTIVMSG is called for is taken as the default.

EHKVAR
This parameter determines whether the tokens of the parsed message text are to be stored in task global variables EHKVAR0 through EHKVAR9 and EHKVART.
YES
The tokens of the triggering message are to be assigned to the task global variables EHKVARn.
NO
No values are to be assigned to the task global variables EHKVARn.
REPLY
This parameter determines whether a defined reply is issued for a message that ACTIVMSG has been called for.
YES
A defined reply in the automation policy for the message that is being handled by ACTIVMSG is issued. REPLY=YES is assumed as the default if the message is a WTOR, otherwise the default is REPLY=NO.
NO
A defined reply for a WTOR that is being handled by ACTIVMSG is not issued.
PASSES
Specifies whether passes are used to issue commands or replies (or both) that have been defined in the automation policy.
YES
PASSES=YES is passed to the ISSUEACT command.
NO
PASSES=NO is passed to the ISSUEACT command.
CODE1=code1 CODE2=code2 CODE3=code3
These parameters are passed to the ISSUEACT command, where they are used to select defined commands and replies via code entries.
PID
The process ID of the resource. Together with the ASID, it uniquely identifies the resource.
ASID
The ASID that is associated with the resource. Together with the PID, it uniquely identifies the resource.

Restrictions and Limitations

  • If ACTIVMSG is driven by a delete operator message, no action is taken in response to this message.
  • Defined commands and replies are only issued in response to a message or a status change if the start flag of the related minor resources of the application allows automation.
  • If commands or replies are defined for the triggering message, the triggering message is automatically captured by ISSUEACT (see ISSUEACT (ISSUECMD, ISSUEREP)). If not, ACTIVMSG captures the triggering message with a default severity of NORMAL. The default severity can be overridden using the code definitions under pseudo-message ID CAPMSGS. Under CODE2, specify MVSESA for messages with SYSTEMMSG=YES, or otherwise, the subsystem's jobname. The severity used is the content of Value Returned of the first row that matches in the code definitions table. CODE3 is not considered. To avoid message capturing, set Value Returned to *IGNORE*.

Usage

You should typically call the ACTIVMSG command from the NetView automation table.

It is recommended that you use ACTIVMSG for all IEF403I (job started) messages.

If ACTIVMSG is called for a WTOR and it is not replied to, OUTREP is called to track the WTOR.

If you are invoking ACTIVMSG for a generic message you should use the ING$QRY NetView automation table function to screen the message before invoking ACTIVMSG. See ING$QRY for more information.

ACTIVMSG should run on the working operator of the subsystem that issued the message. Otherwise, the ACTIVMSG command will run asynchronously to the calling procedure. This means that when the calling procedure regains control, the status of the affected subsystem may not yet have changed.

All commands and replies that are triggered through ACTIVMSG have access to the SAFE, called AOFMSAFE, that stores the message that caused the ACTIVMSG call.

Task Global Variables

EHKVAR0 through EHKVAR9 and EHKVART
When defining the commands in the automation control file to be issued by command ACTIVMSG, the variables &EHKVAR0 through &EHKVAR9 and &EHKVART can be used to be substituted by the tokens of the parsed message that has driven ACTIVMSG. &EHKVAR0 will be substituted by the message ID, &EHKVAR1 by the first token of the message text after the message ID, &EHKVAR2 with the second token and so forth. &EHKVART will be substituted by the trailing message text after the 9th token.

Examples

The following example shows how ACTIVMSG is called from the NetView automation table:

IF MSGID = 'IEF403I' & TOKEN(2) = SVJOB & DOMAINID = %AOFDOM% 
   & ATF('ING$QRY APPL,,JOB='VALUE(SVJOB)) ^= ''
THEN
EXEC(CMD('ACTIVMSG JOBNAME=' SVJOB)
ROUTE(ONE %AOFOPGSSOPER%));