Share this page
TE_wait_text
| Example: TE_wait_text | Synchronization Functions |
Waits for a text string to appear in a designated location.
int TE_wait_text( const char *pattern, int timeout [, int col1, int row1, int col2, int row2, int *retcol, int *retrow, char *match ] );
Inputs
| pattern | The string to wait for. The string may include a Regular Expressions. Indicate the start of a regular expression with an exclamation point (!). If this string is empty, the function either returns immediately if no text is found, or it waits for the timeout if it finds any text. |
| timeout | Determines the amount of time, in seconds, to wait for the string to appear. |
| col1, row1 | [Optional] The column and row coordinates of the top left corner of the area at which to wait for the string. |
| col2, row2 | [Optional] The column and row coordinates of the lower right corner of the area at which to wait for the string. |
Outputs
| retcol, retrow | [Optional] The column and row coordinates at which the string actually appeared. |
| match | [Optional] The matched string. The string is null-terminated. Make sure you allocate a large enough buffer to accommodate the match. |
Besides the pattern and timeout parameters, all the other parameters are optional. Alternatively, for any of the output parameters, you can specify NULL if you do not need the value.
The TE_wait_text function waits for text matching the pattern within the rectangle defined by col1, row1, col2, row2. Text that matches the pattern will be returned to match, and the actual row and column position will be returned to retcol and retrow. If the pattern does not appear before the timeout expires, the function returns an error code. If the pattern already appears on the screen, the function returns immediately.
If the pattern does appear, then the function waits for the client application to be silent for the interval defined by the TE_SILENT_SEC and TE_SILENT_MILLI system variables. This in effect allows the terminal to become stable and emulates a human operator. If the terminal does not become silent within the interval defined by TE_SILENT_TIMEOUT, script execution continues. The function returns 0 for success, but sets the TE_errno variable to indicate that the terminal was not silent after the text appeared. For more information on the system variables, see TE_getvar and TE_setvar.
The terminal emulator screen is measured in characters. The character with position 1,1 is in the top left corner of the screen. If you specify illegal values for col2 or row2 (meaning that the values are smaller than those specified for col1, row1), the function assumes the last row and column on the screen. For example, to indicate that the function should search for text anywhere in the first row, without knowing the precise length of the row, you can specify
TE_wait_text ("!.*complete", 20, 1,1,-1,1, retcol, retrow, match);
Since the col2 parameter is set to -1, the function will search for text until the last column in the first line.
Return Values
This function returns 0 if it succeeds, and a negative error code if it fails. It also sets the global variable TE_errno.
Parameterization
The following argument can be parameterized using standard parameterization: pattern
