SEARCH PRESENTATION SPACE (6)

3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference

SEARCH PRESENTATION SPACE (6)

Purpose

Enables your HLLAPI program to examine the host Presentation Space (PS) for the occurrence of a specified string.

Prerequisite Calls

This function requires a prerequisite call to the CONNECT PRESENTATION SPACE (1) function.

Syntax

hllc (func, apistring, len, ret)
int *func;
char *apistring;
int *len;
int *ret;

Supplied Parameters

Supply the following parameters to invoke the SEARCH PRESENTATION SPACE function:

func	Specifies the number of the function called; must be 6 for the SEARCH PRESENTATION SPACE function.
apistring	Specifies the attributes of the API string; contains target data string of the search.
len	Specifies the length of the target data string. This parameter does not apply in EOT mode.
ret	Specifies the position within the host PS where the search is to begin (SRCHFRWD option) or to end (SRCHBKWD option). This parameter is overridden in SRCHALL (default) mode.

Returned Parameters

len

The following codes are valid:

=0	Specifies that the string was not found.
>0	Specifies that the string was found at the indicated host PS position.

ret

The following codes are valid:

0	Specifies that the SEARCH PRESENTATION SPACE function was successful.
1	Specifies that the host PS was not connected.
2	Specifies that an error was made in specifying parameters.
7	Specifies that the host PS position was invalid.
9	Specifies that a system error occurred.
24	Specifies that the search string was not found.

Remarks

The SEARCH PRESENTATION SPACE function normally scans the host PS for the first occurrence of the specified string:

If the string is not located, then the returning length is set to 0.
If the string is found, then the returning length is set to the string's beginning location in the host PS. This location represents a position in the host PS based on the layout where the upper-left corner (row 1, column 1) is position 1.

Four sets of parameter options from the SET SESSION PARAMETERS (9) function are related to this function:

STRLEN/STREOT
EOT=
SRCHALL/SRCHFROM
SRCHFRWD/SRCHBKWD

You can use the SET SESSION PARAMETERS (9) function to specify SRCHBKWD. When this option is in effect, the search function locates the last occurrence of the string.

The SEARCH PRESENTATION SPACE function checks the entire host PS (SRCHALL is the default mode). However, you can use the SET SESSION PARAMETERS (9) function to specify SRCHFROM. In this mode, the PS position parameter specifies 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 host PS. If the target string is not found, the search stops at the end of the PS.
If the SRCHBKWD option is in effect, the search for the designated string begins at the end of the PS 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 PS position parameter.

Use the SRCHFROM option to search for a keyword that may occur more than once in the host PS.

The SEARCH PRESENTATION SPACE function is also useful in determining when the host PS is available. If your HLLAPI application is expecting a specific prompt or message before sending data, the SEARCH PRESENTATION SPACE function allows you to check for a prompt or message before continuing.

DBCS Remarks

If the specified position where a forward search is to begin is the second byte of a DBCS character, the search begins from the next position. If the last character of the target data string is the first byte of a DBCS character, it is not included.

SO/SI in the presentation space is ignored while searching. Two-byte control characters to be searched must be enclosed between SO(X'OE') and SI(X'OF').

Related Information

CONNECT PRESENTATION SPACE (1) function and SET SESSION PARAMETERS (9) function.

[ Previous | Next | Contents | Search ]