g32_write Function

Communications Technical Reference, Volume 1

g32_write Function

Purpose

Sends a message to a host application.

Libraries

HCON Library

C (libg3270.a)

Pascal (libg3270p.a)

FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_write (as, msgbuf, msglen)

struct g32_api *as;

char *msgbuf;

int msglen;

Pascal Syntax

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

FORTRAN Syntax

EXTERNAL G32WRITE

INTEGER AS(9), MSGLEN, G32WRITE

CHARACTER* XX MSGBUF

RC = G32WRITE(AS, MSGBUF, MSGLEN)

Description

The g32_write function sends the message pointed to by the msgbuf parameter to the host. This function may only be used by those applications having API/API or API/API_T mode specified by the g32_alloc command.

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.

C Parameters

as	Specifies the pointer to a g32_api structure.
msgbuf	Specifies a pointer to a message, which is a byte string.
msglen	Specifies the length, in bytes, of the message pointed to by the msgbuf parameter. The value of the msglen parameter must be greater than 0 and and less than or equal to the maximum I/O buffer size specified in the HCON session profile.

Pascal Parameters

as	Specifies the g32_api structure.
buffer	Specifies an address of a character-packed array. Note: The address of a packed array can be obtained by the addr() function call: buffer := addr (<msg array name> [1]).
msglen	Specifies an integer indicating the length of the message to send to the host. The msglen parameter must be greater than 0 and less than or equal to the maximum I/O buffer size specified in the HCON session profile.

FORTRAN Parameters

AS	Specifies the g32_api equivalent structure as an array of integers.
MSGBUF	Specifies a character array containing the data to be sent to the host.
MSGLEN	Specifies the number of bytes to be sent to the host. The MSGLEN parameter must be greater than 0 and less than or equal to the maximum I/O buffer size specified in the HCON session profile.

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, in C language, the use of the g32_write function:

#include <g32_api>       /* API include */
main()
{
struct g32_api *as;      /* the g32 structure */
char *messg;             /* pointer to a character string to
                            send to the host */
int length;              /* Number of bytes sent */
char *malloc();          /* C memory allocation function */
int return;               /* return code is no. of bytes sent */
.
.
.
messg = malloc(30);       /* allocate 30 bytes for the string */
       /* initialize message string with information */
strcpy(messg,"string to be sent to host/0");
length = strlen(messg);   /* length of the message */
return = g32_write(as,messg,length);
.
.
.

Implementation Specifics

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

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

In a DBCS environment, the g32_write function only sends SBCS data to 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.