ACC Programmer’s Reference Guide Edition 9 HP 9000 Networking Manufacturing Part Number: Z7487-90002 E0400 © Copyright 2000 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 HP-PB ACC Multiplexer Hardware Installation and Reference Manual • 8 Channel EISA ACC Multiplexer Hardware Installation and Reference Manual • 8 Channel PCI ACC Multiplexer Hardware Installation and Reference Manual • 2 Channel (HP-PB) ACC Multiplexer Hardware Installation and Reference Manual • 4-Chan.
Contents 1. ZCOM Subsystem Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 ZCOM Software Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13 ZCOM Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17 Program ZLUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 Terminal ZLUs . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 3. ZCOM Tables and Data Structures Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Memory Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Differences in 32-bit and 64-bit Data Structures . . . . . . . . . . . . . . . . . . 40 ZCOM Header Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Node Entries Table. . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 4. ZCOM C I/F Library Routines Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 Initialization call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 Interface configuration call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 ZLU configuration calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 Data storage allocation calls . . . . . . . . . . . . . . .
Contents ZINIT (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 ZLTMG (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 ZLTMX (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 ZLTQUEUE (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 ZLTSTORE (3X) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 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 . . . . . . Low level ZCOM I/F ZCOM HP-UX Drivers (LDM/DAM) HP9000 System ACC Mux I/F ZCOM Mux Kernel ZCOM Protocol Module ZCOM Protocol Module ZCOM Protocol Module . . . . . . ZCOM Protocol Module (X.
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 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. Each program ZLU points to a queue that contains all messages, including timeout and status messages, that were delivered to the program ZLU.
ZCOM Subsystem ZCOM Concepts 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. All messages delivered are queued at the end of the input queue for a program in the order in which they were received. Note that the message is not actually delivered to the program, but simply placed into the input queue.
ZCOM Subsystem ZCOM Concepts The driver is then responsible for handling the message. Messages on the express queue are sent before those on the high priority queue which are sent before those on the low priority queue. Because the ZCOM Subsystem itself takes responsibility for the delivery of messages, the sending program is able to specify a number of options when it passes the message to the system. These options include: • Continue execution whether the message is sent successfully or not.
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 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 Figure 2-4 TZLU Inbound Multoplexing PTZLU Logical Terminal LTZRVR Physical Terminal PTZRVR=PZLU PZLU APPLICATION Thus, to process an inbound message with multiplexing: • zread (the message type will be type 1, ZCOM_MSTYPE_MSLT - a message from a terminal ZLU). • The source ZLU is obtained from PTZLU. PTZLU gives the ZLU of one of the ZLUs in a multiplexed group. • Decode the protocol header to extract the logical terminal address.
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 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 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 ZCOM Header Structure Field Name 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 Field Name Field Description Field Type Size (Bytes) HPZLU Pointer to 1st Zlu table pointer 8 HPTTBL Pointer to 1st Logical terminal table pointer 8 HPPTBL Pointer to 1st Physical terminal table pointer 8 HPIFTP Pointer to 1st Interface table pointer HPRESP Pointer to 1st response record pointer 8 HPQUES Pointer to 1st Queue header pointer 8 HPBFFR Pointer to data buffer pool pointer 8 HPQL
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 HSSOFF - System starting offset 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.
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 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. HPTTBL - Logical Terminal Table pointer (zltt_type *) This is a pointer to the 1st Logical Terminal table. Note that all of the LTTs are stored in sequential order within kernel memory.
ZCOM Tables and Data Structures ZCOM Header Structure 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. If this limit has been reached, any further write requests to the terminal ZLU will be queued up in the terminal table, but will not processed by the driver immediately.
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 Storage Label Table Field Name Field Description Field Type Size (Bytes) SLBGRP Appl. grp. number (0 = globally assigned) uns.
ZCOM Tables and Data Structures ZCOM Header Structure ETPLIM- Default E1/T1 IFT port TX limit (bytes) This field contains the limit (in bytes) of all unacknowledged transmit messages to terminal ZLUs belonging to the same port and subchannel of an E1/T1 card. Each E1/T1 card has approximately 16 M-bytes of buffer space available for both internal use and 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 Node Entries Table Field Name 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 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. HOST - Host link information structure (array) This array of structures contains information about each of the host links for this node. It can hold information on up to four host links. Each element of the array contains the fields for one host link as shown in Table 3-6.
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 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. ZLTYPE - Type of ZLU The ZLU type values are shown in Table 3-8. The type value is also used to indicate whether the ZLU is defined.
ZCOM Tables and Data Structures ZLU Tables its node and ZLU number. The number of a ZLU can be found using zname given its name and node. ZOWNER - PID number of owner When the ZLU is created, the PID number of the creating program is inserted in this field. When the program closes the ZLU, this field is cleared. For system created ZLUs, this field is zero (e.g., terminal ZLUs assigned by TTGEN). ZTIMER, ZCLOCK - ZLU timeout control These two parameters act together as a timer clock.
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) Field Name Field Description Field Type Size (Bytes) LTZSHRCVRS Pointer to list of indirect shared receivers pointer 8 LTHLDQ Sub-packet holding queue (0) struct 56 LTHDQN Data holding queues (1~4) struct [4] 4*56 This is followed by LTUSER - the user maintainable area - which consists of the fields shown in Table 3-10.
ZCOM Tables and Data Structures Logical Terminal Tables 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. LTPORT- Port number within the Mux card This is a one byte field that indicates which port this terminal is attached to within the Mux card.
ZCOM Tables and Data Structures Logical Terminal Tables LTFLAG - System status flags Currently the system status flags are used to indicate whether the outbound multiplexing and the inbound multiplexing are enabled. Figure 3-2 System Status flags 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 OM IM OM - Outward bound multiplexing, ZCOM_LTFLAG_OMX bit IM - Inbound multiplexing, ZCOM_LTFLAG_IMX bit Both are set by TTGEN according to the device type specified.
ZCOM Tables and Data Structures Logical Terminal Tables LTHLDQ - Sub-packet holding queue This queue is a holding queue for partial messages to an inbound multiplexed terminal. LTDHQN - Data holding queues For use by an application program to store temporary data for each terminal. Only the queue header is stored in these fields, as the data itself is stored in the ZCOM subsystem buffers. LTUSER - User-maintainable area The fields in the user-maintainable area may be modified by the zltup call.
ZCOM Tables and Data Structures Logical Terminal Tables LTAPNO - System application number This field is initialized by TTGEN based on the value specified in the Term or Lterm statement in the TTGEN configuration file. This field is not used by the ZCOM subsystem. It allows applications to recognize the terminals which are assigned to it. Each ZCOM application which is a direct receiver of terminal messages should access only those terminals with its allocated application number.
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 Physical Terminal Tables (System Area) Field Name Field Description Field Type Size (Bytes) PTDRST Driver terminal status uns.short 2 PTFWST Firmware terminal status uns.short 2 PTTYPE Physical type of terminal uns.short 2 SCFG_LEN Length of special configuration uns.short 2 SPEC_CFG Special protocol configuration uns.
ZCOM Tables and Data Structures Physical Terminal Tables PTZLU - Owning terminal ZLU number PTZCS - Owning terminal ZLU checksum The terminal ZLU number points back to the ZLU table entry for the owner of the terminal. The ZLU contains the checksum for the ZLU as well as its number. It is used by the driver to derive the source ZLU for all messages received for this physical terminal. This parameter is initially setup by TTGEN in the memory image file.
ZCOM Tables and Data Structures Physical Terminal Tables PTZPCTL_RCVR - ZCOM address of primary control receiver This is the node number, ZLU, and checksum used as the destination address for any control input messages received for this terminal. This field is set by a zset_rcvr mode 3 call. The control input messages are distinguished by the protocol modules on the MUX, by setting bit 1 of the input message tag byte.
ZCOM Tables and Data Structures Physical Terminal Tables PTTXLX - Pointer to next PTT on the express list linkage This linkage (containing the physical terminal table address) is used to link together physical terminals on the Mux which have messages queued on the express transmit queue. This field is NULL if the terminal is not on the list. It is initialized to NULL by TTGEN and is maintained by the LDM and DAM.
ZCOM Tables and Data Structures Physical Terminal Tables PTTXLB - Pointer to next PTT on low priority list linkage As for PTTXLA above, except that the linkage pertains to the low priority transmit queue. PTTXQB - Low priority transmit buffer queue The low priority queue is operated in a similar manner to the high priority queue. Data on this queue is processed only after all express and high priority data has been processed.
ZCOM Tables and Data Structures Physical Terminal Tables The IN bit indicates whether the terminal is considered as part of the current configuration. It is initialized by TTGEN and maintained by the driver. The EN and AC bits represent the current status of the terminal. They are initialized by TTGEN and maintained by the driver. They are reflected in the opposite sense by DS and IA on the interface card and in PTFWST.
ZCOM Tables and Data Structures Physical Terminal Tables PTUSER - User-maintainable area This area extends to the end of the physical terminal table. It defines the area that may be modified by a zptup call, and contains all the following fields: PTPOLL - Terminal poll addresses PTSLCT - Terminal select addresses These words usually contain the poll and select addresses specified for the terminal in the TTGEN configuration file. For some protocols however, they contain other configuration information.
ZCOM Tables and Data Structures Physical Terminal Tables PTERCT - Terminal error message counter This counter is updated by the driver after each $STDT buffer has been transferred from the Mux interface card. The $STDT buffer contains the number of errors that have occurred for a terminal since the last $STDT buffer was sent to the driver.
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 Interface Table Field Name Field Description Field Type Size (Bytes) 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 Interface Table Field Name Field Description Field Type Size (Bytes) ifwinfo Firmware run-time information word uns.short 2 ifboff Buffer pointer adjusted offset uns.
ZCOM Tables and Data Structures Interface Table ISTIME - Time of last ZMON restart/shutdown this card. This field contains the time (seconds since the Epoch) when ZMON last processed a restart or shutdown request for this card. It is used internally by ZMON to detect and ignore multiple restart/shutdown requests. BC1_ADDR - First level bus converter address for this MUX interface card For HP9000 Series K systems the address is of the form bc1/bc/s.
ZCOM Tables and Data Structures Interface Table IFTYPE - Interface card type Specified in TTGEN through the interface definition (the keyword MUX) with the following results: IFTYPE IFTYPE IFTYPE IFTYPE IFTYPE = = = = = ZCOM_ITYPE_Z7200A(6) ZCOM_ITYPE_Z7350A(7) ZCOM_ITYPE_Z7400A(8) ZCOM_ITYPE_Z7300A(9) ZCOM_ITYPE_Z7340A(11) - Z7200A Z7350A Z7400A Z7300A Z7340A HP-PB HP-PB EISA HP-PB PCI ACC ACC ACC ACC ACC 8-channel Mux 2-channel Mux 8-channel Mux 4-port E1/T1 8-channel Mux This field allows for th
ZCOM Tables and Data Structures Interface Table driver and the interface card (via “zmon restart”). ISCHDL - Scheduler event flags The scheduler uses this word to store the event flags that control the state of the backplane.
ZCOM Tables and Data Structures Interface Table IRSERR - Restart error count This field contains the count of the number of errors which occurred during the last restart or enable. These errors are due to $PORT or $TERM commands and will be separately reported to ZMON. This field is kept for information purposes only. IFSTCN - Status update request count This counts the number of $STDT replies until IFRTRY will be decremented.
ZCOM Tables and Data Structures Interface Table IFFLDT, IFFMNM - Download file link time and module name These two fields contain the time (since Epoch) when the download firmware file is linked (by zlink program) and its module name. These are set up by zlink and stored in the download file. When ZMON loads the file to the Mux interface card, it extracts them from the file and puts them into these two fields. The MX command in zmntr displays these fields.
ZCOM Tables and Data Structures Interface Table TXCX_HEAD - Pointer to head of the express queue linked lists TXCA_HEAD - Pointer to head of the high-priority queue linked lists TXCB_HEAD - Pointer to head of the low-priority queue linked lists ITXLSTX - Pointer to express terminal list array (in union) ITXLSTA - Pointer to high-priority terminal list array (in union) ITXLSTB - Pointer to low-priority terminal list array (in union) IPLIMIT - Pointer to port/subchannel unack Tx limit array (in union) IPBYTES
ZCOM Tables and Data Structures Interface Table Table 3-16 CARD.MMP Structure Field Name Field Description Field Type Size (Bytes) ipstat Port status/Subchannel status uns.short [128] 128*2 ipcntr Terminal count per port uns.short [128] 128*2 iportn Port configuration bytes struct[4] 4*4 isubch_buf Subchannel configuration struct[4] 4*256 ifcmdbuf Current backplane command buffer uns.char [16] 16 iscratch Scratch area for buffer alignment uns.
ZCOM Tables and Data Structures Interface Table CARD.BSP has the following fields shown in Table 3-17. Table 3-17 CARD.BSP Structure Field Name 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 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 IPLIMIT - Port unacknowledged transmit limit (in bytes) This array contains the limit (in bytes) of all unacknowledged transmit messages to terminals belonging to the same port or subchannel of this interface. This array contains one element, one for each port or subchannel of the Mux card.
ZCOM Tables and Data Structures Interface Table IPSTAT - Port/Subchannel status Depending on the card type this interface table is for, this ipstat field either contains the status of each subchannel in a 4-port E1/T1 ACC card, or the status of each port in a non-4-port E1/T1 ACC card (e.g., 2-port card or 8-port ACC card). The individual ipstat bits are handled as follows: ZCOM_IPSTAT_UND: The undefined bit. Being undefined is synonymous with being not configured.
ZCOM Tables and Data Structures Interface Table for ports. It only keeps track of the enabled/disabled status for subchannels via ipstat. ZCOM_IPSTAT_TXB: The out-of-transmit buffers bit. For a non-4-port card, indicates the status of ports. For a 4-port card, indicates the status of subchannels. ZCOM_IPSTAT_TXBX: 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.
ZCOM Tables and Data Structures Interface Table IPORTN - Port configuration buffer (zpconf_type) This array contains the configuration bytes for each port on the Mux card. The Port statements in the Port-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 zport routine.
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 Subchannel Specification Array Element Structure 31-30 29-24 23-8 7 6-3 2-1 0 spare ITBS spare INV spare mode spare ITBS - Individual Transmit Buffer Size INV - Inversion flag mode - Transmission mode spare - Reserved, not used (must be 0) IFIRQBP, IRESPBP, ISTDTBP - DMA reply buffer pointers (char *) These fields point to the corresponding b
ZCOM Tables and Data Structures Interface Table IFIRQBUF, IRESPBUF, ISTDTBUF - DMA response buffers These are response buffers that are written to by DMA read requests to the Mux interface card. The FIRQ buffer contains the results of an $FIRQ backplane transaction. The Response buffer contains the response that provides the DAM with the completion status from the Mux card firmware. The Status buffer contains the data returned from a $STDT transaction.
ZCOM Tables and Data Structures Interface Table ICFG_LKUPT - Optional E1/T1 tunable parameters (zcfg_lookup_t) This structure contains the optional E1/T1 tunable parameters that allow you to fine tune the allocation of resources (memory) within the E1/T1 card. Specifically, these parameters allow you to fine tune how card memory is divided up between internal tables and I/O buffers. These parameters may be specified in the TTGEN Interface-Definition section.
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 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 (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 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. QMMAX - Number of messages on the queue The largest number of outstanding messages ever linked to this queue at any given point in time.
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 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 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 Chapter 3 Dummy Used Flag Dummy Used Flag 103
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 Free Buffer Header Structure (zfbh_type) Field Name 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 BFLEN - Buffer length in bytes (data portion) This field contains the usable memory size (in bytes) within the buffer. The usable area of a buffer is indicated by its location, BFDATA, and its size, BFLEN. BFLINK - Pointer to the next buffer on queue This is the buffer linkage to the next buffer in the chain. It contains the address of the first field (i.e., BFFLAG) of the next buffer. If this is the last buffer on the list, it contains NULL.
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 Message ID Header (zmid_type) Field Name 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 MRQCODE - Terminal request code 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 MRQLEN - Data length This is the total length of the data to be sent, or the length of data received, in this message. 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.
ZCOM Tables and Data Structures Message Header SENODE - Node where event was generated 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 NSTAT - Node status change indicator 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.
ZCOM Tables and Data Structures Message Header ZCOM_SETYPE_CARD - Change in Card Status Event 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_USER_RESTART - The ACC card indicated by the iftno field is being restarted by user request and must not be used until a ZcSE_CARD_RESTRT_CMPLT event is received. 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.
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 Field Name Field Description Field Type Size (Bytes) hpano HPA value of this interface long 8 resrvd1 Reserved for future use. int 4 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.
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 SYS structure (ZCOM system global information, zsys_type) Field Name Field Description Field Type Size (Bytes) STIME Time when status last changed uns.
ZCOM Tables and Data Structures ZCOM Kernel Data 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 SYSPTR, SYSSIZE - ZCOM system size (adjusted) and pointer. These are the pointers to the size of the kernel memory to be used by the ZCOM subsystem. The ZCOM subsystem memory requires 64-byte alignment, and the system may not use up all allocated memory. These two fields indicate the actual location and size of the ZCOM memory. NREQUEST - Number of active requests This field contains the number of ZCOM application requests in progress.
ZCOM Tables and Data Structures ZCOM Kernel Data 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. 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.
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.
ZCOM Tables and Data Structures ZCOM Kernel Data 128 Chapter 3
4 ZCOM C I/F Library Routines 129
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 -ZCOM library access initialization Interface configuration call 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 t
ZCOM C I/F Library Routines Introduction ZLU data transfer calls ltqdget -Read data buffer in terminal data queue ltqdput -Store data buffer in terminal data queue zcntl -Send control message to ZLU zpeek -Read data without disturbing queue zqmve -Move message from one ZLU to another zread -Read from ZLU 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 informatio
ZCOM C I/F Library Routines Introduction zltmg -Move logical terminals between groups zltup -Update logical terminal table zptup -Update physical terminal table zrntimer -Set ZCOM remote node access timeout Chapter 4 133
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. • • • • • • • • • • • • • • • • • • • 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 Chapter 4 • • • • • • • • • • • • • • • • • • 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) 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 GETDEVICE (3X) 2. In a multi-threaded application, if thread cancellation occurs while calling this function, the allocated memory will be released before the thread terminates. Once this function returns, the calling thread is responsible for freeing the allocated memory during thread cancellation. 3. The following is the zdev_type data structure definition (from /opt/acc/include/zcom/zcomsys.h).
ZCOM C I/F Library Routines GETDEVICE (3X) FILES /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. Note: 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). /opt/acc/cfg/zcomdevice.txt User-customizable ASCII file used by ZDGEN to create the binary ZCOM device file, /opt/acc/cfg/zcomdevice.
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) The returned logical terminal table 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 information required from the LTT. An example of defining a buffer of sufficient size would be: NOTES struct { zltt_type char ltt; sys; ext[ZCOM_MAXLSIZE]; /* Max allowable extension */ For example, to access the fields: ltt.sys.
ZCOM C I/F Library Routines LTFIND (3X) FILES SEE ALSO /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 *zap; queue; *ibuf; len; *rlenp; DESCRIPTION Routine ltqdget retrieves the data message stored in the data queue of the logical terminal tables.
ZCOM C I/F Library Routines LTQDGET (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 LTQDGET (3X) RETURN VALUE Routine ltqdget 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 the specified queue is empty, then the ZENODATA error (-24) is returned and ibuf contains invalid data. EXAMPLE #include #include int32 zaddr_type uint32 char int32 int32
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 *zap; queue; *ibuf; len; DESCRIPTION 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) 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 LTQDPUT (3X) RETURN VALUE Routine ltqdput 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 uint32 char int32
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) The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options “-lzcom_c -lpthread” to cc(1) or ld(1). Threads Considerations This routine may be called from a multi-threaded application using the POSIX (1003.1c) kernel threads API package. This routine has the following characteristics when called by a multi-threaded application: cancellation point Thread cancellation can occur when a thread calls this routine.
ZCOM C I/F Library Routines MAKEZLUNAME (3X) WARNING If two different programs call this routine with the same name parameter and from the same TTY, the same ZLU name will be returned.This implies that if multiple copies of a program are run from the same TTY, they will all get the same ZLU name. If they are run from different terminals, different ZLU names will be returned.
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 *zap; *zskeyp; *zptt; len; DESCRIPTION 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) This method is used usually when the MUX, PORT, and TERM are known. An example is in retrieving a previously accessed physical terminal table. 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.
ZCOM C I/F Library Routines PTFIND (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 PTFIND (3X) RETURN VALUE Routine ptfind returns 0 if successful. Otherwise, if the physical terminal is not found, ZENOTM (-75) is returned. EXAMPLE #include #include int32 zaddr_type zskey_type zptt_type int32 ierr; zaddr; zskey; zptt; len; if (ierr = ptfind (&zaddr, &zskey, &zptt, len)) { /* error return code */ } else { /* good return code */ } FILES /opt/acc/include/zcom/zcomsys.
ZCOM C I/F Library Routines ZCLOS (3X) ZCLOS (3X) NAME zclos - Delete program input ZLU 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) Threads Considerations This routine may be called from 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 ZCLOS (3X) FILES /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files. /opt/acc/include/zcom/zcomcall.h ZCOM routine function prototypes (requires ANSI C compilation).
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 *zap; mode; rcode; *mhp; *ibuf; len *rstat; DESCRIPTION Routine zcntl is used to change the state of a terminal or to send a protocol dependent control message to a terminal ZLU.
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) rcode Control request code: ZCOM_MRQCODE_CNTWR ZCOM_MRQCODE_TERM ZCOM_MRQCODE_ENB ZCOM_MRQCODE_DSB ZCOM_MRQCODE_ACT ZCOM_MRQCODE_DEA (3) - Control write (length in len) (6) - Set terminal parameters (7) - Enable terminal (8) - Disable terminal (9) - Activate polling (10) - Deactivate pollin To operate normally, a terminal ZLU must be enabled (rcode=ZCOM_MRQCODE_ENB) and activated (rcode=ZCOM_MRQCODE_ACT).
ZCOM C I/F Library Routines ZCNTL (3X) 1. File /opt/acc/include/zcom/zcomsys.
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 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 10 Special Terminal Configuration 3 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) FILES SEE ALSO /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). zcomstatus(3X), zconfig(3X), zread(3X), zsend(3X), zopen(3X).
ZCOM C I/F Library Routines ZCOMERROR (3X) ZCOMERROR (3X) NAME zcomerror – Return a formatted ZCOM error message 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). EXAMPLE #include #include
ZCOM C I/F Library Routines ZCOMLNAME (3X) ZCOMLNAME (3X) NAME zcomlname – Set up originator name for log messages 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 name 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) NAME zcomlog – Add a message to the ZCOM log file 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) 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 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) 1. The ZMLOG program retrieves the unique message test using the logging program name and message number. By default, the message tests of all log messages are retrieved from the message file default.msg in /opt/acc/msg. If the environment variable “LANG” is defined, the message text is retrieved from the message file $LANG.msg instead. In case it does not exist, the default.msg file is used. This allows support for multiple message file in different languages.
ZCOM C I/F Library Routines ZCOMLOG (3X) FILES /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files. /opt/acc/include/zcom/zcomcall.h ZCOM routine function prototypes (requires ANSI C compilation). /opt/acc/msg/default.msg Master message text file.
ZCOM C I/F Library Routines ZCOMSTATUS (3X) ZCOMSTATUS (3X) NAME zcomstatus – Return a formatted ZCOM status or error message 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 req Request code (from the zread header, zmhd ) stat 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) node Destination node. 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) uint8 bc1_addr; /* 1st level bus converter addr */ uint8 bc_addr; /* Bus converter addr of hardware */ 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; /*
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 ZCOM_ZCONFIG_SYS ZCOM_ZCONFIG_CARD ZCOM_ZCONFIG_PORT ZCOM_ZCONFIG_TERM ZCOM_ZCONFIG_PORTSC - DSC Control - System Configuration - Interface Configuration - Port Configuration - Terminal Configuration - Port and Subchannel Configuration Field header.
ZCOM C I/F Library Routines ZCONFIG (3X) Response Data The response data structure consists of the header fields and a “union” data portion for completion response: /* Configuration Response */ typedef struct { zcfghdr_type header; /* Header Information */ union { struct { int32 error; /* Return ZCOM error */ } ctlret; struct { int32 error; /* Return ZCOM error */ } sysret; struct { uint32 int32 } cardret; struct { uint32 uint32 int32 } portret; struct { zaddr_type int32 } termret; struct { uint32 uint32
ZCOM C I/F Library Routines ZCONFIG (3X) TYPES OF CONFIGURATION FUNCTION DSC Control The DSC control function is to provide global control and status on the access of DSC functions. There are 3 DSC control actions. Action ZcENABLE_DSC(1) is to enable the DSC access after it has been disabled. By default, the DSC access is enabled when ZCOM system is started up. Action ZcDISABLE_DSC(2) is to disable DSC access. When disabled, local processes attempting DSC functions will be suspended.
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) Configuration Data header.config ZCOM_ZCONFIG_SYS (system configuration) header.action ZcDSC_MOD_SYS_NAME (1) - Modify ZCOM runtime system name. 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.
ZCOM C I/F Library Routines ZCONFIG (3X) Interface Configuration There are 6 interface configuration actions. They are used to alter the parameters related to an interface card, and for controlling the operation of an interface card. Action ZcDSC_CHNG_FW_FILE (1) modifies the firmware file name (used to download the MUX card). This change will have no effect until the interface card is restarted, causing the new firmware file to be used to download the 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 ZcDSC_CFG_MODE ZcDSC_BAUD_RATE ZcDSC_PORT_MODE ZcDSC_BREAK_REQ ZcDSC_SET_XMIT_LIMIT ZcDSC_ENABLE_PORT ZcDSC_DISABLE_PORT (1) - Set all operating modes (Configuration, Baud Rate and Port) (2) - Set Configuration mode only (Ecode, Sync, Mode, Parity) (3) - Set Baud Rate mode only (X.Clk, S.
ZCOM C I/F Library Routines ZCONFIG (3X) 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 11 10 Mode 9 8 Parity 7 6 X. Clk Baud 2 4 S.
ZCOM C I/F Library Routines ZCONFIG (3X) X.Clk Value 00 01 10 11 Clock multiplier X1 X 16 X 32 X 64 S.Clk Value 00 01 10 11 Clock source External clock Internal clock from Baud Rate Generator (BRG) X.21 clock source 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. Rates listed in bold are not available on the Z7340A and Z7350A interface cards.
ZCOM C I/F Library Routines ZCONFIG (3X) Pmode Pmode Pmode2 Value Value 00 00 01 00 10 00 11 00 00 01 00 10 00 11 All other values Port mode RS232/V.24 Mode RS422 Mode Loopback Mode (Tristate) X.21/V.11 Mode V.35 (Z7340A and Z7350A only) RS-449 (Z7340A and Z7350A only) V.36 (Z7340A and Z7350A only) Reserved For the Z7300A (E1/T1) card: 15 14 Ecode 13 12 11 FMode Pmode 10 9 0 0 8 7 6 Fsync 5 4 S.
ZCOM C I/F Library Routines ZCONFIG (3X) 194 Fsync Value 00 01 10 11 Other port for clock synchronization Port 0 Port 1 Port 2 Port 3 S.Clk Value 00 01 10 11 Clock source External clock (slave) Internal clock (master) Clock from other port (specified in Fsync) Undefined TxAtt Value 00 01 10 11 T1 Transmit Attenuation (Z7330B only) 0 dB -7.5 dB -15 dB -22.5 dB Pmode Value 0000 ... 0100 0101 0110 0111 1000 1001 1010 1011 1100 ...
ZCOM C I/F Library Routines ZCONFIG (3X) QD 1= On Fast link-down option Makes the line go down whenever loss of T1/E1 frame synchronization is detected by the FALC. Otherwise by default there is a delay to avoid marking the line down on glitches. CR 1= On T1/ESF PRMs transmitted as “carrier” 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.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setport.qlimit New port limit (in bytes). This field is for action ZcDSC_SET_XMIT_LIMIT only. Response Data 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.
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) header.tag1, header.tag2 Any values. data.setportsc.iftno Interface card number (0, 1,...). data.setportsc.portno Port number in E1/T1 interface card (0...3). data.setportsc.subchno Subchannel number within the port (0...31). 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.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setportsc.ptcfg->ptinfo.subchb.tmsl[ ] Timeslot assignment array: used for actions ZcDSC_ALL_PARMS or ZcDSC_SET_TIMESLOTS only. Up to 32 timeslot assignments are allowed. Each element of the array is indexed by the timeslot number. That is, timeslot 0 is in tmsl[0], timeslot 1 is in tmsl[1], etc. For action ZcDSC_ALL_PARMS, all timeslots are configured. For action ZcDSC_SET_TIMESLOTS only timeslot entries with the UPD bit set are configured.
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) 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) Configuration Data header.config ZCOM_ZCONFIG_TERM (terminal configuration) header.action ZcDSC_CREATE_LTT_PTT ZcDSC_CREATE_LTT_ON_PTT ZcDSC_CLEAR_TERM ZcDSC_DELETE_TERM ZcDSC_MOVE_TERM (1) - Create a new terminal (LTT and PTT) (2) - Create a new LTT on an existing PTT (3) - Clear connection to an existing terminal (4) - Delete an existing terminal (5) - Move an existing terminal to another port header.tag1, header.tag2 Any values. data.setterm.
ZCOM C I/F Library Routines ZCONFIG (3X) data.setterm.portno Port number in the interface card (0 to 7). It specifies to which port the new terminal is linked. This field is needed for actions ZcDSC_CREATE_LTT_PTT and ZcDSC_MOVE_TERM only. data.setterm.subchno Subchannel number on the port (0 to 31). It specifies the subchannel number the terminal will communicate over. Currently, only the Z7300A card supports subchannels. All other ACC interface card types must set this parameter to zero.
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 /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) Threads Considerations This routine may be called from 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 ZEVENT_RCVR (3X) eclass ZCOM Subsystem event class (type of event). Note that each event class is a single bit that can be OR’d together to specify multiple event classes in a single zevent_rcvr call. ZcNODE_STATUS - Deliver an event when a Node or any link to a Node changes status. See the ZCOM Programmer’s reference manual for a detailed discussion of node status events. ZcDYN_CONFIG - Deliver dynamic reconfiguration completion events.
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 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. EXAMPLE #include #include
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
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) NOTES 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. 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) FILES /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files. /opt/acc/include/zcom/zcomcall.h ZCOM routine function prototypes (requires ANSI C compilation).
ZCOM C I/F Library Routines ZINIT (3X) ZINIT (3X) NAME zinit – ZCOM routine initialization SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zinit zsinfo_type (sip) *sip; DESCRIPTION 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) NAME zltmg – Move a logical terminal between groups SYNOPSIS #include #include /* if compiled with ANSI C (recommended) */ int32 zltmg (zap, nap) zaddr_type zaddr_type *zap; *nap; DESCRIPTION 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) 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 ZLTMG (3X) EXAMPLE #include #include int32 zaddr_type zaddr_type ierr; zaddr; nzaddr; if (ierr = zltmg (&zaddr, &nzaddr)) { } else { } FILES /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. (Note: must be the first include file before any other ZCOM include files) /opt/acc/include/zcom/zcomcall.
ZCOM C I/F Library Routines ZLTMX (3X) ZLTMX (3X) NAME zltmx – Control logical terminal multiplexing 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) 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 ZLTMX (3X) EXAMPLE #include #include int32 zaddr_type int32 ierr; zaddr; mode; if (ierr = zltmx (&zaddr, mode)) { /* error return code */ } else { /* good return code */ } FILES /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files. /opt/acc/include/zcom/zcomcall.
ZCOM C I/F Library Routines ZLTQUEUE (3X) ZLTQUEUE (3X) NAME zltqueue – Logical data queue allocation 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) 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 ZLTQUEUE (3X) The following example illustrates the queue allocation algorithm: Appln Program Appln Nmbr Appln Label Queue Queue No.
ZCOM C I/F Library Routines ZLTQUEUE (3X) FILES /opt/acc/include/zcom/zcomsys.h ZCOM subsystem general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files. /opt/acc/include/zcom/zcomcall.h ZCOM routine function prototypes (requires ANSI C compilation).
ZCOM C I/F Library Routines ZLTSTORE (3X) ZLTSTORE (3X) NAME zltstore – Logical data storage allocation 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) 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 ZLTSTORE (3X) Routine zltstore returns an already assigned area if the application number and storage label and storage size all match a previously assigned area. Otherwise, an error is returned. This provides a facility to share data areas between different programs and enables program restartability. If bit ZCOM_ZLTSTORE_NA (0x8000) of the size parameter is set before zltstore is called, then zltstore will only return a previously assigned area.
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) 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 ZLTUP (3X) EXAMPLE #include #include int32 zaddr_type char int32 int32 ierr; zaddr; ibuf[size]; len; offset; /* where size is user-defined; must be >= len */ if (ierr = zltup (&zaddr, ibuf, len, offset)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO /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 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) EXAMPLE #include #include int32 zaddr_type int int ierr; zaddr; mode; fd; if (ierr = zluopen (&zaddr, mode, &fd)) { /* error return code */ } else { /* 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.
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 mzap ZCOM address to be mapped. 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) 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). 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. PARAMETERS RETURN VALUE Routine zname returns 0 if successful. Otherwise, a non-zero error code is returned.
ZCOM C I/F Library Routines ZNAME (3X) FILES SEE ALSO /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). 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.
ZCOM C I/F Library Routines ZOPEN (3X) RETURN VALUE Routine zopen 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. 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.
ZCOM C I/F Library Routines ZOPEN (3X) FILES SEE ALSO /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 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 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 zport (3X) stat (Return Param) Status returned from the call: PT_OK PT_INV_PORT PT_BAD_PARM PT_NOT_DSBL PT_BAD_BAUD PT_ILL_SCLK PT_ILL_PMODE PT_NO_BREAK PT_NO_BREAK PT_BAD_XCLK PT_NO_PLL PT_TOO_FAST (0) - No error (1) - Port number out of range (2) - Bad parameter (3) - Some terminals in this port not disabled (4) - Bad baud rate (5) - Illegal clock source (6) - Illegal port mode (7) - Port failed self test (8) - BREAK routine not installed (9) - Clock multiplier not compatible
ZCOM C I/F Library Routines zport (3X) 11 External sync Ecode Value 00 01 10 11 Operating mode Sync mode Async 1 stop Async 1.5 stop bits Async 2 stop bits Parity Value 00 01 10 11 Parity select No Parity Odd parity No Parity Even parity X.Clk Value 00 01 10 11 Clock multiplier X1 X 16 X 32 X 64 S.Clk Value 00 01 10 11 Clock source External clock Internal clock from BRG 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) The Z7300A or Z7330A E1/T1 card uses the following configuration: 15 Ecode 14 13 12 11 10 9 Fmode 8 7 6 0 = not used Pmode 0 = not used Ecode Fmode S.Clk Pmode Chapter 4 Value 00 01 10 5 S.
ZCOM C I/F Library Routines zport (3X) 1100 ... 1111 NOTES Reserved Reserved 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) RETURN VALUE Routine zport 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. 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.
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. offset 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 zap ZCOM address from which to get the message. dzap Destination ZCOM address (if NULL, then the message will be flushed). RETURN VALUE 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. EXAMPLE Example 1: #include #include int32 zaddr_type zaddr_type
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 zap ZCOM address zqhdp (Return param) ZCOM queue header data structure.
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 /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 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) 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) ibuf (Return Param) Buffer for the received data. len Maximum length in bytes of the buffer ibuf. rlen (Return Param) Actual data length. NULL may be specified if the caller does not require the returned message length. Note that rlen may exceed len. This indicates the received data is truncated to just fill up ibuf. rstat (Return Param) Return status.
ZCOM C I/F Library Routines ZREAD (3X) 2. If the received message (or response) is from a terminal, the request code is returned in mhp->mrq.mrqcode. The request code and the returned status may be used to retrieve an appropriate status/error message by zcomstatus(3X). Refer to Appendix B ZCOM Status Codes of the Multiprotocol ACC Programmers’ Reference Guide for more information. The mhp->mrq.mrqcode field contains 0 if the message is from a program or is a System Event Message (SEM). 3.
ZCOM C I/F Library Routines ZREAD (3X) RETURN VALUE Routine zread returns 0 if the call is successful. In addition, for a response message, a non-zero return status rstat indicates there was a problem with the previous zsend(3X) call. A non-zero return status with a terminal message or response indicates there was a problem with the terminal. For other message types, the return status is always 0.
ZCOM C I/F Library Routines ZREAD (3X) FILES SEE ALSO /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) FILES /opt/acc/include/zcom/zcomsys.h ZCOM system general include file, containing data types, data structures, constants, error codes, masks, etc. Note that this must be the first include file before any other ZCOM include files. /opt/acc/include/zcom/zcomcall.h ZCOM routine function prototypes (requires ANSI C compilation).
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) 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 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 mhp->mid.mtagw1 mhp->mid.mtagw2 mhp->mrq.mrqtag - source ZCOM address (ZLU) - header tag word 1 - header tag word 2 - 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) 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). The ZCOM_ZSEND_MHD and ZCOM_ZSEND_NOMX bits are intended for use by multiplexing programs to intercept terminal messages and build specific messages or responses as required.
ZCOM C I/F Library Routines ZSEND (3X) * Mode=1 (ZcMODE_RPT_ERRS - send no wait, report errors) The message is transmitted without waiting for completion. A status response will be returned on the primary ZLU of the calling program, only if transmission errors occur. The response is retrieved by using a zread(3X) call; it will have a message type of six (6) or fourteen (14). Only the status is returned (in the rstat parameter of zread(3X)). The data buffer is discarded.
ZCOM C I/F Library Routines ZSEND (3X) * Mode=8 (ZcMODE_WAIT - send and await status) The return status rstat indicates whether there is any problem with the send (zero means successful). The calling program (or thread) is suspended by this call while the transmission is in progress. In a multi-threaded application, only the calling thread will be suspended, the other threads are not affected. When transmission is completed, the call is returned with the return status in rstat.
ZCOM C I/F Library Routines ZSEND (3X) /*-- ZCOM Message ID Header --*/ typedef struct { uint8 mstype; /* uint8 msresp; /* zaddr_type mzdest; /* zaddr_type mzsrce; /* uint16 mtagw1; /* uint16 mtagw2; /* zaddr_type mzaux1; /* } zmid_type; Message Type */ Message response code */ Destination zcom addr */ Source zcom addr */ Message tag word 1 */ Message tag word 2 */ Auxiliary zcom addr */ /* Mask and values for message type */ #define ZCOM_MSTYPE_REMOTE 0x08 #define ZCOM_MSTYPE____0 0 #define ZCOM_MSTYPE_M
ZCOM C I/F Library Routines ZSEND (3X) #define #define #define #define #define #define #define #define #define #define #define ZCOM_MRQCODE_CNTWR ZCOM_MRQCODE_STDT ZCOM_MRQCODE_STATUS ZCOM_MRQCODE_TERM ZCOM_MRQCODE_ENB ZCOM_MRQCODE_DSB ZCOM_MRQCODE_ACT ZCOM_MRQCODE_DEA ZCOM_MRQCODE_DEL ZCOM_MRQCODE_PORT ZCOM_MRQCODE_MULTI /*-- ZCOM Message Header --*/ typedef struct { zmid_type mid; zmrq_type mrq; } zmhd_type; RETURN VALUE 3 4 5 6 7 8 9 10 11 14 15 /* Terminal write */ /* INTERNAL USE: Status transfer
ZCOM C I/F Library Routines ZSEND (3X) EXAMPLE #include #include int32 zaddr_type uint32 zmhd_type char int32 int32 ierr; zaddr; mode; zmhd; ibuf[size]; /* where size is user-determined; must be >= len */ len; waitstat; if (ierr = zsend (&zaddr, mode, &zmhd, ibuf, len, &waitstat)) { /* error return code */ } else { /* good return code */ } FILES SEE ALSO /opt/acc/include/zcom/zcomsys.
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 ZcLOGICAL_TERM_Q ZcPHYSICAL_TERM_Q (0) - Program input queue (1) - Logical terminal queue (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) 2. Under the current implementation, the terminal unacknowledged queue uses a “byte limit”, i.e. the limit for this queue indicates the maximum number of bytes allowed on the queue. The other queues use a “message limit”, which means the maximum number of messages allowed on the queue. However, the limit type may be changed by setting the ZCOM_QLIM_MFLAG or ZCOM_QLIM_BFLAG bit in the mode parameter. 3.
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) PARAMETERS action Type of action to perform. ZcADD_PRIMARY ZcDEL_PRIMARY ZcADD_SHARED ZcDEL_SHARED zap ZCOM address of terminal. mode Receiver mode: ZcNORMAL ZcINB_MLTPLX ZcOUTB_MLTPLX ZcCONTROL - Sets the program ZLU as the primary receiver. - Deletes the primary receiver. - Adds the program ZLU to the list of shared receivers.
ZCOM C I/F Library Routines ZSET_RCVR (3X) When outbound multiplexing is enabled for a terminal, an outbound receiver must be set up (using mode ZcOUTB_MLTPLX) by the multiplexing program, which will intercept data sent from other programs. The outbound multiplexing program is responsible for passing the correct data onto the physical terminal (using zsend with mode bit ZCOM_ZSEND_NOMX). For more information, see the section on Multiplexing in the Multiprotocol ACC Programmer’s Reference Guide.
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) PARAMETERS zap ZCOM address (program ZLU). time 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. RETURN VALUE 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) FILES SEE ALSO /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 ZTIMR (3X) 298 Chapter 4
