|
The Search Field function examines a field within the connected host presentation space for the occurrence of a specified string. If the target string is found, this function returns the decimal position of the string numbered from the beginning of the host presentation space. (For example, in a 24-row by 80-column presentation space, the row 1, column 1 position is numbered 1 and the row 5, column 1 position is numbered 321.)
This function can be used to search either protected or unprotected fields, but only in a field-formatted host presentation space.
Note:
If the field at the end of the host presentation space wraps, wrapping occurs when the end of the presentation space is reached.
Prerequisite Calls
Connect Presentation Space (1)
Call Parameters
|
Standard Interface
|
Enhanced Interface
|
Function Number
|
Must be 30.
|
|
Data String
|
Target string for search.
|
|
Length
|
Length of the target data string. Overridden in EOT mode.
|
|
PS Position
|
Identifies the target field. For SRCHALL, this can be the PS position of any byte within the target field. For SRCHFROM, it is the beginning point of the search for SRCHFRWD or the ending point of the search for SRCHBKWD. See remark 3.
|
|
Return Parameters
This function returns a length and a return code.
Length
The following codes are defined:
Length
|
Explanation
|
= 0
|
The string was not found.
|
> 0
|
The string was found at the indicated host presentation space position.
|
Return Code
The following codes are defined:
Return Code
|
Explanation
|
0
|
The Search Field function was successful.
|
1
|
Your program is not connected to a host session.
|
2
|
Parameter error. Either the string length was zero, or EOT mode was specified but no EOT character was found in calling data string.
|
7
|
The host presentation space position is not valid.
|
9
|
A system error was encountered.
|
24
|
The search string was not found, or the host presentation space was unformatted.
|
Remarks
| 1. | Four sets of parameters under the Set Session Parameters (9) function are related to this function. They are the SRCHALL/SRCHFROM, STRLEN/STREOT, SRCHFRWD/SRCHBKWD, and the EOT=c session options. |
| 2. | You can use the Set Session Parameters (9) function to determine whether your searches proceed forward (SRCHFRWD) or backward (SRCHBKWD) in a field. |
| 3. | The Search Field function normally checks the entire field (SRCHALL default mode). However, you can use the function 9 to specify SRCHFROM. In this mode, the calling PS position parameter does more than identify the target field. It also provides a beginning or ending point for the search. |
| • | If the SRCHFRWD option is in effect, the search for the designated string begins at the specified PS position and proceeds toward the end of the field. |
| • | If the SRCHBKWD option is in effect, the search for the designated string begins at the end of the field and proceeds backward toward the specified PS position. If the target string is not found, the search ends at the PS position specified in the calling PS position parameter. |
| 4. | DBCS Only: If the start position of the specified search function is the second byte in a double-byte character, the search is started from the next character for SRCHFRWD and from the character for SRCHBKWD. If the last character of the specified string is the first byte of a double-byte character, the character is not searched for. |
The search ignores a pair of SO and SI in the presentation space. When you search a double-byte control character, put SO (X'0E') before the character and SI (X'0F') after it. For example, X'0E000C0F' in the data string is treated as a double-byte character FF (X'000C').
|