g32_get_data Function

Purpose

Obtains current specified display data from the presentation space.

Libraries

HCON Library

C (libg3270.a)

Pascal (libg3270p.a)

FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_get_data ( as, buffer)

struct g32_api *as;

char *buffer;

Pascal Syntax

function g32data (var as : g32_api; buffer : integer) : integer; external;

FORTRAN Syntax

EXTERNAL G32GETDATA

INTEGER AS(9), G32GETDATA

CHARACTER *XX Buffer

RC = G32GETDATA(AS, Buffer)

Description

The g32_get_data function obtains current display data from the presentation space. The transfer continues until either the transfer length is exhausted or the starting point is reached. If the transfer length is greater than the presentation space, then the g32_get_data function only reads data that equals one presentation space and leaves the rest of the buffer unchanged.

The g32_get_data function can only be used in API/3270 session mode.

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

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

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

In a double-byte character set (DBCS) environment, the g32_get_data function only obtains SBCS data from the presentation space even if Kanji or Katakana characters are displayed on the screen. The DBCS data are not available.

C Parameters

Item	Description
as	Specifies a pointer to the g32_api structure containing the row (row) and column (column) address where the data begins, and the length (length) of data to return. Status information is also returned in this structure.
buffer	Specifies a pointer to a buffer where the data is placed.

Pascal Parameters

Item	Description
as	Specifies the g32_api structure.
buffer	Specifies an address of a character-packed array. The array must be the same length or greater than the length field in the g32_api structure. Note: The address of a packed array can be obtained by using the addr() system call: `buffer := addr (<message array name> [1]).`

FORTRAN Parameters

Item	Description
AS	Specifies the g32_api equivalent structure as an array of integers.
buffer	Specifies the character array that receives the retrieved data. The array must be the same length or greater than the length field in the g32_api structure. Note: If the size of the buffer is smaller than AS(LENGTH), a memory fault may occur.

Return Values

Item	Description
0	Indicates successful completion.
-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

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

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

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