SCAN
To perform all three functions, you must use the parameters SESSION, ROW, and COLUMN. The default for ROW and COLUMN is 1. There is no default for SESSION.
For more information about performing these functions and which additional parameters you must use, see Using the parameters.
See Interacting-with-VTAM-applications-with-OSPI for more information about using this command and OSPI.
Command | Parameters |
|---|---|
SCAN | [ROW(startingRow)] [COL(startingColumn)] [TEXT(targetName)] VARIABLE(variableName) | [POSITION] [LENGTH(n)] SESSION(sessionID) [CASE | NOCASE] [TRIM | NOTRIM] |
The following table describes the parameters:
Parameter | Function | Notes |
|---|---|---|
ROW | Row in which to begin the scan | Numeric value is in the range of one through the maximum number of rows supported by the emulated terminal. Default is 1. |
COL | Column in which to begin the scan | Numeric value is in the range of 1-80. Default is 1. |
TEXT | Text to scan for | Maximum length is 255 characters TEXT and VARIABLE cannot be coded together on the same statement. |
VARIABLE | Name of the variable to receive the data | Do not specify a leading ampersand (&). Either VAR or POSITION or both must be specified. TEXT and VARIABLE cannot be coded together on the same statement. |
LENGTH | Number of characters to place into the target variable | This parameter is required with VAR. Numeric value is in the range of 1-255. |
SESSION | Session identifier of the OSPI session that should be accessed | This parameter is provided by the LOGON command. |
CASE | Performs a case-sensitive scan for TEXT | Default is NOCASE. |
NOCASE | Performs a non-case-sensitive scan for TEXT | n/a |
TRIM | All leading and trailing blanks, nulls, and control characters are to be removed from the returned variable | Default is NOTRIM. |
NOTRIM | Data is placed into the target variable exactly as found | n/a |
POSITION | Positions the cursor automatically in the next input field following the indicated character string | Either VAR or POSITION or both must be specified. |
Using the parameters
This section describes which parameter you must use to perform certain functions with IMFEXEC SCAN.
Searching for string and positioning the cursor
The following additional parameters must be used with IMFEXEC SCAN when you want to either search for a string or position the cursor:
- TEXT: indicates a request to find a text string.
- The parameters VARIABLE, LENGTH, and TRIM do not apply when searching for text (and can, in some cases, cause syntax errors). Do not specify any of these parameters when you use TEXT.
- CASE: indicates whether to perform a case-sensitive search for TEXT keyword.
- POSITION: indicates whether or not to position the cursor. If POSITION is not specified, the position will not change.
Retrieving data into variables
The following additional parameters must be used with IMFEXEC SCAN when you want to retrieve data into variables:
- VARIABLE: indicates a request to retrieve data
- The parameters TEXT, CASE, and POSITION do not apply when retrieving data (and can, in some cases, cause syntax errors). Do not specify any of these parameters when you use VARIABLE.
- LENGTH: required to retrieve data
- TRIM: indicates whether or not to remove trailing blanks, nulls, and control characters from the returned variable
Condition codes are listed in the following table:
Value | Description |
|---|---|
0 | Command was executed successfully; text was found. |
4 | Text was not found. |
8 | One of the following situations occurred:
|
Example 1
"IMFEXEC SCAN TEXT(USERID) VAR(MYUSER) LENGTH(25) TRIM NOCASE",
"SESSION("TSOSESS")"
CLIST example:
SESSION(&TSOSESS)
This example command scans the screen beginning at the upper lefthand corner for the character string, USERID. The scan is performed against the session designated by the TSOSESS variable.
The scan is not case-sensitive. The 25 characters following the string are placed into the variable MYUSER after trailing and leading blanks have been removed.
Example 2
"IMFEXEC SCAN ROW(10) COL(10) POSITION TEXT(A) LENGTH(1)",
"SESSION("OSISESS")"
CLIST example:
This example places the cursor in the input field after row 10, column 10, for the virtual screen buffer with the logical unit specified by the variable OSISESS. This command is equivalent to placing the cursor on row 10, column 10, and pressing the Tab key.