Message Header

Message Header (zmhd_type)

Table 3-33 “Message Header (zmhd_type)” shows the information in the message header (zmhd_type).

Message ID Header (zmid_type)

The Message ID Header contains information used for delivery of the message. See Table 3-34 “Message ID Header (zmid_type)”.

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.

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 “Response code for message type 2 and 10”.

Response code for all other message types are shown in Table 3-37 “Response code for all other message types”.

MZDEST - Destination ZCOM address

This is the ZCOM address to which the message is to be sent.

MZSRCE - Source ZCOM address

This is the ZCOM address of the sender of the message. This field is returned in the message header with the zread routine. When a message is received from a terminal, the sender zaddr.zlu is the ZLU number of the terminal.

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.

MZAUXL - Auxiliary ZCOM address

When using the multiplexed mode of operation through the logical terminal table, this field stores the original source ZLU.

Message Request Header (zmrq_type)

The six-byte message request block may or may not be present, depending on the message type and whether it is destined for a terminal. For request types 1, 4, and 6, to a terminal, the request block will be present; for request types 2 and 7 the request block will contain meaningless data. More information on the contents of this block can be found in the firmware reference manual. The Message Request Header is always present. For message types 2, 3, 7, 10, 11, and 15, it contains meaningless data. For types 4, 6, 12, and 14, it contains valid data.

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 “MRQCODE Terminal request codes”.

MRQTERM - Terminal number

This is the relative terminal number within the Mux card. It comes from the PTTERM field in PTT.

MRQSTAT - Request status

This is the status code returned from the protocol module and may be protocol type dependent.

MRQTAG - Tag parameter

This tag parameter is used to carry protocol specific information from the application program to the protocol module on the Mux card and return information from the firmware to the driver or application program.

MRQLEN - Data length

This is the total length of the data to be sent, or the length of data received, in this message.

System Event Message (zevent_type)

A System Event Message (SEM) is a special message generated by the ZCOM subsystem to represent an alarm condition or type of event that has occurred within the ZCOM subsystem. Applications may request that ZCOM deliver these events to a program ZLU by issuing a zevent_rcvr call. A SEM is returned to the application as a normal data message with a message type of ZCOM_MSTYPE_LSEM (5) or ZCOM_MSTYPE_RSEM (13). See the zevent_rcvr routine for addition details.

The structure used to hold the system event messages is composed of a fixed header structure and a variable part that is specific to the type of event. See Table 3-40 “System Event Message (zevent_type) Structure”.

SETYPE - System Event Type

This field contains the type of event represented by this message. Currently there are three defined types of events; a node status event (ZCOM_SETYPE_NODE), a card status change event (ZCOM_SETYPE_CARD), and a dynamic reconfiguration event (ZCOM_SETYPE_RECONFIG). The format of the variable part of the message is dependent on the event type.

SEFLAG - Event flags (currently not used)

This field is currently not used. It is intended to contain global information on the event (e.g. event priority, etc).

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.

SEDATA - Event specific data

Immediately following the header is a union that contains information specific to the type of event that occurred. There are currently two different event types that can be generated. The data structure for each is documented below.

ZCOM_SETYPE_NODE - Node status change event

The node status change event is generated whenever a node changes state or the state of the ZNODE daemon changes. The event data is referenced using sedata.node.<field name> and has the following fields:

NODE_NUM - Node number

This is the number of the node that has changed state. Note that this node is different from the SENODE field. For example, in ZCOM node 10, two remote nodes 40 and 50 are defined. In node 10, if the system detects that remote node 40 has gone down, the SEM generated will have SENODE=10, SEDATA.NODE.NODE_NUM=40.

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. Each entry indicates the status change of one link. If the value is zero, then there has been no change to the link's status. If the value is +1, the link changed state from DOWN to UP. If the value is -1, the link changed state from UP to DOWN.

ZCOM_SETYPE_RECONFIG - Dynamic Reconfiguration Event

The dynamic reconfiguration event is generated by using the zconfig routine, typically after programmatically reconfiguring the ZCOM subsystem during runtime operations. The event data is referenced using sedata.recfg.<field name> and has the fields shown in Table 3-42 “Dynamic Reconfiguration Event (ZCOM_SETYPE_RECONFIG)”.

CFG_CLASS - Type of reconfiguration performed

The field should contain the type of reconfiguration performed. Values from 0 to 999 are reserved for use by the ZCOM subsystem. There is currently one type defined, ZcCLASS_X25 (1), used to indicate that an X.25 link has been reconfigured.

CFG_INFO1 - Caller supplied data

The application or driver calling zconfig to generate the dynamic reconfiguration SEM should supply a class specific piece of data. In the case where the CFG_CLASS is set to ZcCLASS_X25, this field will contain the X.25 level 2 ZLU that was reconfigured.

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.<field name> and has the following fields:

Reason - The reason for the change in card state may be one of the following:

ZcSE_CARD_ADDED - An ACC card has been added to the system at the H/W path indicated by the bus_addr[] and card_addr fields

ZcSE_CARD_SUSPENDED - The operator has suspended card operation in preparation for on-line replacement of the card. The iftno field indicates which ACC card was suspended.

ZcSE_CARD_REMOVED - The ACC card indicated by the iftno field has been removed from the system and is no longer usable.

ZcSE_CARD_REPLACED - The ACC card indicated by the iftno field has been replaced (on-line) and can now be used.

ZcSE_CARD_STOPPED - The ACC card indicated by the iftno field has been halt by user request and must not be used.

ZcSE_CARD_FAILED - The ACC card indicated by the iftno field has been failed and is no longer usable.

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. It can now be used by applications.

Iftno - This is the ZCOM MUX number of the card that has changed state.

Bus_addr_len - Number of bus addresses in the bus_addr[] field. This field is only valid when the event has a reason code of ZcSE_CARD_ADDED.

Bus_addr[] - Hardware path of the ACC card being added. This field is only valid when the event has a reason code of ZcSE_CARD_ADDED.

Card_addr - Contains the address of the slot that the card was inserted into. This field is only valid when the event has a reason code of ZcSE_CARD_ADDED.