Define an agent to the DOMAIN server.
CALL
SEND(agentInst, '_defineAgent ', agentName, rc
<, descriptor, runLoc, securityInfo,
scheduling, notifQueue, notifType, notifDisp>);
|
| Where... |
Is type... |
And represents... |
| agentName |
C |
user-specified name to be assigned to agent |
| rc |
N |
return code |
| descriptor |
C |
optional text description |
| runLoc |
C |
optional host location to run agent |
| securityInfo |
C |
optional security information |
| scheduling |
L |
optional repetitive run scheduling parameters |
| notifQueue |
C |
optional asynchronous notification queue name |
| notifType |
C |
optional run notification form |
| notifDisp |
C |
optional notification spool
disp |
- _defineAgent method
- defines an agent to the DOMAIN server. Any
SAS statements currently in the preview buffer are collected and defined to
the agent, so that when it runs, the collected statements will execute.
- agentName
- is a user-specified agent name that uniquely
identifies the agent. It must be unique within the application collection.
- rc
- identifies whether the agent was successfully
defined to the DOMAIN server.
All parameters that follow the rc parameter
are optional and positional. They are defined as follows:
- descriptor
- is a user-specified text description of
the agent.
- runLoc
- identifies the host and spawner on which
the agent should actually run when it executes. The agent may be defined to
the DOMAIN server that exists on host A, but the agent may actually be defined
to execute on host B. For example, the following specification indicates the
spawner is running on the node HOSTB.XYZ.COM and has a service name of SPAWNSRV:
//hostb.xyz.com/spawnsrv
Note: Windows and OS/2
hosts do not require the service name. All other hosts require both the node
name and service name. ![[cautionend]](../common/images/cautend.gif)
- securityInfo
- is the USERID.PASSWORD specification needed
when the agent actually runs (executes) on a given host. This may be different
from the USERID.PASSWORD that is specified on the _setDomainInfo method.
In that case, userid.password is used to communicate with the
DOMAIN server when running secured. In this case, userid.password
is used to launch the agent on the specified host.
- scheduling
- is an SCL list that contains scheduling
information. If no list is specified, the agent is defined to the DOMAIN server
but is not scheduled to run. In this situation, the _runAgent method has to
be invoked to execute the agent.
The scheduling parms list can be specified
to identify times and dates on which the agent should run. The bold items
that are listed below are supported named-items that can be specified in the
list.
Note: Day-of-Week and Month-and-Day scheduling parms
are mutually exclusive. Use one form or the other, but not both.
- Day-of-Week Schedule
-
- RUN_DOW
- the value 1 represents Sunday and 7 represents
Saturday. A single day must be specified by using a single number. Multiple
days must be specified by using comma delimiters (2,4,6 for Monday, Wednesday,
Friday). A range must be specified by using a hyphen delimiter (1-7).
- Month-and-Day Schedule
-
- RUN_MONTH
- the value 1 represents January and 12 represents
December. Single, multiple, and range specifications (similar to RUN_DOW)
are supported.
- RUN_DAY
- values range between 1 and 31 to represent
the day of the month the agent is scheduled to run. For the agent to execute,
the day of the month must be valid.
- Time Schedule
-
- RUN_HOUR
- indicates hour portion of the agent run
launch time (per 24-hour time, 1:00 PM is 13:00).
- RUN_MINUTE
- indicates minute portion of the agent run
launch time.
- NotifQueue
- identifies the name of the queue in which
to send a message when the agent has successfully run. If the queue does not
exist, it will be dynamically created. This queue can then be checked periodically
by querying the queue to see if there is a message. A message TYPE value of
65539 is reserved and indicates that this message was sent as a result of
an agent run completion. The header parameter from the query
can then be evaluated. The header will contain the following named items:
- AGENT_NAME
- identifies the name of the agent that ran.
- AGENT_RUN_COMPLETION_STATUS
- is used to determine whether the agent run
was successful.
- AGENT_RUN_KEY
- is used to retrieve the spool from the run
instance.
- AGENT_RUN_DATETIME
- is the date and time the agent was run.
- DESCRIPTOR
- is a user-specified text description of
the agent.
- notifType
- indicates the form of the agent run completion
notification message. The following values are supported:
- COMPLETE
- indicates that only completion notification
occurs
- FULL
- indicates that along with completion notification,
the run log and listing output spool are included with the notification.
- LOG
- indicates that along with completion notification,
the run log spool is included with the notification.
- LIST
- indicates that along with completion notification,
the listing output spool is included with the notification.
- notifDisp
- indicates whether the run spool is or is
not retained. The following values are supported:
- RETAIN
- indicates that the run spool is retained
after run completion notification. The user must execute the _purgeAgentRunInfo
method to delete the spool.
- PURGE
- indicates that the run spool is deleted
subsequent to notification.
This program sets a schedule list to run on July 4,
at 8:10 p.m.
rc = setnitemn(schedule, 7, -1, "RUN_MONTH");
rc = setnitemn(schedule, 4, -1, "RUN_DAY");
rc = setnitemn(schedule, 20, -1, "RUN_HOUR");
rc = setnitemn(schedule, 10, -1, "RUN_MINUTE");
This program sets a schedule list so that it runs every
Monday at 7:30 a.m.
rc = setnitemn(schedule, 2, -1, "RUN_DOW");
rc = setnitemn(schedule, 7, -1, "RUN_HOUR");
rc = setnitemn(schedule, 30, -1, "RUN_MINUTE");
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.
