API Exec Event Response Discussion
Running Vantage Programs from User Programs
The API Exec event response enables execution of a user written program or script upon the detection of an event. Also included is the ability to execute Message event and Message with Reply event responses from a user program.
API Exec Event Response Discussion
The API Exec event provides the capability to execute a user-supplied program or script upon event detection. The user program or script is executed on the Vantage workstation.
To be executed by Vantage user programs must exist on the Vantage workstation in the /opt/vantage/apibin directory, must belong to the group v_mgr and have file permissions of 755.
The Vantage API Exec event response makes 13 arguments or variables available to the user program at execution time. How the program references these arguments is dependent on the language in which it is written. For instance, a C program would typically refer to them as argv[0] through argv[12], while a shell script would refer to the same variables as $0 through $9 and the shift command. C language notation will be used in this discussion.
argv[0] or $0 - The name of the user-supplied program to be executed.
argv[1] or $1 - The name of the resource that generated the event.
argv[2] or $2 - The event string as defined in the "Search For Event String" control of the Event Definition dialog.
argv[3] or $3 - The line of console output in which the event was detected.
argv[4] or $4 through argv[12] or $9 (shift) - White space separated variables following the program name.
The Vantage API Exec event response passes three arguments to the user program as argv[1], argv[2] and argv[3]. Though the user program is not required to use these values, the arguments are provided automatically and are available for use if needed.
Up to nine additional user-defined arguments can be passed as argv[4] through argv[12]. These user-defined arguments are entered in the API Exec event definition dialog's "Program to Execute" control following the program name. The first argument following the program name is argv[4], the second argv[5], etc. The program/script name and all arguments must be delimited by a single space.
Running Vantage Programs from User Programs
User written programs can execute the Vantage programs that generate the Message event and Message with Reply dialogs. Program names are /opt/vantage/bin/xmessage and /opt/vantage/bin/xmsg_reply respectively. Both programs require at least three arguments: argv[1], argv[2] and argv[3]. Additional arguments can be passed as follows: argv[4] host_name, argv[5] display_name, argv[6] foreground_color, and argv[7] background_color. An @ symbol preceding the foreground and background indicates black text.
The dialog above was generated by executing the following command on the Vantage workstation:
/opt/vantage/bin/xmessage "This is argv[1]" "This is argv[2] It is ... etc." "This is argv[3] and is the line ... etc" predator predator:0.0 @snow @snow &
The following examples show more of the capabilities of executing Message event and Message with Reply programs from a user script.
/opt/vantage/bin/xmessage "$1" "Reports are ready to print" "$3" &
The command above would display a Message event dialog on the Vantage workstation passing the default value in $1, the text "Reports are ready to print" as $2 and the default value in $3.
The default display for message dialogs is the Vantage workstation. It is possible to display these dialogs on a different X display by specifying additional arguments. To accomplish this you must supply a valid host name as $4, an X display name as $5 and optionally two valid color arguments. An @ symbol preceding the color name denotes black text. The following example shows how to direct a message to another X display.
/opt/vantage/bin/xmsg_reply "$1" "Your job has aborted" myhost mydisp:0.0 "sky blue" "@snow" &
The example above would execute the Message with Reply program, passing the default value in $1. It would pass the text "Your job has aborted!" as $2 and pass the default value in $3.
The next variable, $4, is the host name and $5 is the X display name on which the message is to appear. "sky blue" and "@snow" are $6 and $7 respectively and are the foreground and background colors of the Message with Reply. Variables $4 and $5 are required to direct the message dialog to a display other than the Vantage workstation.
If the message dialog should be displayed on the host and X display set by the transfer_control program, substitute the words DEFAULT_HOST and DEFAULT_DISPLAY for $4 and $5 respectively.
NOTE: When the Reply button is clicked on a Message with Reply the dialog will attempt to send the contents of the "Command to Send" control to the resource named in $1 (argv[1]). Always pass $1 to xmsg_reply to ensure that the reply is sent to the intended destination.
If the Message event or Message with Reply programs are not run in the background the user program will not continue until the message dialog completes. To execute the programs in the background put a & character at the end of the command line.
vanapi01
The program vanapi01 is supplied to enable the execution of a command to a Vantage-managed resource or Group of resources from a user program or script. The vanapi01 program is located in the /opt/vantage/apibin directory and expects two arguments.
usage: vanapi01 [{resource name, group name or $1}] [{command string or token}]
The first argument can be the value in argv[1] $1 or a hard coded resource or group name. The second argument can be either a hard coded command or a combination of a hard coded command and user-defined argv[] values. Shown below are sample uses of the vanapi01 program.
/opt/vantage/apibin/vanapi01 "$1" "rm /tmp/junk/myfile"
The example above would send the command "rm /tmp/junk/myfile" to the resource name in $1.
/opt/vantage/apibin/vanapi01 mysys "run $4.rcvr.acct"
The example above would substitute the value in $4 and execute a command on the resource/group "mysys". If, for example, the entry in the "Program to Execute" control following the program name ($4) is rcvr001p, the API Exec event would execute the command "run rcvr001p.rcvr.acct" on the resource or group "mysys".
vanapi02
The program vanapi02 is provided to enable the execution of a command file to a Vantage-managed resource or Group of resources from a user program or script. The vanapi02 program is located in the /opt/vantage/apibin directory and expects two arguments.
usage: vanapi02 [{resource/group name or $1}] [command_file_name]
The first argument can be the value in argv[1] or it can be a hard coded resource or group name. The second argument must be the command file name. The command file must exist in the /opt/vantage/command_files directory.
The figure below is the API Exec event Definition dialog.
Refer to Using Vantage Dialogs to learn about Vantage dialogs. Each control on the dialog is explained in the text that follows.
Program to Execute:
This control is used to specify the name of the user-supplied program and up to 9 additional, optional arguments to be passed to the program. The user program can be either compiled code or a shell script. Click the control, type the program name and up to 9 arguments.
Include Log File Information in $4 and $5:
There are 2 ways for the API program to get information from Vantage. If this box is checked the program will get $4 as the log file name and $5 as the position in the log file where the event can be found. The parameters in the 'Program to Execute' control will follow in $6 through $9 (shift).
Click OK when all controls are as desired. Click the Add button on the Event Definition dialog to add the event.
You must Distribute Events when finished adding or modifying an event for the new event to be detected.
See also Operating Vantage
