Receives a message from the API application running simultaneously on the local system.
G32READ
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:
| 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:
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.
The G32READ function sets register zero (R0) to the following values:
| > 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. |
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
.
.
.
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.
For documentation on the DMSFREE and DMSFRET macros, consult the VM/SP Entry System Programmer's Guide.
For documentation on the GETMAIN and FREEMAIN macros, consult the MVS/XA System Macros and Facilities, Volume 2 or MVS/XA Supervisor Services and Macros.