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 “ 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. The first two digits represent the revision of a major release and the last two digits represent a minor release revision. Data structures and applications linked with a previous revision of the ZCOM software will be compatible if they have same major revision code. ZMON checks whether the revision code is acceptable. The different minor numbers indicate compatible revisions, such as bug fixes (as long as the major release revision code is the same).

HTREVC - TTGEN revision code

TTGEN inserts its integer revision code in this field in the memory image file. It is loaded into memory (unchanged) by ZMON and the LDM. This 16-bit revision code is stored in the same format as the ZCOM revision code (HZREVC). However, there is no validation of this field.

HNAME1 - Name of the TTGEN source file

Full path name of the source file used by TTGEN to generate the object file. This field is limited to 256 bytes and is null terminated.

HNAME2 - Name of TTGEN object file

Full path name of the TTGEN produced object file which was then used to startup (initialize) the ZCOM subsystem. This field is limited to 256 bytes and is null terminated.

HSNAME - ZCOM subsystem runtime instance name

Contains the contents of the System-Name parameter supplied in the TTGEN configuration file. This field is limited to 80 bytes and is null terminated.

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.

HSSIZE - Total runtime system size in bytes

This is the total size in bytes of the ZCOM subsystem memory, including all tables, queue headers, and the buffer pool.

HBPSIZE - Buffer pool size in bytes

This is the size in bytes of the ZCOM buffer pool. It is defined by the Buffer-Pool parameter in the TTGEN configuration file.

HNDMAX - Number of node entries

This contains the maximum number of node entries which may exist in the node entries memory section. This value is defined by the Node-Entry keyword in the TTGEN configuration file. Each Local-Node and Remote-Node definition consumes one node table entry.

HZLMAX - Total number of ZLUs

Total number of terminal ZLUs and spare (i.e., program) ZLUs. That is, this is the combined values of the Program-ZLU and Terminal-ZLU parameters specified in the TTGEN configuration file.

HTMZLU - Number of terminal ZLUs

This is the number of ZLUs out of the total (HZLMAX) that are allocated to terminals. The terminal ZLU numbers are allocated from 1 up to the number specified in this field. The TTGEN Terminal-ZLU parameter is used to initialize this field.

HSPZLU - Number of program ZLUs

Total number of available program ZLUs. The TTGEN Program-ZLU parameter is used to initialize this field.

HSPZL1 - First program ZLU number

Number of the first ZLU not allocated to terminal ZLUs. This field is initialized to the value of the TTGEN parameter Terminal-ZLU + 1. It indicates where the program ZLUs begin within the ZLU Table. Note that program ZLUs are assigned from the range (Terminal-ZLU+1) to (Terminal-ZLU + Program-ZLU).

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

HLTMAX - Number of logical terminal tables

Contains the maximum number of Logical Terminal Tables (LTT) which may exist in the configuration. This value is initialized from the Logical-Term parameter in the TTGEN configuration file.

HPTMAX - Number of physical terminal tables

Contains the maximum number of Physical Terminal Tables (PTT) which may exist in the configuration. This value is initialized from the Physical-Term parameter in the TTGEN configuration file.

HNCARD - Number of Mux interface tables

Number of Interface Tables (IFTs) which may exist in the configuration. This value is initialized from the Interface-Table parameter in the TTGEN configuration file. Note that there is one Interface Table (IFT) per Mux card defined.

HNRESP - Number of response records

This field contains the number of response records in the ZCOM subsystem. This value is initialized from the Program-ZLU parameter in the TTGEN configuration file.

HNLTQL - Number of LTT queue labels

Number of entries in the queue label table, up to a maximum value of 20. It is initialized by TTGEN to the number of Logical-Data statements defined in the TTGEN configuration file. This value can be modified by calling the zltqueue() routine.

HNLTSL - Number of LTT storage labels

Number of entries in the storage label table, up to a maximum value of 20. It is initially set up by TTGEN and subsequently maintained by the LDM.

HPNTBL - Node Table pointer (znode_type *)

This is a pointer to the first entry in the Node Table. Note that all of the node entries are stored in sequential order within kernel memory.

HPZLU - ZLU table pointer (zlu_type *)

This is a pointer to the 1st entry in the ZLU table. Note that all of the ZLU table entries are stored in sequential order within kernel memory.

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.

HPPTBL - Physical Terminal Table pointer (zptt_type *)

This is a pointer to the 1st physical terminal table. Note that all of the PTTs are stored in sequential order within kernel memory.

HPIFTP - Interface Table pointer (zift_type *)

This is a pointer to the first Interface Table (IFT). Note that all of the IFTs are stored in sequential order within kernel memory.

HPRESP - Pointer to the first response record (zrsp_type *)

This is a pointer to the first response record. Note that all of the response records are stored in sequential order within kernel memory.

HPQUES - Queue Header pointer (zqhd_type *)

This is a pointer to the first Queue Header. Note that all of the Queue Headers are stored in sequential order within kernel memory.

HPBFFR - Data buffer pointer (char *)

This is a pointer to the start of the data buffer pool. The data buffer pool is a block of contiguous kernel memory used for dynamically allocating data buffers for a variety of uses. The size of this block of memory is determined by the Buffer-Pool parameter from the TTGEN configuration file.

HPQLIM - Default program ZLU message queue limit

The default program ZLU message queue limit is the maximum number of messages that may be queued on each program ZLU. This value is initialized from the Queue-Limit parameter in the TTGEN configuration file. The default limit may be overridden during a zopen() by specifying a non-zero value in the limit parameter. The program ZLU queue limit may be changed dynamically by calling the zsetql() routine.

HUNACK - Maximum number of unacknowledged Tx buffers pending on a terminal ZLU

Upper limit of the total size (in bytes) of all unacknowledged transmit messages to a terminal ZLU. 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. The driver will resume processing of queued transmit requests when the Mux card acknowledges the completion of a previously issued transmit request for this terminal ZLU. This mechanism is used to prevent a few (or only one) terminal from consuming all of the transmit buffers on the Mux interface card. This field is initialized from the Unack-Limit parameter in the TTGEN configuration file. The unacknowledged queue limit may be changed dynamically by calling the zsetql() routine.

HMAXTX - Maximum number of Tx buffers pending on a terminal ZLU

Limit of transmit buffers pending on a terminal. When this limit is reached, the program doing write requests to the terminal will be suspended until some of the pending transmit requests are sent. Together with the limit imposed by HUNACK, this protects the ZCOM system buffers from excessive usage due to dead terminals (or other kind of device).

HIPLIM - Default 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 of a 2/8-port Mux card. Each port on the card has approximately 24,480 bytes of buffer space available for both internal use and transmit requests. If the DAM issues a transmit request to the Mux card and the Mux card does not have enough free buffers to hold the request data, the Mux will reject the request with an "out of buffers" error. The DAM will retry the request after an unacknowledged transmit request completes. This field is used to minimize the number of retries (and thereby increase overall performance) by imposing a limit on the size of unacknowledged transmit requests. This value is configured through the Port-Limit parameter in the TTGEN configuration file and is used to initialize the individual port limits iplimit[] kept in the interface table (zift_type).

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. When the value is zero or positive, the DSC functions are enabled. The value represents the number of active DSC requests. When the value is negative, DSC functions are disabled. DSC requests are rejected until this field is set to zero. This field is initialized to zero by TTGEN.

HCSWAIT - Number of DSC state waiters

This field contains the number of processes suspended, waiting for the DSC state to be set to zero. That is, the processes are waiting for the DSC functions to be enabled. A process will be suspended if it issues a DSC request while the DSC functions are disabled or if it issues a DSC disable request while other DSC requests are in progress.

HRDATAQ - Remote data queue (ZNODE Queue)

This is the data queue for remote ZCOM requests. All ZCOM API requests to a remote node or deferred remote request responses will be added to this queue by the LDM. The remote node request daemon, ZNODE, reads and processes the request from this queue. This special queue is sometimes referred to as the ZNODE queue or ZNODE data queue.

HNDPID - ZNODE HP-UX process ID (PID)

This field contains the process ID (PID) of the local ZNODE daemon to use for signalling the arrival of data on the ZNODE queue. If this value is positive, the LDM will send a signal to this process ID whenever new data is placed in the queue. If this value is negative, a signal will be sent to the process group. The group ID used is the absolute value of this field. This field is initialized to zero by TTGEN and is set up by the ZNODE program when it starts up.

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). The LDM timer increments this field once every second and marks all nodes as DOWN when it exceeds the inactivity period (currently 20 seconds). This field is initialized to zero when the ZCOM runtime subsystem is started up.

HNHIGH, HNLOW - ZNODE queue high and low water marks (flow control)

These two fields are used by the LDM to control the flow of data between the ZNODE daemon and the LDM. When the number of pending messages on the ZNODE queue reaches the high-water mark, programs initiating remote requests are suspended to avoid excessive buffer usage. Suspended programs will be allowed to resume execution when the number of queued messages drops to or below the low-water mark.

A special case exists when both the high and low water marks are set to the same value. In this situation, whenever the number of pending messages on the ZNODE queue is at or above this mark, all remote requests are rejected with an immediate error return value of ZENBUSY (-1, ZNODE is busy).

Note that this mechanism is only applicable to programs initiating remote requests and does not limit the messages or responses generated as a result of ZCOM subsystem operation (e.g. a terminal ZLU returns a message to its receiver in a remote system).

These two values are defined by the Flow-Control keyword in the TTGEN configuration file. If not specified, they will default to a high-water mark value of the maximum queue limit and a low-water mark value of zero (i.e. the mechanism is disabled).

HNWAIT - ZNODE queue high-water mark waiter

This field is maintained and used by the LDM to keep track of the number of programs currently suspended due to the high/low water mark flow control mechanism. It is initialized to zero by TTGEN.

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. There may be other numbers that also refer to the local node but HLCLND is the only one that is used to identify the local node on outbound messages.

HLTQTB - Queue label table

Each entry in the queue label table indicates the ownership of a data queue in a logical terminal table. Each entry has a structure of 16 bytes (zqlb_type) as shown in Table 3-2 “Queue Label Table”.

The table is initialized by TTGEN from the Logical-Data statements in the TTGEN configuration file. There is one entry in the Queue label table for each Logical-Data statement. Additional entries can be added to this table by calling the zltqueue routine (up to a maximum of 20 queue labels).

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 “Storage Label Table”.

The table is initialized by TTGEN from the Logical-Data statements in the TTGEN configuration file. There is one entry in the Storage label table for each Logical-Data statement. Additional entries can be added to this table by calling the zltqueue() routine (up to a maximum of 20 storage labels).

DSC_ercvrs - Dynamic Reconfiguration System Event Receivers pointer (zshaddr_type *)

This field contains a pointer to a linked list of all applications that wish to be notified whenever a ZCOM subsystem dynamic reconfiguration system event message is generated (through the zconfig routine). This field is initialized by TTGEN to zero. It will only contain a value if at least one application has requested notification.

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. If the DAM issues a transmit request to the E1/T1 card and the card does not have enough free buffers to hold the request data, the Mux will reject the request with an “out of buffers” error. The DAM will retry the request after an unacknowledged transmit request completes. This field is used to minimize the number of retries (and thereby increase overall performance) by imposing a limit on the size of unacknowledged transmit requests. This value is configured through the E1T1-Port-Limit parameter in the TTGEN configuration file and is used to initialize the individual port and subchannel limit array iplimit[] kept in the interface table (zift_type).

HOSTYPE - Type of operating system

This field indicates the type of operating system that manipulates the data structures. The allowed values are 0, 32 (32-bit kernel) or 64 (64-bit kernel). It is first set up by TTGEN to 0. Then it is set to 32 or 64 by ZMON when it initializes the ZCOM kernel memory block.