Programming with Reflection

image\rwnprg32.gif DefineEvent method

 

Syntax object.DefineEvent Event, EventType, Duration, String, Row, Column, Key

 

Description

Defines an event. You can check for the occurrence of a defined event with CheckEvent or CheckEventNumber. You can pause a procedure to wait for a defined event with WaitEvent or WaitEventNumber. You can be notified when the event occurs by using a DefinedEvent event handler created in the code module for the Reflection Session object (ThisSession)..

Defining an event doesn't prevent processing of subsequent commands.

Once defined, an event remains defined as long as your Reflection session lasts and may affect subsequent macros that check for events. You can remove an individual event definition using RemoveEvent, and it is a good idea to use this method after you have checked for an event. You can use ClearEvents to remove all defined events.

Arguments 

Event Argument type: Integer
Specifies a number identifying this event. Do not use the same number to define another event during the same Reflection session. Do not use 0 as the value for this argument.

 Use rcNextEvent to have Reflection automatically assign an event number. (The EventDefined property returns the number of the most recently defined event.)

EventType Argument type: Enumeration
The event to wait for. The values are:

 rcSilence

 Defines an event as the absence of activity (such as user input or data from the host) for the specified duration. Duration is the only other argument that is meaningful with rcSilence. Use an empty string ("") as the value for String, and 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. For example, this statement defines an event of two minutes of silence:

.DefineEvent 1, rcSilence, "2:00", "", 1, 1, 1

 rcKbdEnabled

 Defines an event as the keyboard being unlocked for the specified duration. Duration is the only other argument that is meaningful with rcKbdEnabled. Use an empty string ("") as the value for String, and use 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. For example, this statement defines an event of the keyboard unlocked for 10 seconds:

.DefineEvent 1, rcKbdEnabled, "10", "", 1, 1, 1

 rcEvConnected

 Defines an event as a host connection. Use an empty string ("") as the value for the Duration and String arguments, and use 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. For example:

.DefineEvent 1, rcEvConnected, "", "", 1, 1, 1

 rcEvDisconnected

 Defines an event as the lack of a host connection. Use an empty string ("") as the value for the Duration and String arguments, and use 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. For example:

.DefineEvent 1, rcEvDisconnected, "", "", 1, 1, 1

 rcEnterField

 Defines an event as a cursor entering the specified field. For the event to have occurred, the cursor must enter the field which contains the specified row and column coordinates (as defined by the Row and Column arguments). Use an empty string ("") as the value for the Duration and String arguments, and 1 as the value for Key; these arguments are not relevant for type of this event. For example, the following event occurs when the cursor enters a field that includes row 20, column 7:

.DefineEvent 1, rcEnterField, "", "", 20, 7, 1

 rcExitField

 Defines an event as the cursor exiting the specified field. For the event to have occurred, the cursor must exit the field which includes the specified row and column coordinates. Use an empty string ("") as the value for the Duration and String arguments, and 1 as the value for Key; these arguments are not relevant for this type of event. For example, the following event occurs when the cursor exits a field that includes row 20, column 7:

.DefineEvent 1, rcExitField, "", "", 20, 7, 1

 rcEnterPos

 Defines an event as the positioning of the cursor at the specified screen coordinates (row and column). For the event to occur, the cursor must be at the specified coordinates. Use an empty string ("") as the value for the Duration and String arguments, and 1 as the value for Key; these arguments are not relevant for this type of event. To specify any row or column, use the value rcAnyRow or rcAnyCol, but not both at the same time. The following event occurs when the cursor is located at row 20, column 7:

.DefineEvent 1, rcEnterPos, "", "", 20, 7, 1

 rcExitPos

 Defines an event as the positioning of the cursor at any location on the screen other than specified coordinates (row and column). For the event to occur, the cursor must not be at the specified coordinates. Use an empty string ("") as the value for the Duration and String arguments, and 1 as the value for Key; these arguments are not relevant for this type of event. To specify any row or column, use the value rcAnyRow or rcAnyCol, but not both at the same time. The following event occurs when the cursor is not located at row 20, column 7:

.DefineEvent 1, rcExitPos, "", "", 20, 7, 1

 rcCommString

 Defines an event as either the expiration of the specified period of time or the reception of the specified string from the host. Use the String argument to specify the string. Use an empty string ("") as the value for the Duration argument and 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. Use rcCommString only if you are connecting to your IBM host through a gateway (such as UNIX) that uses streaming mode rather than block mode. (In streaming mode, incoming characters appear on screen in sequence, and existing lines of text scroll out of sight as new lines appear. In block mode, you see complete screen displays, beginning with the logon display screen.) If you are connecting directly to an IBM host, use rcDisplayString.

 rcDisplayString

 Defines an event as the specified string appearing at the specified row and column coordinates in the terminal window. Use the String argument to specify the string. Use an empty string ("") as the value for the Duration argument, and 1 as the value for Key; these arguments are not relevant for this type of event. Matches are case-sensitive. For example, the following statement defines an event that occurs if the word System is located anywhere in the second row of the screen:

.DefineEvent 1, rcDisplayString, "", "System", 2, rcAnyCol, 1

 rcTimeOfDay

 Defines an event as the current time matching the specified clock time. Use the String argument to specify the time of day in HH:MM:SS format using a 24-hour clock (00:00:00-23:59:59). Use an empty string ("") as the value for Duration, and use 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. For example, this statement defines an event that occurs at 1:30 PM:

.DefineEvent 1, rcTimeOfDay, "", "13:30:00", 1, 1, 1

 rcTime

 Defines an event as the passage of the specified amount of time from when the event is defined, in HH:MM:SS format using a 24-hour clock (00:00:00-23:59:59). Use the String argument to specify the interval of time. Use an empty string ("") as the value for the Duration argument, and a 1 as the value for Row, Column, and Key; these arguments are not relevant for this type of event. For example, the event defined here occurs four seconds after the statement is executed:

.DefineEvent 1, rcTime, "", "4", 1, 1, 1

 rcTerminalKeystroke

 Defines an event as the transmission of the specified terminal key to the host. The Key argument defines the host function. Use an empty string ("") as the value for the Duration and String arguments, and a 1 as the value for Row and Column; these arguments are not relevant for this type of event. For example, the event defined here occurs when the user presses the Enter key:

.DefineEvent 1, rcTerminalKeystroke, "", "", 1, 1, rcIBMEnterKey

 rcNewHostScreen

 Defines an event as a change in the currently displayed screen. Use an empty string ("") for the Duration and String arguments, and 1 for Row, Column, and Key; these arguments are not relevant for this type of event. For example:

.DefineEvent 1, rcNewHostScreen, "", "", 1, 1, 1

 rcPrinterOpened

 Defines an event when the printer is opened and the print job has started. Use an empty string ("") as the value of String, and 1 as the value for Row and Column; these arguments are not relevant for this type of event.

 rcPrinterStartOfPage

 Defines an event when a print page starts. Use an empty string ("") as the value of String, and 1 as the value for Row and Column; these arguments are not relevant for this type of event.

 rcPrinterEndOfPage

 Defines an event when a print page ends. Use an empty string ("") as the value of String, and 1 as the value for Row and Column; these arguments are not relevant for this type of event.

 rcBeforePrinterClosed

 Defines an event just before a printer is closed and the print job ends. Use an empty string ("") as the value of String, and 1 as the value for Row and Column; these arguments are not relevant for this type of event.

 rcPrinterClosed

 Defines an event when the printer (or file) is closed and the print job is done. Use an empty string ("") as the value of String, and 1 as the value for Row and Column; these arguments are not relevant for this type of event.

 rcPrinterString

 Defines an event that occurs when the string specified in the String argument is sent to the printer. Matches are case-sensitive. Use a 1 as the value for Row and Column; these arguments are not relevant for this type of event. For example, the following statement defines an event that occurs if the word "System" is being sent to the printer:

        .DefineEvent 1, rcPrinterString, "", "System", 1, 1, 1

 rcPrinterStringReplace

 Defines an event that you can use to intercept the printing of one string and replace it with a different string. Matches are case-sensitive. Use the String argument to specify both the search string and the replacement string. Use the Column argument to specify where within the String argument the replacement string begins. Use a 1 as the value for Row; this argument is not relevant for this type of event. If the value of Column is greater than the length of the String, no string replacement will take place. For example, the following statement defines an event that replaces the word "System" with "IBM System."

        .DefineEvent 1, rcPrinterStringReplace, "", "SystemIBM System", 1, 7, 1

 Use a 1 as the value for Column, if you want to filter out all occurrences of String (replace the String with null string).

 rcPrinterStatusString

 Defines an event that occurs when the string specified in the String argument is sent to the printer status message box. (Click to see a list of 3287 printing messages or a list of 3812 printing messages.) Use a 1 as the value for Row and Column; these arguments are not relevant for this type of event. Matches are case-sensitive. For example, the following statement defines an event that occurs if the string "Printer Error" is being sent to the status box of the printer:

        .DefineEvent 1, rcPrinterStatusString, "", "Printer Error", 1, 1, 1

Duration Argument type: String
Specifies an interval of time in HH:MM:SS format. The specified event must last this long to satisfy the definition. This argument is only relevant when the value you use for the EventType argument requires a duration—that is, when EventType is rcSilence or rcKbdEnabled. The interval begins when the DefineEvent method is executed. If an event is reset using ResetEvent, WaitEvent, or WaitEventNumber, a new interval begins at that time.

String Argument type: String
Specifies the string that defines string-oriented events. This argument is only relevant when the value you use for EventType requires a string—that is, when EventType is rcCommString, rcDisplayString, rcTimeOfDay, or rcTime.

Row Argument type: Integer or Enumeration
Specifies the row location for screen events. Use a row number to specify a particular row, or use rcMouseRow to specify the row where the mouse was last clicked. When EventType is rcDisplayString, you can use rcAnyRow to indicate that the event can occur at any row location. This argument is relevant when EventType is rcEnterField, rcExitField, rcEnterPos, rcExitPos, or rcDisplayString.

Column Argument type: Integer or Enumeration
Specifies the column location for screen events. Use a column number to specify a particular column, or use rcMouseCol to specify the column where the mouse was last clicked. When EventType is rcDisplayString, you can use rcAnyCol to indicate that the event can occur at any column location. This argument is relevant when EventType is rcEnterField, rcExitField, rcEnterPos, rcExitPos, or rcDisplayString.

Key Argument type: Enumeration
The terminal keystroke used when EventType is rcTerminalKeystroke. You can specify a particular terminal key (Click here to see a list of terminal keys for 3270 terminals, or here to see a list of terminal keys for 5250 terminals), or use rcAnyTerminalKey to check for any terminal keystroke.

 

image\jump.gif Example

image\jump.gif Keyword Index

image\popup.gif Related Topics

image\popup.gif Reflection products that use this command