ZSET_RCVR (3X)

NAME

zset_rcvr - Set up program ZLU as message receiver for a terminal ZLU

SYNOPSIS

#include  <zcom/zcomsys.h>
#include  <zcom/zcomcall.h> /* if compiled with ANSI C (recommended) */
 
int32 zset_rcvr (action, zap, mode, rzap)
 
int            action;
zaddr_type     *zap;
uint32         mode;
zaddr_type     *rzap;

DESCRIPTION

The zset_rcvr() routine is used to establish where incoming data from a terminal ZLU is to be queued. When zset_rcvr() is called, the rzap parameter is used to supply the program ZLU to queue the data on. (Note: An application's program ZLU is returned by the zopen() routine.)

The type of data queued is selected using the mode parameter. You may choose to receive data/status messages, and/or control messages. The location (Virtual Circuit/device/terminal/etc) from which you want to receive the data is specified by the zap parameter. An action parameter value of ZcADD_PRIMARY sets the primary receiver.

Once you have called zset_rcvr(), the application program can issue zread() requests to retrieve any data that may have arrived from the selected terminal ZLU.

An application program that issues a zset_rcvr() call, as described above, is the primary receiver of the specified messages. Another application program can take over being the primary receiver by issuing a zset_rcvr() request, using the same mode and rzap parameters, with the action code also set to ZcADD_PRIMARY. In this situation, data is no longer queued to the original application.

The zset_rcvr() routine can also be used to allow messages to be received by more than one application program at a time. This feature is selected by using an action parameter value of ZcADD_SHARED. When ZcADD_SHARED is used, it specifies that the program does not want to take over being the primary receiver, but simply added as an additional receiver of the incoming messages. Use of this feature does not require that a primary receiver be defined. For every terminal, each receiver mode (except mode ZcOUTB_MLTPLX) allows a maximum of ZcMAX_SHARED_RCVRS (64) program ZLUs to be set with action ZcADD_SHARED.

An application program can indicate that it no longer wishes to receive messages by issuing a zset_rcvr() call with the same parameters as those specified in the original zset_rcvr() request, and setting the action parameter to ZcDEL_PRIMARY or ZcDEL_SHARED.

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

action	Type of action to perform.
	ZcADD_PRIMARY	- Sets the program ZLU as the primary receiver.
	ZcDEL_PRIMARY	- Deletes the primary receiver.
	ZcADD_SHARED	- Adds the program ZLU to the list of shared receivers.
	ZcDEL_SHARED	- Removes the program ZLU from the list of shared receivers.
zap	ZCOM address of terminal.
mode	Receiver mode:
	ZcNORMAL	(0) - Set receiver for normal messages
	ZcINB_MLTPLX	(1) - Set inbound multiplexer receiver
	ZcOUTB_MLTPLX	(2) - Set outbound multiplexer receiver
	ZcCONTROL	(3) - Set receiver for control messages
	Note: Only one constant value can be specified per call for this field. You cannot logically OR these values in one call
rzap	ZCOM address of the receiver program.

NOTES

Usually, an application uses only mode ZcNORMAL to set up itself as the receiver for normal data and status messages. An application uses mode ZcCONTROL only if it needs to receive “control” messages. Control messages are generated by ZCOM protocol modules. You should refer to the specific ZCOM Protocol Manual to determine the “control” messages generated by that protocol, if any.

Modes ZcINB_MLTPLX and ZcOUTB_MLTPLX require the terminal to be an inbound and outbound multiplexed terminal, respectively. Otherwise, error ZERTYPE (-54) is returned. A multiplexed terminal is usually set up by defining the proper device type in the TTGEN configuration file (using TERM or LTERM statements). It may also be modified by using zltmx.

When inbound multiplexing is enabled for a terminal, an inbound receiver must be set up (using mode ZcINB_MLTPLX) by the multiplexing program, which will be responsible for receiving messages from the terminal and passing them to the “normal receivers” kept in the logical terminal tables.

When outbound multiplexing is enabled for a terminal, an outbound receiver must be set up (using mode ZcOUTB_MLTPLX) by the multiplexing program, which will intercept data sent from other programs. The outbound multiplexing program is responsible for passing the correct data onto the physical terminal (using zsend with mode bit ZCOM_ZSEND_NOMX). For more information, see the section on Multiplexing in the Multiprotocol ACC Programmer's Reference Guide.

The ZcADD_SHARED action is not supported for mode ZcOUTB_MLTPLX (outbound multiplexer receiver).

RETURN VALUE

Routine zset_rcvr returns 0 if successful. Otherwise, a non-zero error code is returned. 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;
int          action;
zaddr_type   zaddr;
uint32       mode;
zaddr_type   raddr;
 
if (ierr = zset_rcvr (action, &zaddr, mode, &raddr)) {
          /* error return code */
}
else {
          /* good return code */
}

FILES

/opt/acc/include/zcom/zcomsys.h	ZCOM system 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).