Commands › AGENTMSG Command: Send Messages to a Scheduling Manager

AGENTMSG Command: Send Messages to a Scheduling Manager

To send messages and issue commands to a scheduling manager, use the AGENTMSG command.

Type: General command

Authority: To issue the AGENTMSG command, you need read access to the SAF resource prefix.AGENTMSG.verbsubverb.name.

This command has the following format:

AGENTMSG {date|.} {time|.} managername {from|.} {objectname|.}
   verb subverb [(keyword)]

verb	subverb
CONTROL	MGRADDR PORT(number) ADDRESS(address) [PERSISTENT(TRUE|FALSE)]}

verb	subverb
STATE	COMPLETE
  "	FAILED

verb	subverb
ACTION	HOLD
  "	RELEASE
  "	INSERT

date

The date the message is sent. Specify the actual date or use a period (.) as a placeholder.

time

The time the message is sent. Specify the actual time or use a period (.) as a placeholder.

managername

Specifies the name of the scheduling manager to whom you want to send messages and issue commands. This is a required parameter.

from

Who sent the message. Specify the name of z/OS Agent sending the message or use a period (.) as a placeholder.

objectname

Name of the object to which the command refers. For the commands that are not related to a specific job, specify a period (.) in place of the job name.

For z/OS Agent applications, the object name is specified in the following format:

oooo[.qqqq]/aaaaa.ggggg/fffff

• oooo is the job name.
• qqqq is the optional qualifier.
• aaaaa is the application name.
• ggggg is the generation number of the application.
• fffff is the appl file name.

  Currently, there is only one appl file and its name is MAIN.

verb

Indicates the action to be taken. The values are:

• CONTROL
• STATE
• ACTION

subverb

Further defines the action to be taken.

keyword

Modifies the verb-subverb combination.

The Control Verb

The CONTROL verb requests the scheduling manager to do the action that the subverb specifies. The subverb is:

MGRADDR

Tells the scheduling manager to respond to messages from z/OS Agent on a new TCP/IP address and port. Use the MGRADDR subverb when you move z/OS Agent to a new system. You can issue the AGENTMSG command with the MGRADDR subverb from the original z/OS Agent or from the new z/OS Agent. The following list describes the associated operands:

PORT(number)

Specifies the port number of the new z/OS Agent. PORT is a required operand.

ADDRESS(address)

Specifies the TCP/IP address of the new z/OS Agent. ADDRESS is a required operand.

PERSISTENT (TRUE|FALSE)

Indicates a permanent change or a temporary change on the agent. PERSISTENT is an optional operand.

• TRUE—Permanently saves z/OS Agent address and receiver port number on the scheduling manager. This enables the scheduling manager to know which receiver to connect when required.
• FALSE—Indicates z/OS Agent address and receiver port number only change temporarily on the scheduling manager. The address and port number are reset to the values defined in the scheduling manager topology the next time the scheduling manager restarts. FALSE is the default.

Note: Consider the following items when using the MGRADDR subverb:

• There is also an MGRADDR command, which you can issue from the new master only.
• MGRADDR is also an initialization parameter.
• This change is temporary until the agent restarts. If you must make the change permanent, use the PORT(port) and PERSISTENT(YES) operands.
• If the scheduling manager communicates with more than one z/OS Agent, each z/OS Agent must be defined with a unique name in the scheduling manager. Each of these z/OS Agent names in the scheduling manager must match the ZOSAGENT initialization parameter of the corresponding z/OS Agent.

The STATE Verb

The STATE verb requests the scheduling manager to change the state of a job to the state the subverb specifies. The subverbs are:

COMPLETE

Changes the state to COMPLETE. All successor jobs are released. No further state messages are accepted. The job can be resubmitted if the application containing it is not yet complete.

FAILED

Changes the state to FAILED. User action is required to correct the error before resubmission.

The ACTION Verb

The ACTION verb requests the scheduling manager to do the action that the subverb specifies. The subverbs are:

HOLD

Places the specified job on hold.

RELEASE

Releases the job from a hold state.

INSERT

Inserts a new job in the application.

Example: Change z/OS Agent Address and Port on the Agent

In this example, the scheduling manager named MYSCHEDULER is requested to respond to z/OS Agent at port number 5100 and address 111.11.11.1. The port number and address are permanently saved in the scheduling manager so the scheduling manager knows which receiver to connect when required.

AGENTMSG . . MYSCHEDULER . . CONTROL Mgraddr Port(5100)+
  Address(111.11.11.11) PERSISTENT(TRUE)

Example: Place a Job on Hold

In this example, the AGENTMSG command tells the scheduling manager to place the job PROGRAM1 on hold.

AGENTMSG "PROGRAM1/TEST.2/MAIN ACTION HOLD"