ZCNTL (3X)

NAME

zcntl - Send control message to terminal ZLU

SYNOPSIS

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

DESCRIPTION

Routine zcntl is used to change the state of a terminal or to send a protocol dependent control message to a terminal ZLU. The routine zsend(3X) should be used for sending normal data messages to a terminal.

The terminal must be disabled first if configuration parameters are to be changed (e.g. rcode=6). As in zsend(3X), the mode parameter is used to specify how the call should be completed and for selecting the priority of the request. See under zsend(3X) for more information on its usage.

The response returned from zcntl is through the primary ZLU unless a different source ZLU is specified in the header (mhp->mid.mzsrce).

Note that a program must call zopen() to allocate a primary or auxiliary input ZLU before calling the zsend() routine. This must be done even if the program does not need an input ZLU, for example, if it is not doing any zread() calls and is only doing zsend() calls with mode = ZcMODE_NO_WAIT (0) (send no-wait) where it does not care about the return status.

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).

See the NOTES section for more information on using this routine in a multi-threaded application.

PARAMETERS

zap	Pointer to terminal ZCOM address. The destination where the control message is sent.
mode	Completion control:
	ZMODE_NO_WAIT ZMODE_RPT_ERRS ZMODE_DEF_STATUS ZMODE_RPT_ERRS_WBUF ZMODE_DEF_STATUS_WBUF ZMODE_WAIT	(0) - Send no wait (1) - Send no wait, report errors (2) - Send no wait, definite status (5) - Send no wait, report errors with buffer (7) - Send no wait, definite status and buffer (8) - Send and await status in rstat
	Modes 5 and 7 are only meaningful when rcode is 3. Some bits (when set) in the mode parameter can cause zcntl to behave differently. Refer to the NOTES section in zsend(3X) for details.
rcode	Control request code:
	ZCOM_MRQCODE_CNTWR ZCOM_MRQCODE_TERM ZCOM_MRQCODE_ENB ZCOM_MRQCODE_DSB ZCOM_MRQCODE_ACT ZCOM_MRQCODE_DEA	(3) - Control write (length in len) (6) - Set terminal parameters (7) - Enable terminal (8) - Disable terminal (9) - Activate polling (10) - Deactivate pollin
	To operate normally, a terminal ZLU must be enabled (rcode=ZCOM_MRQCODE_ENB) and activated (rcode=ZCOM_MRQCODE_ACT). If the terminal ZLU is deactivated (rcode=ZCOM_MRQCODE_DEA), the ZCOM subsystem cannot receive incoming messages from that terminal (used for flow-control). If it is disabled (rcode=ZCOM_MRQCODE_DSB), data messages can neither be sent nor received from the terminal. Request ZCOM_MRQCODE_TERM is used to configure a terminal with new parameters, which are protocol dependent. Control write request ZCOM_MRQCODE_CNTWR provides a means of passing protocol specific control information to a terminal. These two requests require setting up the ibuf and len parameters.
mhp	Pointer to message header. It contains some data fields to be sent with the data message. See the NOTES section in zsend(3X) for what fields must be set up by the caller. If NULL is specified, default values are used. For its structure, refer to the subsection on 'Message Header' in the Multi-protocol ACC Programmers' Reference Guide.
ibuf, len	If rcode=ZCOM_MRQCODE_CNTWR, ibuf contains the control data for the protocol, and len indicates the length of the control data. If rcode=ZCOM_MRQCODE_TERM, ibuf contains the configuration data for the terminal as described below, and the len indicates the total length of the configuration data. For other values of rcode, ibuf and len are not used.
rstat (ReturnParam)	Return status. Only used for requests issued with 'wait', i.e. mode = ZMODE_WAIT. NULL may be used if the return status is not required.

NOTES

File /opt/acc/include/zcom/zcomsys.h contains the symbolic names for rcode (not all of them are applicable to zcntl):

/* Message request code values applicable to zcntl() */
#define ZCOM_MRQCODE_CNTWR    3 /* Terminal write */
#define ZCOM_MRQCODE_STATUS   5 /* Unsolicited status change */
#define ZCOM_MRQCODE_TERM     6 /* Set terminal parameters */
#define ZCOM_MRQCODE_ENB      7 /* Terminal enable */
#define ZCOM_MRQCODE_DSB      8 /* Terminal disable */
#define ZCOM_MRQCODE_ACT      9 /* Terminal activate */
#define ZCOM_MRQCODE_DEA      10 /* Terminal deactivate */

The result for a zcntl request is returned in the rstat parameter if mode=8, or may be returned in a response message via zread(3X) if another non-zero mode is specified. Refer to the NOTES section in zsend(3X) for more information on the mode parameter. See zread(3X) for more details on response messages.

For rcode=ZCOM_MRQCODE_TERM (Set terminal parameters), the terminal configuration data in ibuf must be set as follows. Refer to /opt/acc/include/zcom/zcomsys.h for these data structures:

For any ACC card except an i960 4-channel ACC card:

Data structure: ztrq_type

Must set RTYP bit = 0.

	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
0	RTYP	0	Terminal Type						-	-	-	-	-	Port #
2	Group Poll Code								Device Poll Code
4	Group Select Code								Device Select Code
6	Terminal Option Word

For any i960 4-channel ACC card:

Data structure: ztrq2_type

Must set RTYP bit = 1. This usually means setting the ztrq2_type.tmreqt field to 0x80.

	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
0	RTYP	Ext. Req. Type							Terminal Type
2	Port Number								Subchannel Number
4	Group Poll Code								Device Poll Code
6	Group Select Code								Device Poll Code
8	Terminal Option Word
10	Special Terminal Configuration (Variable Length, max. 6 bytes)

The terminal type relates a protocol to the specific terminal (the device name in a TTGEN configuration file maps to a terminal type for each terminal). The terminal port must be the same as the original port. To move a terminal from one port to another, use zconfig(3X). The special terminal configuration is protocol dependent, and corresponds to the field spec_cfg of the physical terminal table (see zptt_type in /opt/acc/include/zcom/zcomsys.h). Currently, a maximum of 6-byte is allowed. Configuration data larger than this is silently truncated.

The tag parameters (mhp-> mid.mtagw1 and mtagw2) may be used in zcntl for identifying the origin of a response when returned from zread(3X). They may also contain codes indicating the specific action to be taken on completion of the request.

RETURN VALUE

Routine zcntl 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.

If mode 8 is used and zcntl returns with zero, rstat contains the return status: 0 means successful, a non-zero value means there was a problem with the control request. zcomstatus(3X) may be used to retrieve a status message, using rcode and rstat.

EXAMPLE

#include     <zcom/zcomsys.h>
#include     <zcom/zcomcall.h>
   
int32        ierr;
zaddr_type   zaddr;
uint32       mode;
uint32       rcode;
zmhd_type    zmhd;
char         ibuf[size]; /* where size is user-determined; must be >= len */
int32        len;
int32        waitstat;
 
if (ierr = zcntl (&zaddr, mode, rcode, &zmhd, ibuf, len, &waitstat)) {
    /* error return code */
}
else {
    /* good return code */
}
 
/* For request ZCOM_MRQCODE_TERM for i960 card (e.g. Z7300A) */
ztrq2_type  ztrq2;
char             spec_cfg[6];
 
ztrq2.tmreqt = 0x80;
/* ... setup other ztrq2 fields and spec_cfg[], max 6 bytes */
memcpy(ibuf, &ztrq2, sizeof(ztrq2));
memcpy(ibuf + sizeof(ztrq2), spec_cfg, 6);
rcode = ZCOM_MRQCODE_TERM;
len = sizeof(ztrq2) + 6;
if (ierr = zcntl (&zaddr, mode, rcode, &zmhd, ibuf, len, &waitstat)) {
     /* 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).