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.

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.

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.

C Parameters

Item Description
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

Item Description
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

Item Description
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

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