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.

Pattern Matching

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

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

Pascal Parameters

FORTRAN Parameters

Return Values

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);
.
.
.

Implementation Specifics

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.

Files

Related Information

List of HCON Programming References in 3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference.

Programming HCON Overview in 3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference.