g32_search Function

Purpose

Searches for a character pattern in a presentation space.

Libraries

HCON Library

C (libg3270.a)

Pascal (libg3270p.a)

FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_search ( as, pattern)

struct g32_api *as;

char *pattern;

Pascal Syntax

function g32srch(var as : g32_api; pattern : stringptr) : integer; external;

FORTRAN Syntax

EXTERNAL G32SEARCH

INTEGER AS(9), G32SEARCH

CHARACTER *XX PATTERN

RC = G32SEARCH(AS, PATTERN)

Description

The g32_search function searches for the specified byte pattern in the presentation space associated with the application.

Note: The g32_search function can only be used in API/3270 mode.

The search is performed from the row and column given in the g32_api structure to the end of the presentation space. Note that the row and column positions start at 1 (one) and not 0. If you start at 0 for row and column, an invalid position error will result.

The g32_search function is part of the Host Connection Program (HCON).

The g32_search function requires one or more adapters used to connect to a host.

In a DBCS environment, the g32_search function only searches the presentation space for an SBCS character pattern. This function does not support Katakana or DBCS characters.

Pattern Matching

In any given search pattern, the following characters have special meaning:

Character	Description
?	The question mark is the arbitrary character, matching any one character.
*	The asterisk is the wildcard character, matching any sequence of zero or more characters.
\	The backslash is the escape character meaning the next character is to be interpreted literally.

Note: The pattern cannot contain two consecutive wildcard characters.

Pattern Matching Example

The string AB?DE matches any of ABCDE, AB9DE, ABxDE, but does not match ABCD, ABCCDE, or ABDE.

The string AB*DE matches any of ABCDE, AB9DE, ABCCDE, ABDE, but does not match ABCD, ABCDF, or ABC.

Pattern Matching in C and Pascal

If the pattern needs to contain either a question mark or an asterisk as a literal character, these symbols must be preceded by two escape characters (\\? or \\*). For example, to search for the string, How are you today?, the pattern might be:

How are you today \\?

The backslash can be used as a literal character by specifying four backslash characters (\\\\) in the pattern. For example, to search for the string, We found the \., the pattern might be:

We found the \\\\.

Pattern Matching in FORTRAN

If the pattern needs to contain either a question mark or an asterisk as a literal character, these symbols must be preceded by one escape character (\? or \*). For example, to search for the string, How are you today?, the pattern might be:

How are you today\?

The backslash can be used as a literal character by specifying two backslash characters (\\) in the pattern. For example, to search for the string, We found the \., the pattern might be:

We found the \\.

HCON application programs using the Pascal language interface must include and link both the C and Pascal libraries. Application programs using the FORTRAN language for the HCON API must include and link both the C and FORTRAN libraries.

C Parameters

Item	Description
as	Specifies a pointer to a g32_api structure. It also contains the row and column where the search should begin. Status information is returned in this structure.
pattern	Specifies a pointer to a byte pattern, which is searched for in the presentation space.

Pascal Parameters

Item	Description
as	Specifies the g32_api structure.
pattern	Specifies a pointer to a string containing the pattern to search for in the presentation space. The string must be at least as long as the length indicated in the g32_api structure.

FORTRAN Parameters

Item	Description
AS	Specifies a g32_api equivalent structure as an array of integers.
PATTERN	Specifies a string that is searched for in the presentation space.

Return Values

Item	Description
0	Indicates successful completion. The corresponding `row` field of the as structure is the row position of the beginning of the matched string. The corresponding `column` field of the as structure is the column position of the beginning of the matched string. The corresponding `length` field of the as structure is the length of the matched string.
-1	Indicates an error has occurred. The `errcode` field in the g32_api structure is set to the error code identifying the error. The `xerrinfo` field can be set to give more information about the error.

Examples

Note: The following example is missing the required g32_open and g32_alloc functions which are necessary for every HCON Workstation API program.

The following example fragment illustrates the use of the g32_search function in an api_3270 mode program in C language:

#include <g32_api.h>             /* API include file */
#include <g32_keys.h>
main()
{
struct g32_api *as;              /* g32 structure */
char *buffer;                    /* pointer to char string */
int return;                      /* return code */
char *malloc();                  /* C memory allocation
                                    function */
.
.
.
return = g32_notify(as,1);       /* Turn notification on */
buffer = malloc(10);
return = g32_get_cursor(as);      /* get location of cursor */
printf (" The cursor position is row: %d col: %d/n", 
   as -> row, as -> column);
 
/* Get data from host starting at the current row and column */
as -> length = 10;              /* length of a pattern on host */
return = g32_get_data(as,buffer); /* get data from host */
printf("The data returned is <%s>\n",buffer);
 
/* Try to search for a particular pattern on host */
as ->row =1;                     /* row to start search */
as ->column =1;                  /* column to start search */
return = g32_search(as,"PATTERN");
/*Send a clear key to the host */
return = g32_send_keys(as,CLEAR);
/* Turn notification off */
return = g32_notify(as,0);
.
.
.