ZREAD (3X)

NAME

zread - Read from ZLU

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zread (zap, mode, mhp, ibuf, len, rlen, rstat)
 
zaddr_type       *zap;
uint32           mode;
zmhd_type        *mhp;
char             *ibuf;
int32            len;
int32            *rlen;
int32            *rstat;

DESCRIPTION

Routine zread fetches the next message from the head of a program ZLU queue. The program has the option to wait (i.e., suspend) if there is no data on the queue specified. The actual length of the data message is returned in rlen.

This routine is similar to zpeek(3X) except it removes the message after fetching it.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1).

Threads Considerations

This routine may be called from a multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application:

cancellation point	Thread cancellation can occur when a thread calls this routine.
async-cancel unsafe	The calling thread's cancelability type must be PTHREAD_CANCEL_DEFERRED if cancellation is enabled.
async-signal unsafe	It cannot be called from a signal handler.
fork unsafe	It cannot be called by a child process after fork(2) but before exec(2).

PARAMETERS

zap	Pointer to program ZCOM address. Source to get input messages.
mode	ZcREAD_W_WAIT (0) - Read with wait. The ztimr() call can be used to set a timeout period that will cause the zread() call to unsuspend and continue after the timeout period has elapsed. ZcREAD_WO_WAIT (1) - Read without wait. Note: If mode = 0, the program is suspended until there is a message on the input queue. If mode = 1, and there is no message on the queue, error ZENODATA (-24) is returned. Otherwise, the message is placed in ibuf. If bit ZCOM_ZREAD_SHARE (0x2000) is set, the input may be shared by multiple processes. This allows multiple processes to read (and wait) on the same ZLU. When a message arrives, only one of the waiting processes will return with the data. If bit ZCOM_ZREAD_QUIET (0x4000) is set, the automatic response mechanism is suppressed. Normally, when a message is sent (e.g., by zsend(3X)) with a mode requesting response, a response is generated automatically when the message is read by zread. This bit is used to suppress this response, and the caller is responsible for checking the request mode and sending a response back to the originator if necessary. This feature is intended for multiplexing programs and should be used with care. This bit is not used in zpeek(3X).
mhp (Return Param)	Pointer to message header. It is the message header received with the data buffer. NULL may be specified if the caller does not require the returned message header. It is described in the subsection on 'Message Header' in the Multiprotocol ACC Programmers' Reference Guide. See the data structure zmhd_type in zcomsys.h for more detail.
ibuf (Return Param)	Buffer for the received data.
len	Maximum length in bytes of the buffer ibuf.
rlen (Return Param)	Actual data length. NULL may be specified if the caller does not require the returned message length. Note that rlen may exceed len. This indicates the received data is truncated to just fill up ibuf.
rstat (Return Param)	Return status. 0 - no error -ve - ZCOM error code +ve - terminal error status It is meaningful only if the returned message is a response or terminal message. For other message types, it is always returned with zero. NULL may be specified if the caller does not require this return status. The return status rstat and the request code mhp->mrq.mrqcode may be used to retrieve a status message by calling zcomstatus(3X).

NOTES

If zsend(3X) was used to send data using modes 1, 2, 5, or 7, then the input ZLU queue may contain response status messages. If the sent message could not be delivered by the driver (e.g., data corruption in the host system), an error response is returned to the sender's primary ZLU. When such an error response is picked up by zread, the function returns with zero (indicating no problem in reading the input ZLU), the returned message type is set (e.g., ZCOM_MSTYPE_RSLT) and the return status will carry a negative ZCOM error code. If the message could not be delivered by the interface (e.g., a problem with the terminal line), the returned response will have a positive ZCOM status code indicating the problem.
If the received message (or response) is from a terminal, the request code is returned in mhp->mrq.mrqcode. The request code and the returned status may be used to retrieve an appropriate status/error message by zcomstatus(3X). Refer to Appendix B ZCOM Status Codes of the Multiprotocol ACC Programmers' Reference Guide for more information. The mhp->mrq.mrqcode field contains 0 if the message is from a program or is a System Event Message (SEM).
A System Event Message (SEM) is generated by the ZCOM subsystem in response to special events that occur within the ZCOM subsystem. A program may choose to receive event messages by supplying its primary ZLU in a zevent_rcvr call. All ZCOM Event messages are divided into a header and event specific data section. The header is defined for all types of Event messages while the data portion depends on the ZCOM Event Message type. Refer to the subsection 'System Event Messages' in the Multiprotocol ACC Programmers' Reference Guide for more information. The SEM's structure is defined in /opt/acc/include/zcom/zcomsys.h.
The tag parameters (mhp->mid.mtagw1 and mtagw2) are the tag parameters from the originating zsend(3X) call.
The type of message received is returned in mhp->mid.mstype. Its values are as follows (defined in /opt/acc/include/zcom/zcomsys.h):

#define  ZCOM_MSTYPE_REMOTE     0x08         /* Mask for remote message bit */
#define  ZCOM_MSTYPE____0        0           /* Undefined type */
#define  ZCOM_MSTYPE_MSLT        1           /* From local terminal */
#define  ZCOM_MSTYPE_LPLP        2           /* Local program to program */
#define  ZCOM_MSTYPE_TOLZ        3           /* Timer message for local ZLU */
#define  ZCOM_MSTYPE_LPLT        4           /* Local program to terminal */
#define  ZCOM_MSTYPE_LSEM        5           /* Local system event message */
#define  ZCOM_MSTYPE_RSLT        6           /* Response from local terminal */
#define  ZCOM_MSTYPE_RSLP        7           /* Response from local program */
#define  ZCOM_MSTYPE____8        8           /* Undefined type */
#define  ZCOM_MSTYPE_MSRT        9           /* Remote terminal message */
#define  ZCOM_MSTYPE_RPLP        10          /* Remote program to program */
#define  ZCOM_MSTYPE_TORZ        11          /* Timer message for remote ZLU */
#define  ZCOM_MSTYPE_RPLT        12          /* Remote program to terminal */
#define  ZCOM_MSTYPE_RSEM        13          /* Remote system event message */
#define  ZCOM_MSTYPE_RSRT        14          /* Response from remote terminal */
#define  ZCOM_MSTYPE_RSRP        15          /* Response from remote program */

RETURN VALUE

Routine zread returns 0 if the call is successful. In addition, for a response message, a non-zero return status rstat indicates there was a problem with the previous zsend(3X) call. A non-zero return status with a terminal message or response indicates there was a problem with the terminal. For other message types, the return status is always 0.

If the zread call itself failed, a non-zero error code is returned, and the other return parameters do not contain valid values. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings.

EXAMPLE

#include   <zcom/zcomsys.h>
#include   <zcom/zcomcall.h>
 
int32            ierr;
zaddr_type       zaddr;
uint32           mode;
zmhd_type        zmhd;
char             ibuf[size]; /* where size is user-determined; must be >= len */
int32            len;
int32            rlen;
int32            rstat;
 
if (ierr = zread(&zaddr, mode, &zmhd, ibuf, len, &rlen, &rstat)) {
        /* error return code */
}
else {
        /* good return code */
}




	NOTE: Check zmhd.mid.mstype to determine the message type. For response or terminal messages, check for non-zero rstat to see if there was any problem with the previous zsend(3X) or with the terminal.

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files.
/opt/acc/include/zcom/zcomcall.h	ZCOM routine function prototypes (requires ANSI C compilation).