ACC Programmer’s Reference Guide Edition 1 HP 9000 Networking Manufacturing Part Number : Z7345-90008 E0204 © Copyright 2004 Hewlett-Packard Company, All rights reserved.
Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty.
This software is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University of California. ©copyright 1980, 1984, 1986 Novell, Inc. ©copyright 1986-1992 Sun Microsystems, Inc. ©copyright 1985-86, 1988 Massachusetts Institute of Technology. ©copyright 1989-93 The Open Software Foundation, Inc. ©copyright 1986 Digital Equipment Corporation. ©copyright 1990 Motorola, Inc.
Printing History The manual publishing date and part number indicate its current edition. The publishing date will change when a new edition is published. Minor changes may be made without changing the publishing date. The manual part number will change when extensive changes are made. Manual updates may be issued between editions to correct errors or document product changes. To ensure that you receive the updated or new editions, you should subscribe to the appropriate product support service.
Related Documentation The documentation available for the Multiprotocol ACC family of products includes the following hardware and software manuals: Hardware Manuals • 8 Channel PCI ACC Multiplexer Hardware Installation and Reference Manual Software Manuals • • • • • • • • • • • • • 6 ACC Installation and Configuration Guide ACC Utilities Reference Guide ACC Programmer’s Reference Guide ACC Error Guide HDLC Frame Protocol User’s Guide ACC X.25 Protocol User’s Guide ACC X.
Contents 1. ZCOM Subsystem Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZCOM Software Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZCOM Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Program ZLUs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Queue Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Buffer Pool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Organization of Buffer Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Message Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents ZCOMLOG (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZCOMSTATUS (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZCONFIG (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ZEVENT_RCVR (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 10
1 Chapter 1 ZCOM Subsystem 11
ZCOM Subsystem Introduction Introduction The ZCOM Subsystem consists of software and firmware that provide the base set of features for the ACC Product family.
ZCOM Subsystem ZCOM Software Overview ZCOM Software Overview Figure 1-1 on page 14 presents an architectural overview of the ZCOM Subsystem. The ZCOM application interface provides low level access to the ZCOM Subsystem. Application programs make requests via the ZCOM library routines which are then communicated to the firmware on the ACC Mux card via the HP-UX drivers. The firmware which runs on the ACC Mux card includes the ZCOM Mux kernel software plus ZCOM protocol modules.
ZCOM Subsystem ZCOM Software Overview Subsystem as separate products. The Protocol User’s Guides provided with these products must be used in conjunction with this Programmer’s Reference Guide when writing ZCOM application programs. Figure 1-1 Overview of ZCOM Software Structure Application or Utility Program Application or Utility Program X.25 TCP/IP Other high level protocol X.25 Level3 Prog. Accs. . . . . . . Application or Utility Program . . . . . .
ZCOM Subsystem ZCOM Software Overview Figure 1-2 presents another view of the ZCOM Subsystem which includes the relationships between the various components of the ZCOM Subsystem: Figure 1-2 ZCOM Subsystem Components C Application Program ZCOM initialization and Mux download by ZMON ZCOM I/F Library zterm Utility zmasterd zmon ZCOM Kernel Tables & Buffers ZCOM HP-UX Drivers zmlog Error log Files ACC I/F Card ACC I/F Card ACC I/F Card ...
ZCOM Subsystem ZCOM Software Overview The zmlog program is used to log error messages generated by the programs and daemons of the ZCOM Subsystem. The zmasterd daemon is used to facilitate starting up and shutting down the daemons in the ZCOM Subsystem, and to automatically recover from daemon failures. Application programs make calls to the routines in the ZCOM application interface. The same requests that can be made programmatically can also be made interactively by using the zterm program.
ZCOM Subsystem ZCOM Concepts ZCOM Concepts Throughout this manual, references are made to terminal ZLU or just terminal. This does not mean a physical terminal device type but is a generic term that can refer to any kind of physical or logical entity. Examples of physical entities are printers, an HDLC link, terminals, etc. Examples of logical entities might be an X.25 Permanent or Switched Virtual Circuit.
ZCOM Subsystem ZCOM Concepts Figure 1-3 on page 18 shows a sample set of program and terminal ZLUs, and their interaction with each other and a Mux card: Figure 1-3 Definition and Features of ZLUs Terminal 2 Terminal 1 Terminal ZLU=231 Terminal 3 Terminal ZLU=57 Terminal ZLU=101 Mux card Program ZLU=500 Application Program B Program ZLU=502 Application Program A To communicate to another program or to a terminal, a program uses ZCOM library calls to write to a program or terminal ZLU.
ZCOM Subsystem ZCOM Concepts are maintained automatically by the ZCOM Subsystem. When a message is sent to a ZLU, the data is moved to a system buffer first and the address of the message is moved to the attached input queue. Program ZLUs Each program may open one or more program ZLUs which provides an input message queue to that program. Think of a program’s input message queue as a mailbox where messages can be delivered.
ZCOM Subsystem ZCOM Concepts level of priority. The Express Queue is used for extremely high-priority protocol dependent requests. The High-Priority Queue is used for high priority data and the Low-Priority Queue is used for low priority data. When a message is generated by an application, the buffers involved are queued to the selected transmit queue and the ZCOM driver is notified. The driver is then responsible for handling the message.
ZCOM Subsystem User Interface User Interface The interface between the application programs and the ZCOM Subsystem is through the ZCOM ‘C’ Application Programming Interface (API) library. The functions provided by this library are documented in Chapter 4, “ZCOM C I/F Library Routines.” All functions within the library are thread-safe and can be used in multi-threaded programs. Both 32-bit and 64-bit applications are supported.
ZCOM Subsystem References References The following manuals should be referred to when using the ZCOM application interface: • • ACC Installation and Configuration Guide ACC Utilities Reference Guide The manuals corresponding to the protocol being used should also be referred to: • • • ACC X.
2 Chapter 2 ZCOM Message Handling 23
ZCOM Message Handling Overview Overview ZCOM message handling is achieved through logical constructs called ZLUs which maintain queues for messages to terminals and programs. The terminal ZLUs are either defined at ZCOM configuration time using ttgen, or can be created programmatically using the Dynamic System Configuration functions; the program ZLUs are allocated dynamically from a pool of ZLUs when requested.
ZCOM Message Handling ZLU Definition ZLU Definition There are three types of ZLUs. These are: • Program • Terminal (or remote device via a communication link) • Mapped Program ZLUs A Program ZLU may be either a primary ZLU or an auxiliary ZLU. All programs using ZCOM must have a primary ZLU defined. Other ZLUs may then be defined as auxiliary if required. If a message is sent to another program, then the destination ZLU is the other program’s primary or auxiliary ZLU.
ZCOM Message Handling ZLU Definition Mapped ZLUs All messages addressed to a particular ZLU will be redirected to the alternate ZLU specified in the zmapr routine call if the original ZLU has been mapped to a different ZLU. One use of mapped ZLUs is for providing high availability systems. For example, if a hardware failure was detected in one of the ACC Mux cards, the application could map all of the ZLUs associated with the failed card to a spare unused card in the system.
ZCOM Message Handling Message Queuing Message Queuing Each program ZLU (either primary or auxiliary) has a single input queue on which messages are received and read on a first-in-first-out basis. Because the ZLU is the input queuing mechanism for timeouts and statuses, as well as for data messages, all programs should request (through the zopen routine) at least one program ZLU before using the other ZCOM calls. The ztimr routine may be used to enable or disable the timer on a program ZLU.
ZCOM Message Handling Message Queuing Queues for terminal ZLUs are located in the physical terminal tables in the ZCOM memory area as shown in Figure 2-2. The physical terminal tables (one per terminal) maintain four queues for each terminal.
ZCOM Message Handling Priorities Priorities Priorities only apply to messages that are destined for terminals. Messages to program ZLUs are simply added to the end of the input queue for that ZLU. Messages destined for terminal ZLUs may have either express, high or low priority. The priority for a message is determined by bits ZCOM_ZSEND_LPR and ZCOM_ZSEND_XPS of the mode parameter, in the zsend and zcntl routine calls.
ZCOM Message Handling Multiplexing Multiplexing The multiplexing feature of ZCOM allows more than one logical terminal to be mapped to a single physical terminal. This mechanism is implemented in ZCOM by allowing messages to and from a terminal ZLU to be intercepted by a program (which is able to alter the data content, e.g., adding or removing headers) and then forwarded on to the destination physical terminal or its receiver program.
ZCOM Message Handling Multiplexing Outbound Multiplexing The multiplexing program uses the zread call to determine the origin of the message, after which, the program would normally attach a protocol header and forward the message to the destination physical terminal. MZAUXL in the message header (see the chapter on Tables and Data Structures) can be used to save the originating source node and ZLU on the outbound message.
ZCOM Message Handling Multiplexing If the ZCOM_LTFLAG_OMX bit is set in the LTFLAG word of the logical terminal table, then a logical terminal is enabled for outbound multiplexing. This means that any message sent (by zsend) to this terminal ZLU will be formatted as normal (type 4, ZCOM_MSTYPE_LPLT, message with request descriptor block), but instead of being queued to the physical terminal transmit queue, it will be queued to the program ZLU defined by LTZMXP.
ZCOM Message Handling Multiplexing The inbound multiplexing program has the task of receiving all messages from the physical terminal. It determines the origin of the logical terminal from which the messages were sent. Then it processes any of the control messages and forwards the data portion of any data messages to the application receiver.
ZCOM Message Handling Terminal State Terminal State Within the ZCOM subsystem, the terminal state may be either enabled or disabled, activated or deactivated. For normal I/O operations, a terminal ZLU must be both enabled and activated. If a terminal is disabled (regardless of whether it is activated), then no messages can be sent to it or received from it. If a terminal is enabled but deactivated, then messages can be sent to the terminal, but none can be received.
ZCOM Message Handling Error Handling Error Handling In the normal functioning of ZCOM, transmission errors on messages to terminal ZLUs are handled by the Mux interface card firmware. The firmware always sends a status back to the driver after it has processed a request - retries are handled internally. The driver checks the mode of the send (i. e., send no wait, report errors, etc.) to determine what to pass back to the requesting program.
ZCOM Message Handling Error Handling 36 Chapter 2
3 Chapter 3 ZCOM Tables and Data Structures 37
ZCOM Tables and Data Structures Introduction Introduction This chapter gives a detailed description of the ZCOM subsystem memory organization and table layout. Each table structures is described in overview, followed by a detailed explanation of all of the elements within the table.
ZCOM Tables and Data Structures Memory Organization Memory Organization The ZCOM Logical Device Manager (LDM driver) reserves a contiguous block of kernel memory for tables for its use. The maximum size of this memory block is tunable at kernel build time through the zcom_mem_size parameter in the “system” file used to build your kernel. The default value for this parameter is 4 Mbytes. This memory is allocated relative to a starting pointer.
ZCOM Tables and Data Structures Differences in 32-bit and 64-bit Data Structures Differences in 32-bit and 64-bit Data Structures HP-UX supports 64-bit mode using the LP64 model. This means the long and pointer fields are 64-bits in length. The ZCOM memory data structures are designed to be 32/64-bit neutral by using conditional padding fields. For example, a pointer field is defined as a 64-bit pointer in 64-bit mode.
ZCOM Tables and Data Structures Differences in 32-bit and 64-bit Data Structures NOTE Chapter 3 The following sections document the data structures used internally by the ACC ZCOM product to implement its functionality. These data structures are subject to change without notice. Programs that directly use these structures may be required to recompile their sources when a new version of the ZCOM subsystem is released (this will be indicated in the release notes).
ZCOM Tables and Data Structures ZCOM Header Structure ZCOM Header Structure The ZCOM Header structure holds the system parameters and pointers to other areas of the ZCOM memory tables as well as other information that pertains to the whole ZCOM subsystem. The layout of the ZCOM Header structure zheader_type is shown in Table 3-1. Table 3-1 Field Name ZCOM Header Structure Field Description Field Type Size (Bytes) HLABEL Header label char [4] 4 HZREVC ZCOM rev code uns.
ZCOM Tables and Data Structures ZCOM Header Structure Table 3-1 ZCOM Header Structure (Continued) Field Name Field Description Field Type Size (Bytes) HNCARD Number of interface tables uns.short 2 HNRESP Number of response records uns.short 2 HNLTQL Number of LTT queue labels uns.short 2 HNLTSL Number of LTT storage labels uns.
ZCOM Tables and Data Structures ZCOM Header Structure Table 3-1 Field Name ZCOM Header Structure (Continued) Field Description Field Type Size (Bytes) HNDPID ZNODE Process ID int 4 HNDSIG ZNODE required signal int 4 HNIDLE ZNODE idle timer value uns.int 4 HNHIGH ZNODE queue high-water mark uns.int 4 HNLOW ZNODE queue low-water mark uns.int 4 HNWAIT ZNODE high-water mark waiter uns.short 2 HLCLND Local node number uns.
ZCOM Tables and Data Structures ZCOM Header Structure HLABEL - ZMON identifier label The identifier label contains the word ‘ZMON’ and provides compatibility with HP1000 version of ZCOM. The memory image file contains the word ‘TTGE’ in this position. The LDM overwrites this after the ZCOM subsystem has been initialized. HZREVC - ZCOM revision code TTGEN initializes this field with a 16-bit revision code, indicating the version of the table structures. This revision code is stored as four 4-bit digits.
ZCOM Tables and Data Structures ZCOM Header Structure This pointer contains the starting physical kernel memory address of the ZCOM subsystem memory. It is initialized to zero by TTGEN. ZMON initializes it with the memory address while loading the memory tables into kernel memory. It is a 64-bit value when used in a 64-bit kernel. HSSIZE - Total runtime system size in bytes This is the total size in bytes of the ZCOM subsystem memory, including all tables, queue headers, and the buffer pool.
ZCOM Tables and Data Structures ZCOM Header Structure HLTDSZE - Logical terminal table LDATA buffer size This specifies the size of the LDATA buffer in the logical terminal tables. This value is initialized from the Logical-Size parameter in the TTGEN configuration file. Set this parameter to 212 for backward compatibility with HP 1000 programs (so that the total size of Logical Terminal Table with extension is 512 bytes).
ZCOM Tables and Data Structures ZCOM Header Structure HPNTBL - Node Table pointer (znode_type *) This is a pointer to the first entry in the Node Table. Note that all of the node entries are stored in sequential order within kernel memory. HPZLU - ZLU table pointer (zlu_type *) This is a pointer to the 1st entry in the ZLU table. Note that all of the ZLU table entries are stored in sequential order within kernel memory.
ZCOM Tables and Data Structures ZCOM Header Structure file. The default limit may be overridden during a zopen() by specifying a non-zero value in the limit parameter. The program ZLU queue limit may be changed dynamically by calling the zsetql() routine. HUNACK - Maximum number of unacknowledged Tx buffers pending on a terminal ZLU Upper limit of the total size (in bytes) of all unacknowledged transmit messages to a terminal ZLU.
ZCOM Tables and Data Structures ZCOM Header Structure HCTOTAL - Total number of Dynamic System Configuration (DSC) requests This field contains the number of DSC requests processed by the ZCOM subsystem since it was initialized and started up. It is incremented every time a DSC request is processed. This value is for information purposes only. HCSTATE - Dynamic System Configuration (DSC) State This field is used by the ZCOM subsystem as an indicator for controlling DSC functions.
ZCOM Tables and Data Structures ZCOM Header Structure HNDSIG - ZNODE signal number Contains the type of signal to use when informing ZNODE of the arrival of new data in the ZNODE queue. This field is initialized to zero by TTGEN and is set up by the ZNODE program when it starts up. HNIDLE - ZNODE idle timer This contains the time in seconds since ZNODE last issued a Node-Status Update ioctl request to the ZCOM subsystem (LDM).
ZCOM Tables and Data Structures ZCOM Header Structure HLCLND - Local node number The node number of the local ZCOM subsystem. If the Node-Definition section in the TTGEN configuration file is omitted, TTGEN defaults this field to one (1). Otherwise, it is initialized to the value of the Local-Node parameter. It is set up by TTGEN as the first node table entry that has zero ZLU number.
ZCOM Tables and Data Structures ZCOM Header Structure HLTSTB - Storage label table The storage label entry indicates the ownership of an application data storage area in the logical terminal table extension area. Each entry is a structure of 16 bytes (zslb_type), as shown in Table 3-3. Table 3-3 Field Name Storage Label Table Field Description Field Type Size (Bytes) SLBGRP Appl. grp. number (0 = globally assigned) uns.
ZCOM Tables and Data Structures ZCOM Header Structure issues a transmit request to the E1/T1 card and the card does not have enough free buffers to hold the request data, the Mux will reject the request with an “out of buffers” error. The DAM will retry the request after an unacknowledged transmit request completes. This field is used to minimize the number of retries (and thereby increase overall performance) by imposing a limit on the size of unacknowledged transmit requests.
ZCOM Tables and Data Structures Node Entries Table Node Entries Table The Node Entries table contains information about the remote ZCOM systems that communicate with the local ZCOM subsystem. Each Local-Node and Remote-Node definition in the TTGEN configuration file occupy one entry in the table. Each entry structure is 392 bytes long and has the format shown in Table 3-4. Table 3-4 Field Name Node Entries Table Field Description Field Type Size (Bytes) node_num ZCOM system node number uns.
ZCOM Tables and Data Structures Node Entries Table FLAGS - Node status and internal flags This bit-field structure contains bits to maintain state and other internal information about this node. The contents of this field are as follows: FLAGS.event - Set to 1 if there is at least one application that wants to be notified of a status change for the node. FLAGS.valid - Set to 1 if this node entry in the table is valid; that is, currently defined and in use. FLAGS.
ZCOM Tables and Data Structures Node Entries Table be sent to each program in this linked list. That is, those applications that have issued a zevent_rcvr() call to receive node status events. This field will be set to zero if there are no applications to be notified. NHOST - The number of defined hosts in the host array. This field contains the number of host link records defined in the HOST table below. This field is zero for a local node entry.
ZCOM Tables and Data Structures Node Entries Table this link is currently up or not. If the link is down (status = 0), the ZNODE daemon will route remote requests on any secondary links that are up. The data in this structure is maintained by the ZNODE daemon.
ZCOM Tables and Data Structures ZLU Tables ZLU Tables The ZCOM logical unit table relates a terminal device or a program queue with a number or logical unit. The ZCOM logical units are called ZLUs to distinguish them from the HP-UX logical units (LUs). Each ZLU entry structure contains 40 bytes of data. The ZLU table is split into two logically distinct parts. The first part is the physical terminal area, and the second the dynamically assignable program ZLUs. The latter are used for program input queues.
ZCOM Tables and Data Structures ZLU Tables Table 3-7 Individual ZLU Data Structure (zlu_type) (Continued) Field Name spare1 Field Description Reserved, not used Field Type int Size (Bytes) 4 ZCKSUM - ZLU checksum The checksum is used as an integrity check to ensure that a ZLU has not been altered while it is active. It is the 16-bit binary sum of bytes 3 to 18 of the ZLU entry (with any overflow discarded). It is calculated when the ZLU table entry is created.
ZCOM Tables and Data Structures ZLU Tables If the ZLU is not type 3, ZMPZCS is set to zero. Otherwise, this contains the checksum of the mapped ZLU. ZLNAME - Name of ZLU Name assigned to the ZLU by the creator of the ZLU. If the ZLU is the input queue to a program then this name is usually Z99999 - where 99999 is the program PID number. In this case the other 2 bytes are space filled. The program ZLU name can be assigned by the zopen call when the ZLU is allocated.
ZCOM Tables and Data Structures Logical Terminal Tables Logical Terminal Tables The Logical Terminal Table (LTT) pages contain the logical configuration information for each terminal ZLU in the ZCOM system. Each terminal table consists of the basic table (which is fixed for all terminals) and a table extension (which is of configurable size specified by LOGICAL-SIZE parameter in the TTGEN configuration file). The basic table contains common information for all terminal ZLUs.
ZCOM Tables and Data Structures Logical Terminal Tables Table 3-9 Logical Terminal Table (Reserved Area) (Continued) Field Name Field Description Field Type Size (Bytes) LTZMXP ZCOM address of multiplexing program struct 6 LTZPRCVR ZCOM addr.
ZCOM Tables and Data Structures Logical Terminal Tables Table 3-10 Field Name SPARE2 Logical Terminal Table (User Maintainable Area) Field Description Reserved, not used Field Type int Size (Bytes) 4 LTZLU - Terminal ZLU number This is the ZLU number of the owning terminal. LTZCS - Owning ZLU checksum This is the ZLU checksum of the owning terminal. LTMUX - Mux interface number for this terminal This is the Mux interface number that this terminal is configured on.
ZCOM Tables and Data Structures Logical Terminal Tables LTTYPE - Logical terminal type The logical terminal type is used to describe the message format expected from the terminal. For screen-type terminals this will identify the terminal as belonging to a class of terminals with the same screen formatting attributes and message delimiters (e.g., IBM.3278 or NCR.501).
ZCOM Tables and Data Structures Logical Terminal Tables LTZSHRCVRS - Pointer to a linked list of indirect shared receivers This field contains a pointer to a linked list of shared receivers that wish to receive data messages from an inbound multiplexed terminal. Each entry in the linked list represents one program. If the ZCOM_LTFLAG_IMX bit in ltflag is set, the system sets up this field on a zset_rcvr (mode 0) call.
ZCOM Tables and Data Structures Logical Terminal Tables LTSTAT - Logical status Contains the status of the logical terminal. This entry is maintained by a multiplexing program and will remain unaltered for a normal 1:1 terminal.
ZCOM Tables and Data Structures Physical Terminal Tables Physical Terminal Tables The physical terminal table (zptt_type) contains information used by the LDM and DAM to initialize and control a physical terminal (or other device). The PTT consists of a system area, which is reserved for use by the ZCOM subsystem, and a user area which may be manipulated by application programs. The user modifiable portion of the PTT immediately follows the reserved area.
ZCOM Tables and Data Structures Physical Terminal Tables Table 3-11 Field Name Physical Terminal Tables (System Area) (Continued) Field Description Size (Bytes) Field Type PTTXLA Pointer to next PTT on high priority list pointer 8 PTTXQA High priority transmit buffer queue struct 56 PTTXLB Pointer to next PTT on low priority list pointer 8 PTTXQB Low priority transmit buffer queue struct 56 PTTXQC Unacknowledged transmit buffer queue struct 56 PENDG_TXREQ Next request for $DATA st
ZCOM Tables and Data Structures Physical Terminal Tables Table 3-12 Field Name Physical Terminal Tables (User Maintainable Area PTUSER) (Continued) Field Description Field Type Size (Bytes) PTCNFG Special configuration uns.char [8] 8 PTCWCT Control write counter uns.int 4 PTTXCT Transmit message counter uns.int 4 PTRXCT Receive message counter uns.int 4 PTERCT Error counter uns.
ZCOM Tables and Data Structures Physical Terminal Tables This field contains the firmware terminal number this terminal ZLU is associated with. The firmware manages terminals using a terminal number while the ZCOM subsystem manages terminals using ZLUs on the host. On 2/8-channel cards, the terminal number must be unique for a given port. On E1/T1 cards, the terminal number is unique per card. SUBCH - Subchannel number within port This field contains the subchannel this terminal ZLU is configured on.
ZCOM Tables and Data Structures Physical Terminal Tables setting bit 1 of the input message tag byte. If there are no shared control receivers, this field will contain a zero. When a control message arrives, it will be delivered to each application in the linked list (as well an any primary control receiver). PTLIST - Pointer to next PTT on the same port Contains a pointer to the physical terminal table of the next terminal on the same Mux interface card and port number as the current terminal.
ZCOM Tables and Data Structures Physical Terminal Tables This queue contains the high priority transmit requests waiting to be sent. It also contains the terminal configuration (zcntl) requests. The data on this queue is processed only after all express transmit data has been processed. When a message has been transferred to the card, the buffers are moved to the unacknowledged transmit buffer queue.
ZCOM Tables and Data Structures Physical Terminal Tables The content of this field is as follows: Figure 3-4 Terminal Status Field PTDRST 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 EN AC UP AV IN EN AC AV - Terminal has been initialized (ZCOM_PTDRST_INT) Terminal is enabled (ZCOM_PTDRST_ENB) Terminal is active (ZCOM_PTDRST_ACT) Terminal is available for use The IN bit indicates whether the terminal is considered as part of the current configuration.
ZCOM Tables and Data Structures Physical Terminal Tables PTTYPE - Terminal type (physical) Protocol module terminal type. It is initially setup by TTGEN in the memory image file but is subsequently maintainable. SCFG_LEN - Length of the special protocol configuration bytes. This field contains the length of any protocol specific configuration data contained in the spec_cfg[] field.
ZCOM Tables and Data Structures Physical Terminal Tables PTCWCT - Terminal control write counter This counter is incremented by the driver every time a control write buffer for this terminal is transferred to the Mux interface card. PTTXCT - Terminal transmit message counter This counter is incremented by the driver every time a transmit buffer for this terminal is transferred to the Mux interface card.
ZCOM Tables and Data Structures Interface Table Interface Table The interface table shown in Table 3-13 is a structure that has one instance for each Mux interface card defined in the TTGEN configuration file. It is primarily used by the DAM for controlling the backplane interaction with the Mux interface card. (zift_type) Table 3-13 Field Name Interface Table Field Description Size (Bytes) Field Type istime Time of ZMON control of card int 4 bc1_addr Level 1 Bus converter address uns.
ZCOM Tables and Data Structures Interface Table Table 3-13 Field Name Interface Table (Continued) Field Description Size (Bytes) Field Type imaxterms Max. # of terminals per card uns.short 2 ifname Firmware download file name char [256] 256 iffldt Download file link time uns.int 4 iffnmn Download file module name char [12] 12 ifrudt ROM label: ROM update time uns.
ZCOM Tables and Data Structures Interface Table Table 3-13 Field Name Interface Table (Continued) Field Description Size (Bytes) Field Type iportn Pointer to port configuration bytes Pointer 8 ifplook PTT lookup table pointer Pointer 8 ifcmdbp Current backplane command buffer pointer Pointer 8 ilock Pointer to IFT lock Pointer 8 ihpap Pointer to HPA entry Pointer 8 card Card type specific information Union of: bsp mmp 3616 18592 In the following definitions of the different fiel
ZCOM Tables and Data Structures Interface Table This field contains the I/O card address representing the I/O slot number that the MUX interface card is installed in. It is initialized by TTGEN from the slot value specified in the MUX statement of the TTGEN configuration file. INHPA - Interface HPA value (from TTGEN) The HPA value is built as follows: Table 3-14 Interface HPA Value Format INHPA 63-32 All 1’s (111...
ZCOM Tables and Data Structures Interface Table IFSTAT - interface card status This word indicates the current status of the Mux card. It is updated by the driver. Bit 15 indicates whether the card is usable (when set) or not (when cleared).
ZCOM Tables and Data Structures Interface Table Figure 3-6 Scheduler Event Flags ISCHDL 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 AC ST NB PA AC ST NB PA - Driver currently active Card has sent status transfer request ($STDT) Driver cannot get any free system buffers Pause after current event ITCNTR - Interface terminal counter The terminal counter is the actual number of terminals defined on this Mux interface card.
ZCOM Tables and Data Structures Interface Table This field contains the maximum number of ports supported by this specific ACC interface card. IMAXSUBC_PORT - Maximum number of subchannels per port. This is the maximum number of subchannels supported on each port of this ACC interface card. The minimum value of this field is 1 (e.g. 2/8-channel cards). IMAXSUBC_CARD - Maximum number of subchannels on card. This field contains the number of subchannels supported by this card.
ZCOM Tables and Data Structures Interface Table This is a 16-bit field refreshed by the DAM once every 10 seconds with the runtime information word from the Mux firmware. It contains the average percentage activity of the Mux interface for the previous 10 seconds and the type code of the Mux front panel connected. IFBOFF - Buffer pointer adjusted offset Contained with the interface table are buffers that are used for DMA transfers between the driver and the Mux card.
ZCOM Tables and Data Structures Interface Table These fields are used internally by the ZCOM subsystem. CARD - Interface card specific data structures (union) This field is a union which contains two structures. These structures hold information that are specific to the type of interface card associated with this IFT entry. The structure card.mmp is used if the IFT is associated with an 8-port PCI or E1/T1 interface card. Otherwise, the card.
ZCOM Tables and Data Structures Interface Table CARD.BSP has the following fields shown in Table 3-17. Table 3-17 Field Name CARD.BSP Structure Field Description Field Type Size (Bytes) itxlstx Express terminal list headers struct[8] 8*40 itxlsta High priority terminal list headers struct[8] 8*40 itxlstb Low priority terminal list headers struct[8] 8*40 iplimit Port unack TX limit (in bytes) uns.
ZCOM Tables and Data Structures Interface Table port. For the 4-port E1/T1 ACC cards, these arrays are indexed by a combination of port and subchannel. Specifically elements 0-31 represent port 0 and subchannels 0 to 31; elements 32-63 represent port 1 and subchannels 0 to 31, etc.
ZCOM Tables and Data Structures Interface Table ITXLSTX - Express transmit list headers (zptl_type) This field is an array of list headers for the express transmit requests associated with each port or subchannel of the Mux card. Each list header represents the head of a linked list of PTTs that have pending express transmit requests waiting to be sent to the Mux card. The list linkage is maintained through the PTTXLX pointer in each physical terminal table.
ZCOM Tables and Data Structures Interface Table The list headers in this array function identically to ITXLSTA only for the low priority transmit requests. A terminal may be linked to ITXLSTX, ITXLSTA and ITXLSTB all at the same time, if it has express, high, and low priority transmit requests in progress.
ZCOM Tables and Data Structures Interface Table ZCOM_IPSTAT_UND: The undefined bit. Being undefined is synonymous with being not configured. For a non-4-port card, this bit in ipstat indicates whether a port is defined or not. For a 4-port card, this bit in ipstat indicates whether a subchannel is defined or not. However, for defined/undefined status, we must also keep track of whether ports are defined or not.
ZCOM Tables and Data Structures Interface Table The out-of-transmit-buffers (XPS queue) bit. For a non-4-port card, indicates the status of ports. For a 4-port card, indicates the status of subchannels. The DAM maintains the port status to determine the usability of a port/subchannel. A port/subchannel is operating normally if the status value is zero. If it is out of transmit buffers, no new transmit data transfer will be initiated.
ZCOM Tables and Data Structures Interface Table The layout for the 4-channel E1/T1 ACC card is as follows: Table 3-20 31-30 ecode 92 4-Channel E1/T1 ACC Card Format 29-26 fmode 26-22 21-20 19-16 spare sclock spare ecode - Encoding modes sync - Sync mode select mode - Operating mode parity - Parity select xclock - Clock multiplier sclock - Clock source baud - Baud rate value pmode - Port mode select fmode - Frame mode select spare - Reserve, not used 15-11 pmode 10-0
ZCOM Tables and Data Structures Interface Table ISUBCH_BUF - Port subchannel configuration buffer (subchbuf_def) This array contains the subchannel configuration bytes for each port on the ACC E1/T1 4-port Mux card. The Subch statements in the Subchannel-Definition section of the TTGEN configuration file are used to define the initial values of this array. Each element of the array is associated with a single port on the Mux card. Each element can be dynamically configured by calling the zconfig routine.
ZCOM Tables and Data Structures Interface Table Each element of the subchannel specification array has the following structure: Table 3-23 31-30 spare Subchannel Specification Array Element Structure 29-24 ITBS 23-8 spare 7 INV 6-3 spare 2-1 mode ITBS - Individual Transmit Buffer Size INV - Inversion flag mode - Transmission mode spare - Reserved, not used (must be 0) 0 spare IFIRQBP, IRESPBP, ISTDTBP - DMA reply buffer pointers (char *) These fields point to the corresponding buffers k
ZCOM Tables and Data Structures Interface Table Mux card firmware. The Status buffer contains the data returned from a $STDT transaction. This data is updated into the physical terminal tables by the DAM. The actual area being used is offset by the number of bytes specified in IFBOFF. This area is accessed by the pointer set up in the corresponding pointer fields IFIRQBP, IRESPBP, ISTDTBP. These fields are not used for ACC E1/T1 cards.
ZCOM Tables and Data Structures Interface Table IFPLOOK - Physical terminal table lookup This table is used by the DAM during FIRQ processing to determine the physical terminal table address based on the port and terminal number passed back from the Mux interface. It is indexed by the value [(port number * 8) + terminal number] for the 2/8-channel NIO and EISA ACC cards. For the ACC E1/T1 and 8-Port PCI cards, it is simply indexed by the terminal number.
ZCOM Tables and Data Structures Interface Table Table 3-24 Field Name Optional E1/T1 Tunable Parameters (Continued) Field Description Field Type Size (Bytes) bquota Quota of buffers allowed for each subchannel uns.int 4 tracesize Firmware trace buffer size uns.int 4 traceopt Firmware trace option bits uns.int 4 spare1~3 Reserved, not used uns.int[3] 4*3 tsize Size of timer tables in bytes uns.
ZCOM Tables and Data Structures Response Records Response Records Response records are used to keep track of the issue-and-wait operations in the ZCOM subsystem. Currently, it is used for the send-with-wait (for example, zsend mode 8), port configuration (zport and zconfig routines), interface card control (zconfig), and remote API calls. When a program requests a issue-and-wait operation, the LDM allocates a spare response record from the pool, sets up the sleeping address, and puts the caller to sleep.
ZCOM Tables and Data Structures Response Records RPTYPE - Expected response type This field contains the type of response the waiter is expecting. The LDM sets up the response type when it initializes the record. This field is validated when a response is returned. Currently, it may contain one of the values in Table 3-26.
ZCOM Tables and Data Structures Response Records RPBUFQ - Response buffer queue When a response carries data in addition to just a status or error code, the data is stored in this queue temporarily. The data is retrieved by the waiting process when it resumes execution. Currently, only remote completion responses use this queue for data storage.
ZCOM Tables and Data Structures Queue Header Queue Header The queue header area contains the descriptor block for all the ZCOM subsystem queues. The first queue is used to link the free buffers in the buffer pool. Figure 3-7 Queue Header Area Queue Header 0 (Free Queue) Queue Header 1 … … Queue Header n Free Queue Header (zfqh_type), queue 0, basically is the same as the other buffer queues. However, its fields are viewed and used slightly differently from the other queues.
ZCOM Tables and Data Structures Queue Header Table 3-28 Queue Header Structure (zqhd_type) Field Name Field Description Field Type Size (Bytes) QNMSG Number of messages on queue uns.int 4 QLIMIT Max messages/bytes allowed on queue uns.int 4 QHEAD Pointer to first message on queue pointer 8 QTAIL Pointer to last message on queue pointer 8 QMMAX Historical max number of messages uns.int 4 QTMSG Total messages through queue uns.int 4 QBYTES Number of bytes on queue uns.
ZCOM Tables and Data Structures Queue Header is initialized from the Queue-Limit parameter in the TTGEN configuration file when the queue is initialized. The queue limit may be modified dynamically by calling the zsetql routine. QHEAD, QTAIL - Queue head and tail pointers (zbhd_type *) These are pointers to the first and last messages attached to this queue. If the queue is empty, these values are undefined. If the queue has only one buffer, then the values are equal.
ZCOM Tables and Data Structures Queue Header QFLAG - Queue flags This field contains some indicators which may affect the processing of a queue. The format is shown in Table 3-29.
ZCOM Tables and Data Structures Queue Header QFDATA - Queue function data QFUNC - Queue function These two fields have valid data only when the ZCOM_QFLAG_FUNC bit in qflag is set. They are set up by the setkfunc routine and contain a pointer to a kernel function and a 32-bit value for use in calling the function. Each is only used by the kernel so that a kernel function is called whenever data is added to the queue.
ZCOM Tables and Data Structures Data Buffer Pool Data Buffer Pool The data buffer pool is part of the ZCOM memory structure. The size of data buffer pool is defined in the TTGEN configuration file. The data buffer pool is a global resource within the ZCOM subsystem. Organization of Buffer Pool The buffer pool is a contiguous block of memory divided dynamically into a number of variable length buffers.
ZCOM Tables and Data Structures Data Buffer Pool of blocks in the pool (initially 2), the total number of bytes in the pool, and the number of accesses to the pool to get a memory buffer. The buffer pool structure is shown in Figure 3-8.
ZCOM Tables and Data Structures Data Buffer Pool Figure 3-8 Buffer Pool Layout (when first initialized) Free Queue Header List Head List Tail Block Block Pointer Pointer Dummy Free Buffer Dummy Used Flag Dummy Used Flag Buffer Flag Next Block Pointer Previous Block Pointer Buffer Flag Next Block Pointer Previous Block Pointer Buffer Flag Main Free Buffer Dummy Used Flag Dummy Used Flag Buffer Flag 108 Dummy Used Flag Dummy Used Flag Chapter 3
ZCOM Tables and Data Structures Data Buffer Pool Free Buffer Header Structure (zfbh_type) The buffer header contains information about the buffer as well as a linkage to the next buffer. (zbhd_type). See Table 3-30 and Table 3-31. Table 3-30 Field Name Free Buffer Header Structure (zfbh_type) Field Description Field Type Size (Bytes) BFFLAG System flags (length & status) uns.
ZCOM Tables and Data Structures Data Buffer Pool BFFLAG - Buffer flags The use of the memory pool is based around a buffer flag field that indicates the size of a memory block as well as containing a flag that indicates whether the block is currently in use. This field appears at the start and end of each buffer segment. This field is 32 bits long. The size of the buffer is always a multiple of 8-bytes (so each buffer is 64-bit aligned).
ZCOM Tables and Data Structures Data Buffer Pool These pointers are used to link all the free blocks within the memory pool, to form a circular list. The free queue contains the initial pointer to the first and last free block. The value in the pointer is the address of the buffer flag (i.e., the address of the next block pointer in the block). BFLEN - Buffer length in bytes (data portion) This field contains the usable memory size (in bytes) within the buffer.
ZCOM Tables and Data Structures Message Header Message Header In the buffer header (i.e., BFDATA pointer), there is a message header that describes the message type, the source and destination addresses, and the type of response expected from the message. The message header is the first 30 bytes of the buffer data area. When the data buffer is allocated, the initial data offset is chosen so that the message data starts on a specific boundary depending on its purpose (e.g.
ZCOM Tables and Data Structures Message Header Message ID Header (zmid_type) The Message ID Header contains information used for delivery of the message. See Table 3-34. Table 3-34 Field Name Message ID Header (zmid_type) Field Description Field Type Size (Bytes) MSTYPE Message type uns.char 1 MSRESP Message response code uns.char 1 MZDEST Destination ZCOM address struct 6 MZSRCE Source ZCOM address struct 6 MTAGW1 Message tag word 1 uns.short 2 MTAGW2 Message tag word 2 uns.
ZCOM Tables and Data Structures Message Header MSTYPE - Message type This field contains the message type. If bit 3 of the message type is set (ZCOM_MSTYPE_REMOTE (0x08)), then the message is remote. Notice that the remote message type maps onto the message type for a local terminal.
ZCOM Tables and Data Structures Message Header MSRESP- Response code The response code is used in two ways. Firstly, for message types 2, 4, 10, and 12 (send message), it indicates the type of response expected when this message is sent or delivered. Secondly, for other message types, it is the status of the completed message. Response code for message type 2 and 10 are shown in Table 3-36.
ZCOM Tables and Data Structures Message Header MTAGW1, MTAGW2 - Message tag words These are application defined tag words that are passed unaltered through the ZCOM subsystem with the message data. They are supplied in the zsend and zcntl calls and returned in the zread call. When a receive message is returned from a terminal, the tag words are set to zero.
ZCOM Tables and Data Structures Message Header This field contains the request code sent to or received from the Mux firmware on the interface card. The message request code values are shown in Table 3-39.
ZCOM Tables and Data Structures Message Header This tag parameter is used to carry protocol specific information from the application program to the protocol module on the Mux card and return information from the firmware to the driver or application program. MRQLEN - Data length This is the total length of the data to be sent, or the length of data received, in this message.
ZCOM Tables and Data Structures Message Header System Event Message (zevent_type) A System Event Message (SEM) is a special message generated by the ZCOM subsystem to represent an alarm condition or type of event that has occurred within the ZCOM subsystem. Applications may request that ZCOM deliver these events to a program ZLU by issuing a zevent_rcvr call. A SEM is returned to the application as a normal data message with a message type of ZCOM_MSTYPE_LSEM (5) or ZCOM_MSTYPE_RSEM (13).
ZCOM Tables and Data Structures Message Header This field will contain the ZCOM node number of the system that generated the event message. If the message type is ZCOM_MSTYPE_LSEM, this will contain the local ZCOM node number. SETIME - Time when the event occurred This field contains the Coordinated Universal Time (UTC) of when the event occurred. It is taken from the originating system at the time of the event.
ZCOM Tables and Data Structures Message Header This field contains a numeric value indicating the status change. If the value is zero, then there has been no change to the node’s status. If the value is +1, the node changed state from DOWN to UP. If the value is -1, the node changed state from UP to DOWN. HSTAT - Host link status change indicator This field is an array of four values, one for each potential link associated with NODE_NUM. Each entry indicates the status change of one link.
ZCOM Tables and Data Structures Message Header This event is generated whenever there is a change in the state of an ACC interface card. This includes notification of firmware failures (causes an automatic restart of the card), user initiated restarts, hardware failures, and for those systems that support it, the on-line addition, removal, or replacement of an ACC card. The event data is referenced using sedata.card.
ZCOM Tables and Data Structures Message Header ZcSE_CARD_FAIL_RESTART - the ACC card indicated by the iftno field is being restarted due to a firmware failure and must not be used until a ZcSE_CARD_RESTRT_CMPLT event is received. ZcSE_CARD_RESTRT_CMPLT - The ACC card indicated by the iftno field has been redownloaded and restarted. It can now be used by applications. Iftno - This is the ZCOM MUX number of the card that has changed state. Bus_addr_len - Number of bus addresses in the bus_addr[] field.
ZCOM Tables and Data Structures ZCOM Kernel Data ZCOM Kernel Data This is a kernel data structure shared by the LDM and DAM. Unlike the ZCOM subsystem memory tables (which are set up when ZCOM subsystem is started), this data structure is generated into the HP-UX operating system with the LDM and always exists even when the ZCOM subsystem is not started up. The kernel entry point for this data structure is Zcom which consists of four components, NCARD, HPATBL, SYS, and HP.
ZCOM Tables and Data Structures ZCOM Kernel Data Table 3-44 HPA Table Entries (Continued) Field Name Field Description Field Type Size (Bytes) resrvd2 Reserved for future use int 4 card_type The type of the ACC interface card int 4 resrvd4 Reserved for future use int 4 hlmpda Pointer to lower manager’s (DAM) PDA pointer 8 hpaift Pointer to ZCOM interface table pointer 8 hstatus Status of this entry uns.short 2 hactive Number of active requests uns.
ZCOM Tables and Data Structures ZCOM Kernel Data HPANO - HPA value of I/F card (zhpano_type) The HPA value is setup by the DAM when HP-UX creates an instance of the DAM for a particular Mux interface card. This field is used by the LDM to match the Mux interface cards defined in the TTGEN configuration file, to those actually configured in the hardware. The format of the field is shown in Table 3-45.
ZCOM Tables and Data Structures ZCOM Kernel Data HACTIVE - Number of active requests This field contains the number of pending inter-driver requests from the LDM to DAM. A non-zero value indicates some LDM requests are being processed by the DAM, hence deallocation of the driver resources is not allowed (i.e., driver unbinding). This feature is intended for the implementation of dynamic hardware reconfiguration in HP-UX. SX25_BRDN - Streams X.
ZCOM Tables and Data Structures ZCOM Kernel Data SYS The SYS structure (ZCOM system global information, zsys_type) contains software status information about the ZCOM subsystem. For example, it indicates whether ZCOM is running and when it was last started up. It is updated by the LDM based on requests from ZMON. Table 3-46 Field Name SYS structure (ZCOM system global information, zsys_type) Field Description Field Type Size (Bytes) STIME Time when status last changed uns.
ZCOM Tables and Data Structures ZCOM Kernel Data RESET state). If so, an error will be returned to the application program. This mechanism allows all sleeping ZCOM programs to be notified when the operational state of the ZCOM subsystem has changed. STATUS - Current ZCOM system status This field contains the current state of the ZCOM subsystem. The defined values are shown in Table 3-47.
ZCOM Tables and Data Structures ZCOM Kernel Data DEBUG - Debug level This field is used by the LDM to produce driver debug logs for its processing. Some LDM modules have embedded debug codes, which check this field to log debug messages. The format of this field is shown in Table 3-49. The values of the bits in the field are described in Table 3-50.
ZCOM Tables and Data Structures ZCOM Kernel Data MEMPTR, MEMSIZE -Kernel memory size pointers These are pointers to the size of kernel memory allocated by the LDM. The memory is used to hold ZCOM subsystem Memory Tables. In the current implementation, there is a fixed amount of memory defined in the kernel for use by the ZCOM subsystem, determined by the kernel zcom_mem_size tunable parameter defined at kernel build time. Hence, these fields are assigned to that part of memory.
ZCOM Tables and Data Structures ZCOM Kernel Data ZSINFO - ZCOM system information buffer This is a data structure set up by the LDM when ZCOM subsystem is started up. It contains information to be passed back to an application via zinit. Refer to the definition of zsinfo_type for its layout. HP The HP (Pointer to ZCOM system header) structure is a pointer to ZCOM subsystem header. It is set up by the LDM during ZCOM subsystem startup. The ZCOM subsystem memory tables are accessed through this pointer.
ZCOM Tables and Data Structures ZCOM Kernel Data LINFO The LINFO structure (Lock Information, struct zlinfo) contains the ZCOM locks used globally in the ZCOM subsystem. It is initialized by the LDM during system bootup. The locks are used to provide exclusive access to the sharable data structures in the ZCOM subsystem. The fields are described in Table 3-51.
ZCOM Tables and Data Structures ZCOM Kernel Data ZC_SLOCK - Super IFT spinlock This lock protects against deadlock situations while multiple IFTs need to be access simultaneously. A piece of code must obtain this lock first if it is going to lock multiple IFTs. Each of the above fields is a data structure (zlock_t) with the data fields shown in Table 3-52.
4 Chapter 4 ZCOM C I/F Library Routines 135
ZCOM C I/F Library Routines Introduction Introduction The ZCOM C interface library routines provide an application program interface to the ZCOM subsystem. These enable the application programmer to access to the ZCOM subsystem, transfer data, configure the system, check on the state of the ZCOM subsystem, etc. Applications should link in the archive library libzcom_c.a or the shared library libzcom_c.sl with their program to use these functions.
ZCOM C I/F Library Routines Introduction The following is a list of ZCOM C interface library routines: Initialization call zinit Chapter 4 -ZCOM library access initialization 137
ZCOM C I/F Library Routines Introduction Interface configuration calls zport -Datacomm port configuration zconfig -Dynamic system configuration ZLU configuration calls zclos -Delete program input ZLU zmapr -Set up ZLU mapping configuration zopen -Create ZLU program input queue zluopen -Open a ZLU for file system access zset_rcvr -Set up a program ZLU as receiver for a terminal ZLU zevent_rcvr -Set up a program ZLU as receiver for system event messages zsetql -Set buffer queue limit ztimr
ZCOM C I/F Library Routines Introduction zsend -Send data buffer to ZLU ZLU information calls ltfind -Find specific logical terminal in a group ptfind -Find specific physical terminal in a group zinfo -Get ZCOM table information zname -Find ZLU number from ZLU name zqsze -Read ZLU input queue size zget_shrcvr_list -Retreive a list of all the current shared receivers Utility routines Chapter 4 getdevice -Return ZCOM device definitions makezluname -Make a ZLU name with tty name suffix zco
ZCOM C I/F Library Routines Introduction ZLU Definition The zlu field of a parameter specifies the ZLU address. The checksum field of a parameter is a checksum used to verify the address of the message. All routine calls that specify ‘(with checksum)’ in the ZLU definition must have both fields defined correctly for successful processing. The checksum minimizes the possibility of messages being accidentally misdirected.
ZCOM C I/F Library Routines Man Pages Man Pages The C-I/F man pages are provided in this section. They are in alphabetical order in similar format as the online man pages. • • • • • • • • • • • • • • • • • • • Chapter 4 getdevice.3x ltfind.3x ltqdget.3x ltqdput.3x makezluname.3x ptfind.3x zclos.3x zcntl.3x zcomerror.3x zcomlname.3x zcomlog.3x zcomstatus.3x zconfig.3x zevent_rcvr.3x zget_shrcvr_list.3x zinfo.3x zinit.3x zltmg.3x zltmx.3x • • • • • • • • • • • • • • • • • • zltqueue.3x zltstore.3x zltup.
ZCOM C I/F Library Routines GETDEVICE (3X) GETDEVICE (3X) NAME getdevice – Read ZCOM device definitions SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int getdevice (dfile, dpp) char *dfile; zdev_type **dpp; DESCRIPTION Routine getdevice reads the ZCOM device file specified by the dfile parameter and loads the device definition entries into a memory table. The pointer to the device definition table is returned (see zdev type definition below).
ZCOM C I/F Library Routines GETDEVICE (3X) See the NOTES section below for more information on using this routine in a multi-threaded application.
ZCOM C I/F Library Routines GETDEVICE (3X) PARAMETERS RETURN VALUE NOTES dfile Pointer to the full path name of a binary zdgen device file. That is, the output file from the zdgen program. If a NULL is passed, it defaults to the file specified by the symbol ZCOM_DEVICE_FILE), which is currently defined as /opt/acc7cfg/zcomdevice in the include file /opt/acc/include/zcom/zcomsys.h dpp (Return param) Pointer to a data structure containing the full device table.
ZCOM C I/F Library Routines GETDEVICE (3X) char dpname[8]; } zdev_type; EXAMPLE #include #include int32 char zdev_type /* Protocol module name */ ierr; *dfile; *dp; ierr = getdevice (dfile, &dp); if (ierr < 0) { /* (error; user to check errno) */ } else { /* (success; ierr indicates number of device types) */ } FILES /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines GETDEVICE (3X) /opt/acc/cfg/zcomdevice Binary ZCOM device file created by ZDGEN, using the user-customizable ASCII file, /opt/acc/cfg/zcomdevice.txt. Refer to the section on ZDGEN in the Multiprotocol ACC Utilities Reference Guide for more details.
ZCOM C I/F Library Routines LTFIND (3X) LTFIND (3X) NAME ltfind – Find specific logical terminal in a group SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 ltfind (zap, laddr, llen, ibuf, len) zaddr_type char int32 char int32 DESCRIPTION *zap; *laddr; llen; *ibuf; len; Routine ltfind searches through the group linkage in the logical terminal table, for the logical terminal with the specified logical address.
ZCOM C I/F Library Routines LTFIND (3X) 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.
ZCOM C I/F Library Routines LTFIND (3X) struct { zltt_type char ltt; sys; ext[ZCOM_MAXLSIZE]; /* Max allowable extension */ For example, to access the fields: ltt.sys.ltname gives the terminal name ltt.ext[0] gives the 1st byte in table extension This allows <t to be used instead of ibuf in the ltfind call. EXAMPLE #include #include int32 zaddr_type char int32 char int32
ZCOM C I/F Library Routines LTFIND (3X) FILES SEE ALSO 150 /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).
ZCOM C I/F Library Routines LTQDGET (3X) LTQDGET (3X) NAME ltqdget – Retrieve data buffer in terminal data queue SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 ltqdget (zap, queue, ibuf, len, rlenp) zaddr_type uint32 char int32 int32 DESCRIPTION *zap; queue; *ibuf; len; *rlenp; Routine ltqdget retrieves the data message stored in the data queue of the logical terminal tables.
ZCOM C I/F Library Routines LTQDGET (3X) 152 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).
ZCOM C I/F Library Routines LTQDGET (3X) PARAMETERS zap ZCOM address of a terminal from which to get the data. queue Terminal data queue number (specifies which data queue is to be used). 0 - Sub-packet holding queue (reserved) 1 - Data holding queue A 2 - Data holding queue B 3 - Data holding queue C 4 - Data holding queue D ibuf (Return Param) On a successful return, the data is placed into this buffer. len Length in bytes of ibuf. rlenp (Return Param) Actual number of bytes returned in ibuf.
ZCOM C I/F Library Routines LTQDGET (3X) /* error return code */ } else { /* good return code */ } FILES SEE ALSO 154 /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).
ZCOM C I/F Library Routines LTQDPUT (3X) LTQDPUT (3X) NAME ltqdput – Store data buffer in terminal data queue SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 ltqdput (zap, queue, ibuf, len) zaddr_type uint32 char int32 DESCRIPTION *zap; queue; *ibuf; len; Routine ltqdput stores a data message in the data queue of the logical terminal tables. It links the message to the end of the specified queue.
ZCOM C I/F Library Routines LTQDPUT (3X) 156 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).
ZCOM C I/F Library Routines LTQDPUT (3X) PARAMETERS zap ZCOM address of the terminal ZLU to store data into. queue Terminal data queue number (specifies which data queue is to be used): 01234- Sub-packet holding queue (reserved) Data holding queue A Data holding queue B Data holding queue C Data holding queue D ibuf Data buffer to be stored. len Length in bytes of ibuf.
ZCOM C I/F Library Routines LTQDPUT (3X) FILES SEE ALSO 158 /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/zcomcal l.h ZCOM routine function prototypes (requires ANSI C compilation).
ZCOM C I/F Library Routines MAKEZLUNAME (3X) MAKEZLUNAME (3X) NAME makezluname – Make a ZLU name with TTY name suffix SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ char *makezluname (name) char *name; DESCRIPTION Routine makezluname constructs a ZLU name by merging the user-supplied name with the TTY suffix. The returned name is 7 characters long plus a terminating ’\0’.
ZCOM C I/F Library Routines MAKEZLUNAME (3X) TTY Name Returned Name console MYnsole Comment Trailing part of TTY name is used. 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.
ZCOM C I/F Library Routines MAKEZLUNAME (3X) For multi-threaded application, since all threads will be from the same TTY, if the threads use the same name parameter, the same ZLU name will be returned. This routine uses an internal static buffer for temporary storage of the returned name. The buffer is overwritten by each call. EXAMPLE #include #include
ZCOM C I/F Library Routines PTFIND (3X) PTFIND (3X) NAME ptfind – Find a physical terminal within a group SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 ptfind (zap, zskeyp, ibuf, len) zaddr_type zskey_type zptt_type int32 DESCRIPTION *zap; *zskeyp; *zptt; len; Routine ptfind provides special methods of accessing terminals on the same MUX and port. The zap->zlu parameter is the ZLU of a terminal on a particular MUX and port.
ZCOM C I/F Library Routines PTFIND (3X) Method 2: Retrieve the next terminal whose table has a sequence of matching bytes. This method compares the contents of the physical terminal tables within a group, and locates the one that matches a byte sequence. In addition to the data buffer, table location and number of bytes to be compared, the caller also specifies a terminal ZLU within the group to be searched.
ZCOM C I/F Library Routines PTFIND (3X) Method 3: Retrieve the next terminal whose table has a sequence of matching bit patterns. This mode is similar to Method 2 except that the caller also specifies a mask buffer, which is used to mask some unused bits in the physical terminal table before comparing with the specified data. The mask buffer is AND’ed with the table content before comparison. Hence, the mask buffer should contain zeros for those unused bits and ones for those bits to be compared.
ZCOM C I/F Library Routines PTFIND (3X) PARAMETERS zap ZCOM address of the terminal. It can be any terminal ZLU within the group to be searched. If using method 1, only its MUX number is used (its port number, hence its group, may be different from the target terminal). zskeyp ptfind search key. The search key is set up by the caller program before this routine is called. It consists of a search mode, which indicates the method to be used and the data (mode dependent) used in searching.
ZCOM C I/F Library Routines PTFIND (3X) else { /* good return code */ } 166 Chapter 4
ZCOM C I/F Library Routines PTFIND (3X) FILES Chapter 4 /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).
ZCOM C I/F Library Routines ZCLOS (3X) ZCLOS (3X) zclos - Delete program input ZLU NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zclos (zap) zaddr_type *zap; DESCRIPTION Routine zclos closes the program ZLU set up by the zopen call and returns the ZLU back to the system for reuse. This call should normally always occur before a program terminates.
ZCOM C I/F Library Routines ZCLOS (3X) 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 za p RETURN VALUE ZCOM address to be returned to the system. Routine zclos 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 #include int32 zaddr_type
ZCOM C I/F Library Routines ZCNTL (3X) ZCNTL (3X) zcntl – Send control message to terminal ZLU NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zcntl (zap, mode, rcode, mhp, ibuf, len, rstat) zaddr_type uint32 uint32 zmhd_type char int32 int32 DESCRIPTION *zap; mode; rcode; *mhp; *ibuf; len *rstat; Routine zcntl is used to change the state of a terminal or to send a protocol dependent control message to a terminal ZLU.
ZCOM C I/F Library Routines ZCNTL (3X) 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.
ZCOM C I/F Library Routines ZCNTL (3X) 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.
ZCOM C I/F Library Routines ZCNTL (3X) 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 (Return Param) Return status. Only used for requests issued with ‘wait’, i.e. mode = ZMODE_WAIT.
ZCOM C I/F Library Routines ZCNTL (3X) 6 174 Terminal Option Word Chapter 4
ZCOM C I/F Library Routines ZCNTL (3X) 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 0 RTYP Ext. Req. Type 2 Port Number Subchannel Number 4 Group Poll Code Device Poll Code 6 Group Select Code Device Poll Code 8 Terminal Option Word 1 0 Special Terminal Configuration 2 1 0 Terminal Type (Variable Length, max.
ZCOM C I/F Library Routines ZCNTL (3X) EXAMPLE #include #include int32 zaddr_type uint32 uint32 zmhd_type char int32 int32 ierr; zaddr; mode; rcode; zmhd; ibuf[size]; /* where size is user-determined; must be >= len */ len; 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.
ZCOM C I/F Library Routines ZCNTL (3X) /opt/acc/include/zcom/zcomcall.h SEE ALSO Chapter 4 ZCOM routine function prototypes (requires ANSI C compilation). zcomstatus(3X), zconfig(3X), zread(3X), zsend(3X), zopen(3X).
ZCOM C I/F Library Routines ZCOMERROR (3X) ZCOMERROR (3X) zcomerror – Return a formatted ZCOM error message NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ char int32 *zcomerror(err) err; Description Routine zcomerror returns a character string containing error text associated with an error number returned through use of the ZCOM library calls.
ZCOM C I/F Library Routines ZCOMERROR (3X) PARAMETERS err Error number. NOTES This routine reads a message file for the error message text. It uses the file zerrmsg.msg in /opt/acc/msg (ZCOM_MESSAGE_PATH). If not found, it uses the default message file default.msg. RETURN VALUE Routine zcomerror returns a character string corresponding to the error number passed in as a parameter (err).
ZCOM C I/F Library Routines ZCOMERROR (3X) EXAMPLE #include #include char int32 *errmsg; err; /* Returned message string */ errmsg = zcomerror (err); FILES 180 /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.
ZCOM C I/F Library Routines ZCOMLNAME (3X) ZCOMLNAME (3X) zcomlname – Set up originator name for log messages NAME SYNOPSIS #include #include void char /* if compiled with ANSI C (recommended) */ zcomlname (name) *name; DESCRIPTION Routine zcomlname sets up the originator (program) name to be used by the ZCOM message log system. Subsequent calls to zcomlog will log messages with this specified program name. Refer to zcomlog(3x) for more information on log messages.
ZCOM C I/F Library Routines ZCOMLNAME (3X) PARAMETERS nam e Name for the log message (string, 6 bytes) RETURN VALUE Routine zcomlname has no return value. NOTES In a multi-threaded application, zcomlname is to be called only once by any one of the threads. It sets up the logging program name for the subsequent calls to zcomlog for all threads. If it is called again, the new program name is effective for the subsequent log messages. EXAMPLE #include #include
ZCOM C I/F Library Routines ZCOMLOG (3X) ZCOMLOG (3X) zcomlog – Add a message to the ZCOM log file NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ void zcomlog (error, msgno, narg [, desc, arg]) uint32 int32 uint8 uint32 uint32 error; msgno; narg; desc; arg; DESCRIPTION Routine zcomlog creates a log record and passes it to the ZCOM message log system, where the logged messages will be retrieved and processed by the ZMLOG program.
ZCOM C I/F Library Routines ZCOMLOG (3X) 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.
ZCOM C I/F Library Routines ZCOMLOG (3X) PARAMETERS error Error code to be logged (unsigned int). The error code is displayed as a 5-digit unsigned value (ranges from 00000 to 99999) in the error message log file. msgno ID number of the message to be logged (signed int). narg Number of arguments to be logged with the message (positive int). desc Argument descriptor used to describe the “type” of the argument which follows.
ZCOM C I/F Library Routines ZCOMLOG (3X) 3. In a multi-threaded application, zcomlname is to be called only once by any one of the threads. It sets up the logging program name for the subsequent calls to zcomlog for all threads. If it is called again, the new program name is effective for the subsequent log messages.
ZCOM C I/F Library Routines ZCOMLOG (3X) EXAMPLE #include #include uint32 int32 uint32 uint32 char int error; msgno; desc; arg; p1; p2; error = 1730; msgno = 150; /* Msg text = "This is an error. P1 = %c P2 = %d". */ p1 = ’a’; p2 = 37; zcomlog (error, msgno, 2, ZCOM_AT_CHAR, p1, ZCOM_AT_INT, p2); FILES SEE ALSO Chapter 4 /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines ZCOMSTATUS (3X) ZCOMSTATUS (3X) zcomstatus – Return a formatted ZCOM status or error message NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ char *zcomstatus (req, stat) int32 int32 req; stat; DESCRIPTION Routine zcomstatus returns a ZCOM status message string corresponding to a specific status code. The return character string has a length of 31 bytes maximum, plus a terminating zero.
ZCOM C I/F Library Routines ZCOMSTATUS (3X) PARAMETERS re q Request code (from the zread header, zmhd ) st at Status (ZCOM error code if < 0) NOTES This routine reads a message file for the status message text. It uses the file zstatmsg.msg in /opt/acc/msg (ZCOM_MESSAGE_PATH). If not found, it uses the default message file default.msg. RETURN VALUE Routine zcomstatus returns a message string, corresponding to either the ZCOM status if stat is non-negative, or the ZCOM error if stat is negative.
ZCOM C I/F Library Routines ZCONFIG (3X) ZCONFIG (3X) zconfig – ZCOM Dynamic System Configuration (DSC) NAME SYNOPSIS #include #include /* If compliled with ANSI C (recommended) */ int32 zconfig (zap, mode, node, cdata, rdata) zaddr_type *zap; uint32 mode; uint32 node; zconfig_type *cdata; zcfgret_type *rdata; DESCRIPTION Routine zconfig provides a general purpose mechanism for configuring a ZCOM system dynamically, i.e.
ZCOM C I/F Library Routines ZCONFIG (3X) Threads Considerations PARAMETERS This routine may be called from multi-threaded application using the POSIX (1003.1c) kernel threads API package. It has the following characteristics when called by 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.
ZCOM C I/F Library Routines ZCONFIG (3X) This is the node number of the remote (or local) ZCOM system where the configuration is to take place. If zero is specified, it is the local system. Note that the node parameter must specify the local system with this release (except for the Port Configuration functions) cdata Configuration data. This points to a data structure containing all the information necessary for the configuration. See below for a description of this structure.
ZCOM C I/F Library Routines ZCONFIG (3X) uint16 card_addr; /* Card address of new hardware */ uint16 itype; /* Interface card type */ char fname[ZCOM_MAXFNAME]; /* Firmware filename */ } setcard; /* Request=Interface Configuration */ struct { uint16 iftno; /* Interface card number */ uint8 bc1_addr; /* 1st level bus converter addr */ uint16 bc_addr; /* Bus converter addr of hardware */ uint16 card_addr; /* Card address of new hardware */ uint16 itype; /* Interface card type */ zcfg_lookup_t cfglt; /* Confi
ZCOM C I/F Library Routines ZCONFIG (3X) Field header.config specifies the type of configuration. The interpretation of the header.action and data fields vary depending on the configuration type. Allowed values are: ZCOM_ZCONFIG_CNTL - DSC Control ZCOM_ZCONFIG_SYS - System Configuration ZCOM_ZCONFIG_CARD - Interface Configuration ZCOM_ZCONFIG_PORT - Port Configuration ZCOM_ZCONFIG_TERM - Terminal Configuration ZCOM_ZCONFIG_PORTSC - Port and Subchannel Configuration Field header.
ZCOM C I/F Library Routines ZCONFIG (3X) } portret; struct { zaddr_type int32 } termret; struct { uint32 uint32 uint32 int32 } portscret; } data; } zcfgret_type; zaddr; error; /* Terminal ZLU */ /* Return ZCOM error */ iftno; portno; subchno; status; /* /* /* /* Interface card number */ Port number */ Subchannel number */ Return status */ The header is the same as in the configuration data. Its fields are returned without change for the caller to identify the response.
ZCOM C I/F Library Routines ZCONFIG (3X) Configuration Data header.config ZCOM_ZCONFIG_CNTL (DSC Control) header.action ZcENABLE_DSC (1) - Enable DSC access ZcDISABLE_DSC (2) - Disable DSC access ZcDSC_SEND_RECFG (3) - Broadcast reconfiguration complete system event message. header.tag1, header.tag2 Any values.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setctl.cfg_class Caller supplied type of reconfiguration. There is one predefined configuration class, ZcCLASS_X25. This event should be generated whenever an X.25 link is dynamically configured. This includes modifying the number and/or type of Virtual Circuits and creating or deleting an X.25 level 2 (LAPB) ZLU. If the ZCOM Subsystem is used with X25/9000 and x25init is executed, this event will be generated if the configuration for an X.25 link is modified.
ZCOM C I/F Library Routines ZCONFIG (3X) ZcDSC_SET_PROG_QLIMIT (2) - Set default program queue limit. ZcDSC_SET_TERM_XMIT_QLIMIT (3) - Set default terminal transmit queue limit. ZcDSC_SET_TERM_UNACK_QLIMIT (4) - Set default terminal “unack” queue limit. ZcDSC_SET_PORT_XMIT_LIMIT (5) - Set default port transmit limit. header.tag1, header.tag2 Any values. data.setsys.sysname New runtime ZCOM system name. This field is used for action 1 only. data.setsys.qlimit New default queue limit.
ZCOM C I/F Library Routines ZCONFIG (3X) Action ZcDSC_CREATE_IFT (2) allocates the internal data structures required for a new interface card. That is, it creates a new Interface Table entry. Action ZcDSC_START_CARD (3) starts up an interface. This initializes the hardware, the ports and terminals according to the configuration kept in the ZCOM tables. In functionality, it is identical to a zmon restart command. Action ZcDSC_HALT_CARD (4) halts the hardware and stops new requests to the ACC interface card.
ZCOM C I/F Library Routines ZCONFIG (3X) Configuration Data header.config ZCOM_ZCONFIG_CARD (interface configuration) header.action ZcDSC_CHNG_FW_FILE (1) - Modify interface firmware file name ZcDSC_CREATE_IFT (2) - Create a new interface table ZcDSC_START_CARD (3) - Startup (e.g. restart) an interface card ZcDSC_HALT_CARD (4) - Disable an interface ZcDSC_STOP_CARD (5) - Shutdown (e.g. disable and flush) an interface card DSC_REASSIGN_IFT (6) - Link an interface to different hardware header.
ZCOM C I/F Library Routines ZCONFIG (3X) Response Data data.cardret.iftno This is the interface card number as in the configuration data. It indicates the interface table entry that was created or modified. data.cardret.error This is the returned interface configuration error: 0 - No error (successful) < 0 - ZCOM error code The error message text may be fetched using \fIzcomerror\fR(3X) with a non-zero error code. Port Configuration There are 8 port configuration actions.
ZCOM C I/F Library Routines ZCONFIG (3X) Configuration Data header.config ZCOM_ZCONFIG_PORT (port configuration) header.action ZcDSC_ALL_PARMS (1) - Set all operating modes (Configuration, Baud Rate and Port) ZcDSC_CFG_MODE (2) - Set Configuration mode only (Ecode, Sync, Mode, Parity) ZcDSC_BAUD_RATE (3) - Set Baud Rate mode only (X.Clk, S.
ZCOM C I/F Library Routines ZCONFIG (3X) Unused spare field. For data alignment. data.setport.cnfg Configuration data (32 bits). This field is used for actions 1 to 4 only. The content is dependent on the specific hardware being configured. It contains the following information: For the Z7200A, Z7400A, Z7340A, Z7350A cards: 15 14 13 12 Ecode Sync Pmode Pmode2 Ecode Sync Mode Chapter 4 11 Mode 10 9 8 Parity 7 6 X.
ZCOM C I/F Library Routines ZCONFIG (3X) Parity X.Clk S.Clk Value Parity select 00 No Parity 01 Odd parity 10 No Parity 11 Even parity Value Clock multiplier 00 X1 01 X 16 10 X 32 11 X 64 Value Clock source 00 External clock 01 Internal clock from Baud Rate Generator (BRG) 10 X.21 clock source 11 DPPL output (must use BRG as source) The baud rate is split between two 4-bit parameters (for compatibility reasons). If the Baud 1 parameter is 0, then Baud 2 is used.
ZCOM C I/F Library Routines ZCONFIG (3X) Baud 2 Pmode Chapter 4 0001 300 1001 38,400 0010 600 1010 48,000 0011 1,200 1011 57,600 0100 2,400 1100 76,800 0101 4,800 1101 64,000 0110 9,600 1110 128,000 0111 14,400 1111 256,000 Value Rate Value Rate 0000 150 1000 768,000 0001 56,000 1001 1,024,000 0010 153,600 1010 1,228,800 0011 307,200 1011 1,536,000 0100 192,000 1100 1,544,000 0101 614,400 1101 2,048,000 0110 384,000 1110 Reserved 0111 512,000
ZCOM C I/F Library Routines ZCONFIG (3X) 00 01 V.35 (Z7340A and Z7350A only) 00 10 RS-449 (Z7340A and Z7350A only) 00 11 V.36 (Z7340A and Z7350A only) All other values Reserved For the Z7300A (E1/T1) card: 15 14 Ecode 13 12 FMode Pmode Ecode Fmod e 206 11 10 9 0 0 8 7 6 5 Fsyn c S.
ZCOM C I/F Library Routines ZCONFIG (3X) Fsync S.Clk TxAtt Pmod e Chapter 4 0110 Transparent (voice) mode Value Other port for clock synchronization 00 Port 0 01 Port 1 10 Port 2 11 Port 3 Value Clock source 00 External clock (slave) 01 Internal clock (master) 10 Clock from other port (specified in Fsync) 11 Undefined Value T1 Transmit Attenuation (Z7330B only) 00 0 dB 01 -7.5 dB 10 -15 dB 11 -22.
ZCOM C I/F Library Routines ZCONFIG (3X) ... 0100 Reserved 0101 E1 twisted pair DB9 120 ohm 0110 E1 coax BNC 75 ohm 0111 T1 twisted pair RJ45 100 ohm 1000 Loopback Mode (Tristate) 1001 E1 twisted pair RJ45 100 ohm 1010 T1 twisted pair DB9 120 ohm 1011 T1 coax BNC 75 ohm 1100 Reserved ... QD 1111 Reserved 1= On Fast link-down option Makes the line go down whenever loss of T1/E1 frame synchronization is detected by the FALC.
ZCOM C I/F Library Routines ZCONFIG (3X) T1/ESF PRMs transmitted as “carrier”. The performance report messages transmitted in T1/ESF mode contain an address which indicates whether the ACC is a “network” or “user” device. By default the ACC is a “user” device. NP 1= On T1/ESF performance report messages suppressed This option suppresses the transmission of performance report messages in T1/ESF mode. LH 1= On Long-haul mode (Z7330B only) Enables the receive equalization and high power transmit line.
ZCOM C I/F Library Routines ZCONFIG (3X) data.portret.iftno data.portret.portno These are the interface and port numbers as supplied in the original configuration data (request). They indicate the interface and port whose configuration has been modified. data.portret.status Completion status returned from port configuration: < 0 - Standard ZCOM error. PT_OK (0) - No error (successful). PT_INV_PORT (1) - Port number out of range. PT_BAD_PARM (2) - Bad parameter.
ZCOM C I/F Library Routines ZCONFIG (3X) Port Subchannel Configuration The port subchannel configuration is only valid for the E1/T1 interface. There are 12 port configuration actions. Actions ZcDSC_ALL_PARMS, ZcDSC_CFG_MODE, ZcDSC_BAUD_RATE, ZcDSC_PORT_MODE, ZcDSC_SET_TIMESLOTS and ZcDSC_SET_SUBC_SPECS configure the datacomm ports and/or subchannels on the MUX E1/T1 interface card.
ZCOM C I/F Library Routines ZCONFIG (3X) Action ZcDSC_DISABLE_SUBC disables a subchannel putting it into an inoperative state. All linked terminal ZLUs are marked disabled without actually sending a disable request to the interface card. This is to avoid a “hung” terminal disable request due to a hardware failure on a subchannel. This action is designed to isolate a subchannel that has failed from the ZCOM system.
ZCOM C I/F Library Routines ZCONFIG (3X) Configuration Data header.config ZCOM_ZCONFIG_PORTSC (port and subchannel configuration) header.action ZcDSC_ALL_PARMS (1) - Set all operating modes (Configuration, Baud Rate and Port) ZcDSC_CFG_MODE (2) - Set Configuration mode only (Ecode, Sync, Mode, Parity) ZcDSC_BAUD_RATE (3) - Set Baud Rate mode only (S.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setportsc.rcode This field is used for actions ZcDSC_ALL_PARMS, ZcDSC_CFG_MODE, ZcDSC_BAUD_RATE, ZcDSC_PORT_MODE, ZcDSC_SET_TIMESLOTS and ZcDSC_SET_SUBC_SPECS only. Values are: 1 - Use configuration in interface table 2 - Use data in field data.setportsc.ptcfg data.setportsc.ptcfg Pointer to the port and subchannel configuration data of which the data structure zptcfg_t is defined in /opt/acc/include/zcom/zcomsys.h. data.setportsc.
ZCOM C I/F Library Routines ZCONFIG (3X) A RTI (Receive Timeslot Inhibit) bit value of ‘1’ causes all data received in this timeslot to be ignored. The subchannel does not process inbound data for this timeslot. The Rxcv and Txmit subch nmber fields associate the specified subchannel number with the Transmit and Receive timeslot, respectively. That is, tmsl[3] is used to specify which subchannel(s) will be using timeslot 3 for transmitting and receiving data.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setportsc.ptcfg->ptinfo.subchb.spec[ ] Subchannel specification data: used for actions ZcDSC_ALL_PARMS or ZcDSC_SET_SUBC_SPECS only. Up to 32 subchannel specifications are allowed. For action ZcDSC_ALL_PARMS, all subchannels are configured. For action ZcDSC_SET_SUBC_SPECS only subchannel entries with the UPD bit set are configured.
ZCOM C I/F Library Routines ZCONFIG (3X) Response Data data.portscret.iftno, data.portscret.portno, data.portscret.subchno These are the interface, port number and subchannel numbers as supplied in the original configuration data (request). They indicate the interface, port and subchannel whose configuration has been modified. data.portscret.
ZCOM C I/F Library Routines ZCONFIG (3X) The error or status message text may be fetched using zcomstatus (3X) with req = ZCOM_MRQCODE_PORT (or 14) and the return status. Note that status codes PT_BAD_BAUD, PT_ILL_SCLK, PT_ILL_PMODE, and PT_BAD_PORT imply the associated port is now inoperative. Another port configuration request must be performed to recover it.
ZCOM C I/F Library Routines ZCONFIG (3X) Terminal Configuration There are 5 terminal configuration actions. They are for altering various internal linkages and terminal tables in the ZCOM runtime system memory. Action ZcDSC_CREATE_LTT_PTT (1) creates a simple terminal that has one Logical Terminal Table (LTT) and one Physical Terminal Table (PTT). NOTE For this new ZCOM terminal, zconfig() allocates data structures in the kernel for ZCOM drivers to access.
ZCOM C I/F Library Routines ZCONFIG (3X) header.action ZcDSC_CREATE_LTT_PTT (1) - Create a new terminal (LTT and PTT) ZcDSC_CREATE_LTT_ON_PTT (2) - Create a new LTT on an existing PTT ZcDSC_CLEAR_TERM (3) - Clear connection to an existing terminal ZcDSC_DELETE_TERM (4) - Delete an existing terminal ZcDSC_MOVE_TERM (5) - Move an existing terminal to another port header.tag1, header.tag2 Any values.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setterm.zaddr ZLU of the related terminal. The “node” field is not used. For action 1 and 2, if ZLU is non-zero, it must be an unassigned one and ZLU checksum is not necessary. If ZLU is zero, the system chooses an arbitrary (unused) one. For actions ZcDSC_CLEAR_TERM, ZcDSC_DELETE_TERM, and ZcDSC_MOVE_TERM, the ZLU must be defined and the ZLU checksum must be valid. data.setterm.daddr ZLU of the destination terminal.
ZCOM C I/F Library Routines ZCONFIG (3X) Logical terminal information. This contains the logical terminal information of the newly created terminal. Only the user maintainable fields (i.e. “ltaddr” and the following fields) are copied to the new logical terminal table. The other fields are ignored. This field is needed for actions ZcDSC_CREATE_LTT_PTT and ZcDSC_CREATE_LTT_ON_PTT only. data.setterm.ptt Physical terminal information.
ZCOM C I/F Library Routines ZCONFIG (3X) Response Data data.termret.zaddr This is the terminal ZLU which has been successfully created or modified. For actions ZcDSC_CREATE_LTT_PTT and ZcDSC_CREATE_LTT_ON_PTT, it is the newly created terminal ZLU with the correct checksum. data.termret.error This is the returned terminal configuration error: 0 - No error (successful) < 0 - ZCOM error code > 0 - zcntl() firmware status code NOTES 1.
ZCOM C I/F Library Routines ZCONFIG (3X) unsigned int set0_2 : 4; /* Reserved, must be 0 */ unsigned int pmode : 4; /* Port mode */ unsigned int set0_3 : 12; /* Reserved, must be 0 */ } e1t1_bits; int32 pcval; /* Must be signed, -1 means bad config */ uint8 pconfig[4]; /* 4 configuration bytes */ } zpconf_type; 3. While clearing a terminal (Terminal Configuration action ZcDSC_CLEAR_TERM), the terminal unacknowledged transmit queue is also flushed.
ZCOM C I/F Library Routines ZCONFIG (3X) FILES SEE ALSO Chapter 4 /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). zsetql(3X), zcntl(3X).
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) ZEVENT_RCVR (3X) NAME zevent_rcvr – Set up a program ZLU to receive ZCOM alarms and events SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int zevent_rcvr (rzap, action, eclass, einfop) zaddr_type int uint32 Zclinfo_type *rzap; action; eclass; *einfop; DESCRIPTION Routine zevent_rcvr is used to set up a program to receive ZCOM alarm and system event messages.
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) Chapter 4 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).
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) PARAMETERS rzap ZCOM address of the receiver program (required). action Type of action to perform (required). ZcDELETE_EVENT - Remove the linkage for the indicated event classes. That is, those event classes will no longer be delivered to the program queue specified by the rzap parameter. Events that have already been queued prior to this call are not deleted.
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) einfop This data structure contains any event class specific information needed to carry out the action specified. Some of this information is optional, some of it is required (depending on the action and eclass values). The fields in this data structure are listed below with their dependent class types given in parenthesis. src_node (ZcNODE_STATUS) - This is the node that should be used to detect the node status changes. It can be the local or a remote node.
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) NOTES When an Application program issues a zread call, it can differentiate the type of information it is receiving by looking at the type of the message. ZCOM Event messages will return a message type of 5 (ZCOM_MSTYPE_LSEM) for a local system event, and a message type of 13 (ZCOM_MSTYPE_RSEM) for a remote system event. The difference between local and remote event messages is where the event was generated.
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) RETURN VALUE Chapter 4 Routine zevent_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.
ZCOM C I/F Library Routines ZEVENT_RCVR (3X) EXAMPLE #include #include int zaddr_type int uin32 Zclinfo_type ierr; rzap; action; eclass; cinfo; if (ierr = zevent_rcvr (&rzap, action, eclass, &cinfo)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO 232 /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines ZGET_SHRCVR_LIST (3X) ZGET_SHRCVR_LIST (3X) NAME zget_shrcvr_list – Get list of current shared receivers SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zget_shrcvr_list (zap, mode, mlen, zrcvrs) zaddr_type uint32 int32 zaddr_type DESCRIPTION *zap; mode; mlen; zrcvrs[]; Routine zget_shrcvr_list is used to retrieve the contents of a linked list of shared receivers from the ZCOM subsystem tables.
ZCOM C I/F Library Routines ZGET_SHRCVR_LIST (3X) fork unsafe It cannot be called by a child process after fork(2) but before exec(2). See the NOTES section below for more information on using this routine in a multi-threaded application. PARAMETERS zap ZCOM address pointer. The uses of node, zlu and zcs depend on the specified mode. But in general this is used to select the specific table entry from which you want the shared receivers list. mode Specifies which shared receiver list to return.
ZCOM C I/F Library Routines ZGET_SHRCVR_LIST (3X) RETURN VALUE Routine zget_shrcvrs_list 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 #include int32 int32 uint32 zaddr_type zaddr_type mlen */
ZCOM C I/F Library Routines ZINFO (3X) ZINFO (3X) NAME zinfo – Get ZCOM table information SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zinfo (zap, mode, ibuf, len) zaddr_type *zap; unit32 mode; char *ibuf; int32 len; DESCRIPTION Routine zinfo is used to retrieve the contents of various ZCOM subsystem tables.
ZCOM C I/F Library Routines ZINFO (3X) PARAMETERS zap ZCOM address pointer. The node field is used to indicate from which node to retrieve the information. The uses of zlu and zcs depend on the specified mode.
ZCOM C I/F Library Routines ZINFO (3X) The returned logical terminal table (mode = ZcLTT_TBL) consists of the basic table and the logical terminal table extension (the extension size is configurable in the TTGEN configuration file). The size of this buffer should be large enough to hold the required information. NOTES ATTENTION Note that this call returns the contents of the internal tables used to implement the ZCOM subsystem.
ZCOM C I/F Library Routines ZINFO (3X) /opt/acc/include/zcom/zcomcall.h Chapter 4 ZCOM routine function prototypes (requires ANSI C compilation).
ZCOM C I/F Library Routines ZINIT (3X) ZINIT (3X) zinit – ZCOM routine initialization NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zinit zsinfo_type DESCRIPTION (sip) *sip; Routine zinit initializes the access to the ZCOM system and sets up the global variables for use by the other ZCOM routines. Therefore, it must be called before any other ZCOM routines are used. This routine also returns some ZCOM system information.
ZCOM C I/F Library Routines ZINIT (3X) PARAMETERS sip (Return Param) ZCOM system information data structure containing the following fields: sizrev ZCOM software revision code (4 digits). sinode ZCOM system local node number. sinzlu Total number of ZLU tables in the ZCOM system. sinltt Total number of Logical Terminal Tables in the ZCOM system. sinptt Total number of Physical Terminal Tables in the ZCOM system. sinift Total number of Interface Tables in the ZCOM system.
ZCOM C I/F Library Routines ZINIT (3X) 4. In a multi-threaded application, if this routine is called the second time by a thread while some ZCOM APIs are in-progress in the other threads, the access to the ZCOM system will be re-initialized. The in-progress APIs will detect this and ‘retry’ internally. This is handled automatically and is transparent to the application. RETURN VALUE Routine zinit returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.
ZCOM C I/F Library Routines ZLTMG (3X) ZLTMG (3X) zltmg – Move a logical terminal between groups NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zltmg (zap, nap) zaddr_type zaddr_type DESCRIPTION *zap; *nap; Routine zltmg moves the logical terminal associated with a terminal ZLU to a new group of logical terminals designated by another terminal ZLU. The first terminal must not be the only terminal linked in its existing group.
ZCOM C I/F Library Routines ZLTMG (3X) PARAMETERS NOTES zaddr Terminal to be moved nzaddr A group member of the new group In the ZCOM subsystem, a group of logical terminals may be defined to link to a single physical terminal. This routine allows a logical terminal to be moved from one terminal group to another, thus all its physical input/output may be handled by a different physical device. This call is intended for advanced ZCOM programmers, and should be used with care.
ZCOM C I/F Library Routines ZLTMX (3X) ZLTMX (3X) zltmx – Control logical terminal multiplexing NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zltmx (zap, mode) zaddr_type int32 *zap; mode; DESCRIPTION Routine zltmx is used to enable or disable the multiplexing of logical terminals. This routine allows dynamic control of the ZCOM_LTFLAG_OMX and ZCOM_LTFLAG_IMX logical terminal flag bits.
ZCOM C I/F Library Routines ZLTMX (3X) PARAMETERS zap ZCOM address. mod e Multiplexing control mode ZcENB_OUTB_MLTPLXG (1) - Enable outbound multiplexing ZcENB_INB_MLTPLXG (2) - Enable inbound multiplexing ZcDSB_OUTB_MLTPLXG (3) - Disable outbound multiplexing ZcDSB_INB_MLTPLXG (4) - Disable inbound multiplexing NOTES For a more detailed description of the multiplexing facilities available under ZCOM, see the section of the manual under the heading “ZCOM Message Handling”.
ZCOM C I/F Library Routines ZLTMX (3X) FILES Chapter 4 /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).
ZCOM C I/F Library Routines ZLTQUEUE (3X) ZLTQUEUE (3X) zltqueue – Logical data queue allocation NAME SYNOPSIS #include #include /* if compliled with ANSI C (recommended) */ int32 zltqueue (appln, label, queuep) uint32 char uint32 appln; *label; *queuep; DESCRIPTION Routine zltqueue requests a data queue in the logical terminal tables for terminals of a specific application number. There is currently a maximum of 4 queues.
ZCOM C I/F Library Routines ZLTQUEUE (3X) PARAMETERS NOTES appln Application number of terminal group. label Queue label name. queuep (Return Param) Data queue number (or ZCOM error, if negative) The data queue returned should only be used for terminals within the specified application group (there is NO queue ownership validation when it is used in ltqdget and ltqdput). An application value of zero means terminals in ALL application groups.
ZCOM C I/F Library Routines ZLTQUEUE (3X) Appln Progra m Appl n Nmb r F 30 USAGE 3 4 <-- same appln, diff usage G 30 USAGE 4 error <-- no more queues for apln 30 Queue Queue No. Appln Label Returned Queues 1, 3, and 4 are allocated for application 30, and queue 2 is allocated for global usage in program B. Thus, because there is a current limit of four queues, an error is returned to program G when it attempts to allocate another queue to application 30.
ZCOM C I/F Library Routines ZLTQUEUE (3X) EXAMPLE #include #include int32 uint32 char uint32 ierr; appln; label[6]; queue if (ierr = zltqueue (appln, label, &queue)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO Chapter 4 /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines ZLTSTORE (3X) ZLTSTORE (3X) zltstore – Logical data storage allocation NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zltstore (appln, label, size, offsetp uint32 char uint32 int32 appln; *label; size; *offsetp; DESCRIPTION Routine zltstore requests a data area in the logical terminal table extension for terminals of a specific application number.
ZCOM C I/F Library Routines ZLTSTORE (3X) fork unsafe Chapter 4 It cannot be called by a child process after fork(2) but before exec(2).
ZCOM C I/F Library Routines ZLTSTORE (3X) PARAMETERS NOTES appln Application number. label Storage label name. size Storage size requested, in bytes. The size must be a multiple of 4 bytes and must not exceed the available area in logical terminal table extension (as defined by LOGICAL-SIZE in TTGEN configuration file). Otherwise, error ZEBADSIZE (-63) is returned. offsetp (Return Param) Starting byte offset, relative to the beginning logical terminal table, for the storage in the extension area.
ZCOM C I/F Library Routines ZLTSTORE (3X) RETURN VALUE Chapter 4 Routine zltstore 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.
ZCOM C I/F Library Routines ZLTSTORE (3X) EXAMPLE #include #include int32 uint32 char uint32 int32 ierr; appln; label[6]; size; offset; if (ierr = zltstore (appln, label, size, &offset)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO 256 /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines ZLTUP (3X) ZLTUP (3X) zltup – Update logical terminal table NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zltup (zap, ibuf, len, offset) zaddr_type char int32 int32 DESCRIPTION *zap; *ibuf; len; offset; Routine zltup is used to update information in the user area of the logical terminal area.
ZCOM C I/F Library Routines ZLTUP (3X) 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 NOTES zap ZCOM address. ibuf Data buffer. len Byte length of buffer. offse t Byte offset within the logical terminal table where the data in the buffer should be placed.
ZCOM C I/F Library Routines ZLTUP (3X) int32 int32 len; offset; if (ierr = zltup (&zaddr, ibuf, len, offset)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO Chapter 4 /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.
ZCOM C I/F Library Routines ZLUOPEN (3X) ZLUOPEN (3X) zluopen – Open a ZLU file NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int zluopen (zap, mode, fd) zaddr_type int int *zap; mode; *fd; DESCRIPTION Routine zluopen opens the device file associated with a program ZLU for use with the standard HP-UX file access routines. The zap parameter points to the program ZLU to be accessed.
ZCOM C I/F Library Routines ZLUOPEN (3X) 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.
ZCOM C I/F Library Routines ZLUOPEN (3X) /* good return code */ } NOTES The ZLU associated device files are kept in the /dev/zcom directory, and should only be opened by zluopen. If they are opened and accessed directly, incorrect results may be returned. Currently, only device files for program ZLUs are required for the system. They are named as pzluNNNNN, where NNNNN is a number ranging from 00001 to 99999.
ZCOM C I/F Library Routines ZLUOPEN (3X) FILES SEE ALSO Chapter 4 /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). /dev/zcom/pzlu* Device files associated with program ZLUs. select(2), close(2).
ZCOM C I/F Library Routines ZMAPR (3X) ZMAPR (3X) zmapr – Set up ZLU mapping configuration NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zmapr (zap, mzap) zaddr_type zaddr_type *zap; *mzap; DESCRIPTION Routine zmapr is used to set up an alternate mapping for a ZLU. After the zmapr routine has been successfully called, all messages addressed to the source ZLU (*zap) will be redirected to the destination ZLU (*mzap).
ZCOM C I/F Library Routines ZMAPR (3X) PARAMETERS zap ZCOM address to be mapped. mzap ZCOM address to be mapped onto. NOTES On a successful return from zmapr, accessing the source ZLU is actually directed to the destination ZLU. If the source ZLU was a program ZLU, all messages that were queued on it will be flushed (i.e., returned to the free queue). If it was a terminal ZLU, the linkage to the terminal is lost. Usually, this is not desirable because the previously associated terminal is unusable.
ZCOM C I/F Library Routines ZNAME (3X) ZNAME (3X) zname – Find ZLU number from ZLU name NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zname (zap, name) zaddr_type char DESCRIPTION *zap; *name; When a zopen call is issued to allocate a program ZLU, the application assigns a symbolic name to the ZLU. Routine zname is used to find the program ZLU number associated with a symbolic name.
ZCOM C I/F Library Routines ZNAME (3X) Chapter 4 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).
ZCOM C I/F Library Routines ZNAME (3X) PARAMETERS RETURN VALUE zap (Return param) ZCOM address. name ZLU symbolic name to search for. The name may be a maximum of 7 characters long, and must be left-justified and null-terminated. Comparison is case sensitive. Routine zname 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 #include
ZCOM C I/F Library Routines ZNAME (3X) FILES SEE ALSO Chapter 4 /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).
ZCOM C I/F Library Routines ZOPEN (3X) ZOPEN (3X) zopen – Create ZLU program input queue NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zopen (zap, pflag, name, limit) zaddr_type uint32 char uint32 DESCRIPTION *zap; pflag; *name; limit; Routine zopen allocates a free ZLU as a program input queue. This must be done before a program may receive any messages from terminals or other programs.
ZCOM C I/F Library Routines ZOPEN (3X) The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options “-lzcom_c -lpthread” options to cc(1) or ld(1).
ZCOM C I/F Library Routines ZOPEN (3X) 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.
ZCOM C I/F Library Routines ZOPEN (3X) NOTES The first zopen call that a program makes will define the primary ZLU irrespective of the value of pflag. If a subsequent zopen call is made with pflag=1, the primary ZLU definition will be overridden. If multiple zopen calls are made with pflag=1, then each call will override the previous definition, leaving the primary ZLU defined as the one allocated in the last zopen call.
ZCOM C I/F Library Routines ZPEEK (3X) ZPEEK (3X) zpeek – Read data from ZLU without disturbing input queue NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zpeek (zap, mode, mhp, ibuf, len, rlen, rstat) zaddr_type uint32 zmhd_type char int32 int32 int32 DESCRIPTION *zap; mode; *mhp; *ibuf; len; *rlen; *rstat; Routine zpeek fetches the next message from the head of a program ZLU input queue. The program has the option to wait (i.e.
ZCOM C I/F Library Routines ZPEEK (3X) Threads Considerations RETURN VALUE 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.
ZCOM C I/F Library Routines ZPORT (3X) ZPORT (3X) zport – ACC interface card port configuration NAME SYNOPSIS #include #include #include /* if compliled with ANSI C (recommended) */ int32 zport (iftno, portno, rcode, action, cnfg, stat) uint32 uint32 uint32 uint32 zpconf_type int32 iftno; portno; rcode; action; cnfg *stat; DESCRIPTION Routine zport (action 0-3) configures the datacomm ports on an ACC interface card.
ZCOM C I/F Library Routines ZPORT (3X) Threads Considerations Chapter 4 This routine may be called from multi-threaded application using the POSIX (1003.1c) kernel threads API package. It has the following characteristics when called by 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.
ZCOM C I/F Library Routines ZPORT (3X) PARAMETERS iftno ACC MUX interface number. portno Port number in the ACC interface card: 0.. 7 For Z7200A, Z7340A and Z7400A ACC interface cards 0.. 3 For the Z7300A ACC interface card 0..
ZCOM C I/F Library Routines ZPORT (3X) PT_ILL_PMODE (6) - Illegal port mode PT_NO_BREAK (7) - Port failed self test PT_NO_BREAK (8) - BREAK routine not installed PT_BAD_XCLK (9) - Clock multiplier not compatible with mode PT_NO_PLL (10) - No DPLL available at this baud rate PT_TOO_FAST (11) - Async mode not available for baud > 38400 The status message text may be fetched using zcomstatus(3X) (req = ZCOM_MRQCODE_PORT, or 11).
ZCOM C I/F Library Routines ZPORT (3X) Ecode Parity X.Clk S.Clk 280 Value Operating mode 00 Sync mode 01 Async 1 stop 10 Async 1.5 stop bits 11 Async 2 stop bits Value Parity select 00 No Parity 01 Odd parity 10 No Parity 11 Even parity Value Clock multiplier 00 X1 01 X 16 10 X 32 11 X 64 Value Clock source 00 External clock 01 Internal clock from BRG 10 X.
ZCOM C I/F Library Routines ZPORT (3X) The baud rate is split between two 4-bit parameters (for compatibility reasons). If the Baud 1 parameter is 0, then Baud 2 is used. Rates listed in bold are not available on the Z7350A or Z7340A ACC interface cards. The Z7200A card does not support baud rates above 76800 and the Z7400A card does not support rates above 128000.
ZCOM C I/F Library Routines ZPORT (3X) 00 00 RS232 Mode 01 00 RS422 Mode 10 00 Loopback Mode (Tristate) 1 1i 00 X.21/V.11 Mode 00 01 V.35 (Z7340A and Z7350A only) 00 10 RS-449 (Z7340A and Z7350A only) 00 11 V.36 (Z7340A and Z7350A only) All Other Values Reserved The Z7300A or Z7330A E1/T1 card uses the following configuration: 15 Ecode 14 13 12 Fmode 10 9 8 7 6 0 = not used Pmode 0 = not used Ecode Fmode 282 11 5 S.
ZCOM C I/F Library Routines ZPORT (3X) S.Clk Pmode 0011 T1: F72 - Remote Switch Mode 0100 E1: DF - Doubleframe 0101 E1: MF - CRC Multiframe 0110 Transparent (voice) mode Value Clock source 00 External clock (slave) 01 Internal clock from BRG (master) 10 External RxC only (Exin) 11 DPPL output (use BRG as source) Value Port Mode 0000 Reserved ....
ZCOM C I/F Library Routines ZPORT (3X) NOTES 1. Notice that it is possible to change only one byte of the configuration word by using an appropriate ‘action’ parameter value. In this case, the other bytes remain unaffected. The new parameters remain in force until changed by another call or until the ZCOM subsystem is reinitialized. Normally, an application program should not be required to change the port configuration. 2.
ZCOM C I/F Library Routines ZPORT (3X) When zport returns a zero error code, the return status stat indicates the completion status: zero means successful, while non-zero values indicate the reason for the problem. Note that status code 4, 5, 6, and 7 implies the associated port will now be inoperative. Another zport configuration request must be done to recover it.
ZCOM C I/F Library Routines ZPORT (3X) EXAMPLE This example puts an E1/T1 port into “loopback” (tristate) mode. #include #include int32 ierr; uint32 iftno; uint32 portno; uint32 rcode; uint32 action; zpconf_type cnfg; int32 stat; iftno = 1; /* ACC MUX number 1 in TTGEN configuration file. */ portno = 2; /* Port #2 */ rcode = 2; /* We are providing the configuration in “cnfg”. */ action = ZCOM_ZMUXPORT_PORT; /* Set only the port mode (Pmode, Pmode2) */ cnfg.e1t1_bits.
ZCOM C I/F Library Routines ZPTUP (3X) ZPTUP (3X) zptup - Update physical terminal table user area NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zptup (zap, ibuf, len, offset) zaddr_type char int32 int32 *zap; *ibuf; len; offset; DESCRIPTION Routine zptup is used to update information in the user area of the physical terminal table.
ZCOM C I/F Library Routines ZPTUP (3X) PARAMETERS RETURN VALUE zap ZCOM address of the physical terminal table to update. ibuf Data buffer holding the information to place into the PTT. len Number of bytes of data to copy from ibuf into the PTT. offse t Byte offset within the physical terminal table from where the update should begin. Routine zptup returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.
ZCOM C I/F Library Routines ZQMVE (3X) ZQMVE (3X) zqmve – Move message from one ZLU to another NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zqmve (zap, dzap) zaddr_type zaddr_type *zap; *dzap; DESCRIPTION Routine zqmve is used to transfer the first message from one ZLU queue to the end of a second ZLU queue by changing the queue pointers (without actually moving the data). If the destination queue is not specified (i.e.
ZCOM C I/F Library Routines ZQMVE (3X) PARAMETERS RETURN VALUE 290 zap ZCOM address from which to get the message. dza p Destination ZCOM address (if NULL, then the message will be flushed). Routine zqmve 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.
ZCOM C I/F Library Routines ZQMVE (3X) EXAMPLE Example 1: #include #include int32 zaddr_type zaddr_type ierr; zaddr; daddr; if (ierr = zqmve (&zaddr, &daddr)) { /* error return code */ } else { /* good return code */ } Example 2: - (how to flush) while(zqmve(&zaddr, NULL) == NULL); FILES Chapter 4 /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines ZQSZE (3X) ZQSZE (3X) zqsze – Read ZLU input queue size NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zqsze (zap, zqhdp) zaddr_type zqhd_type *zap; *zqhdp; DESCRIPTION Routine zqsze will return the queue header information, which includes the number of messages, i.e., the number of buffers (zqhd_type->qnmsg) queued to the specified program ZLU. An error is returned if the ZLU is not a program ZLU.
ZCOM C I/F Library Routines ZQSZE (3X) PARAMETERS za p ZCOM address zqhdp (Return param) ZCOM queue header data structure.
ZCOM C I/F Library Routines ZQSZE (3X) RETURN VALUE 294 Routine zqsze 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.
ZCOM C I/F Library Routines ZQSZE (3X) EXAMPLE #include #include int32 zaddr_type zqhd_type ierr; zaddr; zqhd; if (ierr = zqsze (&zaddr, &zqhd)) { /* error return code */ } else { /* good return code */ } FILES Chapter 4 /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.
ZCOM C I/F Library Routines ZREAD (3X) ZREAD (3X) zread – Read from ZLU NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zread (zap, mode, mhp, ibuf, len, rlen, rstat) zaddr_type uint32 zmhd_type char int32 int32 int32 DESCRIPTION *zap; mode; *mhp; *ibuf; len; *rlen; *rstat; Routine zread fetches the next message from the head of a program ZLU queue. The program has the option to wait (i.e.
ZCOM C I/F Library Routines ZREAD (3X) fork unsafe Chapter 4 It cannot be called by a child process after fork(2) but before exec(2).
ZCOM C I/F Library Routines ZREAD (3X) 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.
ZCOM C I/F Library Routines ZREAD (3X) 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.
ZCOM C I/F Library Routines ZREAD (3X) 3. 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.
ZCOM C I/F Library Routines ZREAD (3X) 5. The type of message received is returned in mhp->mid.mstype. Its values are as follows (defined in /opt/acc/include/zcom/zcomsys.
ZCOM C I/F Library Routines ZREAD (3X) /* error return code */ } else { /* good return code */ } NOTE 302 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.
ZCOM C I/F Library Routines ZREAD (3X) FILES SEE ALSO Chapter 4 /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). zevent_rcvr(3X), zpeek(3X), zset_rcvr(3X), zsend(3X), ztimr(3X), zcomstatus(3X).
ZCOM C I/F Library Routines ZRNTIMER (3X) ZRNTIMER (3X) zrntimer – Set timeout for remote node access NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zrntimer (node, time) int32 int32 node; time; DESCRIPTION Routine zrntimer is used to change the ZCOM request timeout value for requests sent to a remote ZCOM system node.
ZCOM C I/F Library Routines ZRNTIMER (3X) See the NOTES section below for more information on using this routine in a multi-threaded application. PARAMETERS node Remote node number where timeout is set. A value of zero means setting the timeout values for ALL remote nodes. time Timeout value in seconds (1-65535). Zero or negative values are not allowed. RETURN VAULE Routine zrntimer returns 0 if successful. Otherwise, a non-zero error code is returned. See /opt/acc/include/zcom/zcomsys.
ZCOM C I/F Library Routines ZRNTIMER (3X) /* good return code */ } FILES 306 /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).
ZCOM C I/F Library Routines ZSEND (3X) ZSEND (3X) zsend – Send data buffer to a ZLU NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zsend (zap, mode, mhp, ibuf, len, rstat) zaddr_type uint32 zmhd_type char int32 int32 DESCRIPTION *zap; mode; *mhp; *ibuf; len *rstat; Routine zsend sends a buffer to the specified ZLU. The zcntl(3X) routine is used for sending control messages to a terminal ZLU.
ZCOM C I/F Library Routines ZSEND (3X) 308 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).
ZCOM C I/F Library Routines ZSEND (3X) PARAMETERS zap Pointer to ZCOM address. The destination to where the data is sent.
ZCOM C I/F Library Routines ZSEND (3X) NOTES If mhp is specified (i.e., a non-NULL pointer), some header fields must be set up by the caller because they are extracted and sent with the data buffer. These fields are: mhp->mid.mzsrce - source ZCOM address (ZLU) mhp->mid.mtagw1 - header tag word 1 mhp->mid.mtagw2 - header tag word 2 mhp->mrq.mrqtag - protocol tag parameter (for terminal ZLU only) The other header fields are set up by the ZCOM subsystem exclusively.
ZCOM C I/F Library Routines ZSEND (3X) mhp->mrq.mrqstat - returned status (for response messages) mhp->mrq.mrqtag - protocol tag value (for terminal ZLU only) If Bit ZCOM_ZSEND_NOMX (0x4000) of mode is set and the request is to a outbound-multiplexed terminal ZLU, the outbound multiplexing is over-ridden. This results in the data being sent directly to the terminal (instead of the multiplexing program).
ZCOM C I/F Library Routines ZSEND (3X) Apart from the special bits, the mode value indicates the requested completion status of the write: * Mode=0 (ZcMODE_NO_WAIT - send no wait) The message to be sent is moved to a buffer and the caller continues executing without waiting for return status. If this mode is used, the program is responsible for controlling the flow of messages. If the calling program (or thread) uses too many buffers it will be suspended until some of the buffers have been sent.
ZCOM C I/F Library Routines ZSEND (3X) * Mode=7 (ZcMODE_DEF_STATUS_WBUF - send no wait, definite status with buffer) Similar to Mode 2, however both the status and the data buffer are returned with the response. This enables a message to be sent to multiple ZLUs in a particular order, without the program having to store the message temporarily. * Mode=8 (ZcMODE_WAIT - send and await status) The return status rstat indicates whether there is any problem with the send (zero means successful).
ZCOM C I/F Library Routines ZSEND (3X) #define #define #define #define #define #define #define #define #define #define ZCOM_MSTYPE_RSLT ZCOM_MSTYPE_RSLP ZCOM_MSTYPE____8 ZCOM_MSTYPE_MSRT ZCOM_MSTYPE_RPLP ZCOM_MSTYPE_TORZ ZCOM_MSTYPE_RPLT ZCOM_MSTYPE_RSEM ZCOM_MSTYPE_RSRT ZCOM_MSTYPE_RSRP 6 7 8 9 10 11 12 13 14 15 /* Mask of message response code */ #define ZCOM_MSRESP_LPR 0x80 #define ZCOM_MSRESP_XPS 0x40 #define ZCOM_MSRESP_PGW 0x08 #define ZCOM_MSRESP_BFR 0x04 #define ZCOM_MSRESP_DEF 0x02 #define ZCOM
ZCOM C I/F Library Routines ZSEND (3X) RETURN VALUE Routine zsend 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 ZcMODE_WAIT is used and zsend returns with zero, rstat contains the return status: 0 means successful, non-zero means there was a problem with the send. zcomstatus(3X) may be used to retrieve a status message, using request code ZCOM_MRQCODE_WRITE and rstat.
ZCOM C I/F Library Routines ZSETQL (3X) ZSETQL (3X) zsetql – Set buffer queue limit NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zsetql (zap, mode, qnum, limit) zaddr_type uint32 uint32 uint32 DESCRIPTION *zap; mode; qnum; limit; Routine zsetql changes the pre-set queue limit of a buffer queue (the pre-set value is configured in the TTGEN configuration file).
ZCOM C I/F Library Routines ZSETQL (3X) PARAMETERS zap ZCOM address. mode Type of queue: ZcPROGRAM_Q (0) - Program input queue ZcLOGICAL_TERM_Q (1) - Logical terminal queue ZcPHYSICAL_TERM_ Q (2) - Physical terminal queue If bit ZCOM_QLIM_MFLAG (0x8000) is set, the queue is changed to use a message limit. If bit ZCOM_QLIM_BFLAG (0x4000) is set, the queue is changed to use a byte limit. If neither are set, the limit mode is unchanged. They should not be set together. qnum Queue number.
ZCOM C I/F Library Routines ZSETQL (3X) RETURN VALUE 318 Routine zsetql 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.
ZCOM C I/F Library Routines ZSETQL (3X) NOTES 1. Queue limit does not affect data messages that are already in a queue. If the new limit is below the amount of queued data, no new data is accepted until the queued data drops below the limit. Setting a queue limit to zero will prevent the queue from accepting new messages. The queue is still readable, but new data can’t be added to the queue. 2. Under the current implementation, the terminal unacknowledged queue uses a “byte limit”, i.e.
ZCOM C I/F Library Routines ZSETQL (3X) FILES 320 /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).
ZCOM C I/F Library Routines ZSET_RCVR (3X) ZSET_RCVR (3X) zset_rcvr – Set up program ZLU as message receiver for a terminal ZLU NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zset_rcvr (action, zap, mode, rzap) int zaddr_type uint32 zaddr_type DESCRIPTION action; *zap; mode; *rzap; The zset_rcvr() routine is used to establish where incoming data from a terminal ZLU is to be queued.
ZCOM C I/F Library Routines ZSET_RCVR (3X) 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.
ZCOM C I/F Library Routines ZSET_RCVR (3X) 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.
ZCOM C I/F Library Routines ZSET_RCVR (3X) 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.
ZCOM C I/F Library Routines ZSET_RCVR (3X) EXAMPLE #include #include int32 int zaddr_type uint32 zaddr_type ierr; action; zaddr; mode; raddr; if (ierr = zset_rcvr (action, &zaddr, mode, &raddr)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO Chapter 4 /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc.
ZCOM C I/F Library Routines ZTIMR (3X) ZTIMR (3X) ztimr – Enable/disable ZLU timer NAME SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 ztimr (zap, time) zaddr_type int32 *zap; time; DESCRIPTION Routine ztimr is used to enable or disable the timer on a program ZLU. When enabled, a timer message is added to the program ZLU queue every specified time seconds. Timer messages are of type 3 (see ‘type’ in zread). The libraries libzcom_c.
ZCOM C I/F Library Routines ZTIMR (3X) time RETURN VALUE Chapter 4 Timer value in seconds (1-32767). A timer value of 0 will cancel the timer processing on the specified program ZLU. That is, no new timer messages are added to the program’s input queue. Routine ztimr 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.
ZCOM C I/F Library Routines ZTIMR (3X) NOTES A timer value of zero will cancel the timer processing on the specified ZLU. The ztimr call causes timer messages to be added regularly to the input queue of the specified program ZLU. A zread call to that ZLU will return a message type of 3 (in the type parameter) if it is a timer message. Thus the waiting program (or thread) is able to take alternative action, rather than waiting indefinitely for a response.
