G32READ Function

Purpose

Receives a message from the API application running simultaneously on the local system.

Syntax

G32READ

Description

The G32READ function receives a message from an application programming interface (API) application. The G32READ function returns when a message is received. The status of the transmission is returned in register zero (R0).

The G32READ function returns the following information:

Return	Description
R0	Indicates the number of bytes read.
R1	Indicates the address of the message buffer.

In VM/CMS, storage for the read command is obtained using the DMSFREE macro. R0 contains the number of bytes read. R1 contains the address of the buffer. It is the responsibility of the host application to release the buffer with a DMSFRET call. Assuming the byte count and address are in R0 and R1, respectively, the following code fragment should be used to free the buffer:

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

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

SRL  R0,3
A    R0,=F'1'
DMSFRET DWORDS=(0),LOC=(1)

In MVS/TSO, storage for the READ command is obtained using the GETMAIN macro. R0 contains the number of bytes read. R1 contains the address of the buffer. The host application must release the buffer with a FREEMAIN call.

Attention: In MVS/TSO, when programming an API assembly language application, you must be careful with the TPUT macro. If it is used in a sequence of G32READ and G32WRITE subroutines, it will interrupt the API/API mode and switch the host to the API/3270 mode to exit. You will not be able to get the API/API mode back until you send the Enter key.

Return Values

The G32READ function sets register zero (R0) to the following values:

Value	Description
> 0	Normal return. Indicates the length of the message as the number of bytes read.
< 0	Less than zero. Indicates a host API error condition.

Examples

The following 370 Assembler code example illustrates the use of the host G32READ function:

           .
           .
           .
MEMORY  L  12,=v(G32DATA)      /* SET POINTER TO API DATA AREA */
        .
        .
        .
        L  2,=F`2'
        G32READ                /* RECEIVE MESSAGE FROM AIX */
        ST 1,ADDR              /* STORE ADDRESS OF MESSAGE */
        ST 0,LEN               /* STORE LENGTH OF MESSAGE */
        BAL 14,CHECK
           .
           .
           .