Project: Monitor specified events and list them in a text dump file, along with the time and date the action took place. For this example, the events to be monitored are disconnections, “System Error” messages sent from the host, and idle periods of fifteen minutes or more.
Algorithm:The conditions to be monitored are defined up front, along with the associated actions when the condition becomes true. This definition of events to be monitored is done with WHEN commands. After this header block to define the conditions to be monitored, the script pauses at a WAIT command. This keeps the script running but inactive until any of the WHEN conditions become true. The WHEN commands are only actively checked when the script is in a wait state.
WHEN commands are session specific, so the addition of more WHEN commands could extend this example to cover multiple concurrent sessions. The WHEN commands use an optional window handle parameter to specify which session is being monitored, so it is necessary for the session to be open prior to issuing the WHEN commands for that session. A simple text table is used for data output. See the Data Tables example for further discussion on the use of table.
Relevant Commands and Functions:
WHEN DISCONNECT — activates when the connection is terminated
WHEN STRING — activates when the specified string is received
WHEN QUIET — activates after time period elapses without character transmission
WHEN CANCEL — cancels the specified WHEN commands
TIME( ) — current or derived time
DATE( ) — current or derived date
TABLE DEFINE — Define a table to be used for dumping data and writing to a file
@R — Record buffers used for reading/writing to tables
RECORD WRITE — Writes the contents of the record buffer to a table
TABLE CLOSE — Closes the specified table
SHOW — Display each script command as it is executed.
WHEN INPUT — activates when a keystroke-generated character is sent
WHEN ERROR — activates when an execution error is encountered
WHEN TIMER — activates when a specified time period has elapsed
WHEN WINDOW — filters window messages to child windows
A Brief Example
TABLE DEFINE 0 TEXT "Logfile.txt"
CONNECT "Session1.Ses" WINDOW %WindowHandle
WHEN DISCONNECT WINDOW %WindowHandle
@R0 = "Disconnected … " | TIME() | " " | DATE()
RECORD WRITE 0
TABLE CLOSE 0
WHEN STRING "System Error" WINDOW %WindowHandle
@R0 = "System Error … " | TIME() | " " | DATE()
RECORD WRITE 0
WHEN QUIET "00:15:00" WINDOW %WindowHandle
@R0 = "Idle for 15 minutes … " | TIME() | " " | DATE()
RECORD WRITE 0
After the session is connected and the log file defined, three WHEN commands are issued to monitor the three conditions on this session. Each has a command block of code to be executed when the command is activated. The script continues to the WAIT RESUME command, which is used as an arbitrary way to keep the script in execution and at a wait state so the conditions specified in the WHEN commands will be monitored.
Event triggers and WHEN commands are more commonly used to react to host responses and user input than to record a static log file. A common case is handling error messages that may occur at irregular times.
Since DCS is a multisession product, it is wise to use the optional window handle parameters to specify which session to monitor.
Several of the WHEN commands include an Index argument which is used to track multiple concurrent WHEN commands of the same type. See the Script Reference for details of limitations on the total number of concurrent WHEN commands, which varies by product. The WHEN CANCEL command is used to cancel unnecessary WHEN commands, and free resources for reuse.