g32_read Function

AIX Version 4.3 Communications Technical Reference, Volume 1

g32_read Function

Purpose

Receives a message from a host application.

Libraries

HCON Library

C (libg3270.a)

Pascal (libg3270p.a)

FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_read (as, msgbuf, msglen)

struct g32_api *as;

char **msgbuf;

int *msglen;

Pascal Syntax

function g32read (var as : g32_api;
  var buffer : stringptr;
  var msglen : integer) : integer; external;

FORTRAN Syntax

EXTERNAL G32READ

INTEGER AS(9), BUFLEN, G32READ

CHARACTER *XX MSGBUF

RC= G32READ (AS, MSGBUF, BUFLEN)

Description

The g32_read function receives a message from a host application. The g32_read function may only be used by those applications having API/API or API/API_T mode specified with the g32_alloc function.

In C or Pascal, a buffer is obtained, a pointer to the buffer is saved, and the message from the host is read into the buffer. The length of the message and the address of the buffer are returned to the user application.
In FORTRAN, the calling procedure must pass a buffer large enough for the incoming message. The BUFLEN parameter must be the actual size of the buffer. The G32READ function uses the BUFLEN parameter as the upper array bound. Therefore, any messages larger than BUFLEN are truncated to fit the buffer.

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

as	Specifies a pointer to a g32_api structure.
msgbuf	Specifies a pointer to a buffer where a message from the host is placed. The API obtains space for this buffer by using the malloc library subroutine, and the user is responsible for releasing it by issuing a free call after the g32_read function.
msglen	Specifies a pointer to an integer where the length, in bytes, of the msgbuf parameter is placed. The message length must be greater than 0 but less than or equal to the maximum I/O buffer size parameter specified in the HCON session profile.

Pascal Parameters

as	Specifies the g32_api structure.
buffer	Specifies a stringptr structure. The API obtains space for this buffer by using the malloc C library subroutine, and the user is responsible for releasing it by issuing a dispose subroutine after the g32_read function.
msglen	Specifies an integer where the number of bytes read is placed. The message length must be greater than 0 (zero) but less than or equal to the maximum I/O buffer size parameter specified in the HCON session profile.

FORTRAN Parameters

AS	Specifies the g32_api equivalent structure.
BUFLEN	Specifies the size, in bytes, of the value contained in the MSGBUF parameter. The message length must be greater than 0 and less than or equal to the maximum I/O buffer size parameter specified in the HCON session profile.
MSGBUF	Specifies the storage area for the character data read from the host.

Return Values

> 0 (greater than or equal to zero)	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 illustrates the use of the g32_read function in C language.

#include <g32_api>       /* API include file */
main()
{
struct g32_api *as, asx  /* g32_api structure */
char **msg_buf;          /* pointer to host msg buffer */
char *messg;             /* pointer to character string */
int msg_len;             /* pointer to host msg length */
char * malloc();         /* C memory allocation function */
int return;              /* return code is no. of bytes read */
.
.
. 
as = &asx;
msg_buff = &messg;       /* point to a string */
return = g32_read(as, msg_buff, &msg_len);
.
.
.
free (*msg_buff);
.
.
.

Implementation Specifics

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

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

In a DBCS environment, the g32_read function only reads SBCS data from a host in the MODE_API_T mode.

Files

/usr/include/g32_api.h	Contains data structures and associated symbol definitions.
/usr/include/g32const.inc	Defines Pascal API constants.
/usr/include/g32hfile.inc	Defines Pascal API external definitions.
/usr/include/g32types.inc	Defines Pascal API data types.

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.