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. A copy of the specific warranty terms applicable to your
Hewlett- Packard product and replacement parts can be obtained from
your local Sales and Service Office.
Restricted Rights Legend. Use, duplication or disclosure by the U.S.
Government is subject to restrictions as set forth in subparagraph (c) (1)
(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013 for DOD agencies, and subparagraphs (c) (1) and
(c) (2) of the Commercial Computer S oftware Restricted Rights clause at
FAR 52.227-19 for other agencies.
HEWLETT-PACKARD COMPANY 3000 Hanover Street Palo Alto,
California 94304 U.S.A.
Use of this manual and flexible disk(s) or tape cartridge(s) supplied for
this pack is restricted to this product only. Additional copies of the
programs may be made for security and back-up purposes only. Resale of
the programs in their present form or with alterations, is expressly
prohibited.
TrademarkNotices UNIXisaregistered trademark in the UnitedStates
and other countries, licensed exclusively through X/Open Company
Limited.
X Window System is a trademark of the Massachusetts Institute of
Technology.
MS-DOS and Microsoft are U.S. registered trademarks of Microsoft
Corporation.
OSF/Motif is a trademark of the Open Software Foundation, Inc. in the
U.S. and other countries.
4
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 t hat you receive the updated or
new editions, you should subscribe to the appropriate product support
service.See your HP sales representativefor details.
First EditionDec 1992Release 1.0
Second EditionMar 1994Release 2.1
The ZCOM Subsystem consists of software and firmware t hat provide
the base set of features for the ACC Product family. It consists of:
• HP-UX interface drivers that communicate with the ACC Mux cards
• the ZCOM Mux Kernel which is an operating system that is
downloaded to the ACC Mux cards
• a set of daemon and utility programs that provide and facilitate
access to the ZCOM Subsystem
• a library of routines t hat provides a comprehensive user interface t o
the ZCOM Subsystem.
The ZCOM Subsystem also provides a powerful framework for
experienced data communication programmers to develop customized
protocols for specialized data communication applications.
This document describes the programmatic interface to the ZCOM
Subsystem. It describes the ZCOM Subsystem tables, buffers, and
routines, and how they are used to achieve program-to-device and
program-to-program communication. It als o contains information
required when writing application programs to take advantage of ACC
product features, such as:
• remote node access
Thisfeatureallowsprogrammaticrequeststoberoutedtoeithera
Mux card that is connected to the system on which the request is
made, or to a program or Mux card on a remote system.
• dual interface Mux panel configurations
This feature allows two systems to connect to a single Mux panel.
• multiple protocol support
• true multi-thread programming support
• 64-bit programming support
12Chapter1
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. The ZCOM protocol
modules provide the protocol specific firmware that runs on the ACC
Mux card
Note that the highlighted area in Figure 1-1 shows which software
components are provided by the base ZCOM Subsystem. Only protocol
modules used for loopback testing, and for monitoring the health of the
ACC Mux card and panel are provided with the base ZCOM Subsystem.
Protocol specific modules, such as X.25, are added to the ZCOM
Subsystem as separate products. The Protocol User’s Guides provided
with these products must be used in conjunction with this Programmer’s
Reference Guide when writing ZCOM application program
.
s.
Chapter 113
ZCOM Subsystem
ZCOM Software Overview
Figure 1-1Overview of ZCOM Software Structure
Application
or Utility
Program
X.25 TCP/IP
X.25 Level3
Prog. Accs.
Application
or Utility
Program
Other high
level
protocol
ZCOM HP-UX Drivers (LDM/DAM)
ZCOM Mux Kernel
......
......
Application
or Utility
Program
Low level
ZCOM I/F
HP9000
System
ACC Mux I/F
ZCOM
Protocol
Module
(X.25)
ZCOM
Protocol
Module
Mux datacomm interface to network
14Chapter1
ZCOM
Protocol
Module
......
ZCOM
Protocol
Module
Figure 1-2 presents another view of the ZCOM Subsystem which
includes the relationships between the various components of the ZCOM
Subsystem:
Figure 1-2ZCOM Subsystem Components
C Application
Program
ZCOM Subsystem
ZCOM Software Overview
ZCOM initialization
and Mux download
by ZMON
zmasterd
zmon
zmlog
Error log
Files
The ZCOM Subsystem is initialized by the zmon daemon which reads a
memory image file and downloads appropriate firmware to the ACC Mux
interface cards. The memory image file is created by running the ttgen
utility on an ASCII configuration file which contains information such as
what protocol will be used on the various ports of the ACC Mux cards,
and protocol specific configuration.
ZCOM I/F Library
ZCOM HP-UX Drivers
ACC I/F
Card
ACC I/F
Card
ACC I/F
Card
zterm
Utility
ZCOM Kernel
Tables & Buffers
...
ACC I/F
Card
Chapter 115
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
.
16Chapter1
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.
In the ZCOM Subsystem, messages are sent directly from sender to
receiver (where the receiver is another program or a terminal ZLU).
They are routed using a pointer called a ‘ZLU’ which stands for ‘ZCOM
Logical Unit’. ZCOM uses t he ZLU for its addressing mechanism. A ZLU
may represent a terminal (for instance, an X.25 virtual circuit) or an
application program. Messages are sent to and received by ZLUs.
Figure 1-3 on page 18
shows a sample set of program and terminal ZLUs,
and their interaction with each other and a Mux card:
Chapter 117
ZCOM Subsystem
ZCOM Concepts
Figure 1-3Definition and Features of ZLUs
Terminal 2
Terminal 1
Terminal
ZLU=57
Program
ZLU=502
Application
Program A
Mux card
Terminal
ZLU=231
Program
ZLU=500
Application
Program B
Terminal 3
Terminal
ZLU=101
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
statusmessages, that were deliveredto the program ZLU. These pointers
are maintained automatically by the ZCOM Subsystem. When a message
is sent to a ZLU, the data is moved to a system buffer first and the
address of the message is moved to the attached input queue.
18Chapter1
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 m ailbox 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. The program must issue a ZCOM library call to retrieve the
messages one-by-one from the input queue. The method used to cause a
message to be placed into a program’s input queue will be different
depending on whether the message was created by another program or a
physical/logical device.
If a message is sent (generated) by another program, then the sending
program must specify the ZLU of the program’s input queue to place the
message into. The receiving program need not do anything for the
message to be successfully delivered to their mail box (program input
queue).
However, when a message is generated by a terminal ZLU, any program
that wishes to receive messages from that device (terminal ZLU) must
inform the ZCOM Subsystem first. The program should issue a ZCOM
call (zset_rcvr) to tell the ZCOM Subsystem that all data coming from
the specified terminal ZLU should be delivered to its input queue.
Whenever data arrives from the device, it will be placed into the input
queues of all programs that have requested this data.
Terminal ZLUs
Terminal ZLUs represent a physical or logical device and do not have
input queues of their own. Any data coming from a terminal ZLU will be
delivered to the input queues of all applications that have requested it. If
there is no application interested in receiving the data, then the data is
thrown away and a message is logged to that effect.
TerminalZLUs do however have three different output (transmit)
queues. When a program sends data to a terminal ZLU,it can select one
of three queues to place that data on. Each queue represents a different
level of priority. The Express Queue is used for extremely high-priority
protocol dependent requests. The High-Priority Queue is used for high
priority data and the Low-Priority Queue is used for low priority data.
When a message is generated by an application, the buffers involved are
queued to the selected transmit queue and the ZCOM driver is notified.
Chapter 119
ZCOM Subsystem
ZCOM Concepts
The driver is then responsible for handling the message. Messages on the
express q ueue 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.
• Continue execution but report any error status (status messages are
queued to the ZLU of the calling program).
• Continueexecution; a definite response will be queued to the program
ZLU when the send has completed.
• Suspend execution until the send has completed (i.e.,
acknowledgment that the message was transmitted).
On completion, the message buffer may also be passed back to the
sending application program if required.
Each message on the ZLU has a ‘type’ attribute so that the program
reading the ZLU is able to differentiate between status messages,
timeout messages and data messages from terminals or other programs.
20Chapter1
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.
The interactive program ZTERM gives the user access to all the ZCOM
routines and can be used to test programs or terminals by sending and
receiving messages between them. The program ZSCAN allows the
programmer to display the contents of the ZCOM memory areas.
Chapter 121
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
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 a t 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.
24Chapter2
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.
Terminal ZLUs
Terminal ZLUs are used to direct messages to terminals. Before a
program can receive messages from a terminal, a program must set itself
up as receiver for that particular terminal’s ZLU (using the zset_rcvr
routine call). Any number of programs can be set up as a receiver for a
given terminal at any one time. It is possible, of course, to set up a
program to route messages to other programs from the terminal ZL U.
NOTETerminal ZLU is a generic term. The actual physical entity associated
with a terminal ZLU is dependent on the particular protocol being used.
For example, with a TTY protocol a Terminal ZLU would be associated
withaphysicalterminalorterminallikedevice.However,witha
protocol such as X.25, a terminal ZLU might represent a virtual circuit
or the HDLC line (X.25 level 2).
Chapter 225
ZCOM Message Handling
ZLU Definition
Mapped ZLUs
AllmessagesaddressedtoaparticularZLUwillberedirectedtothe
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.
26Chapter2
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 mechanismfor timeoutsand
statuses,as well a s 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. When enabled, a timeout message is added to the input
queue of the ZLU every n seconds (n being specified as a parameterto
the ztimr call). If there are already 10 or more messages on the queue, no
timer message is queued. Timer processing stops when ZTIMER and
ZCLOCK are reset to zero via the ztimr routine (a zero “time” value).
The application program uses the zread routinetoreadmessagesfrom
the input queue. All response and status messages are written to the
primary program ZLU. Data messages can be written to eit her the
primary or auxiliary program ZLUs.
When a zsend routine call is executed, the message to be sent is moved to
the ZCOM kernel buffer which is queued to the ZLU to which the
messagewassent.Themessageisaddedtotheendofthequeueforthe
specified ZLU.
Figure 2-1Program Message Queueing
Application A
zread
Chapter 227
Primary
Program
Input
Queue
Points to the
Input Queue
MSGMSG
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.
Figure 2-2Physical Terminal Table
Physical Terminal Table
Express Queue
High Priority Queue
Low Priority Queue
Unacknowledged Queue
The driver reads messages first from the express queue until there are
no remainingexpress queue messages, then from the high priorityqueue
until there are no high priority messages, at which stage the low priority
queue is read. Any further additions to the higher priority queues will be
read before the driver continues with the lower priority queues. When
the interface card is ready to accept messages, t he driver moves the
message to the unacknowledged queue and transfers the message to the
interface card (through the unacknowledged queue). Both the interface
card and the driver use DMA (Direct Memory Access) hardware to
transfer the messages. If the number of buffers on the unacknowledged
queue is less than the limit specified to TTGEN, more messages will be
transferred, otherwise the transfer will be suspended until some
outstanding messages are acknowledged.
Once the interface card has transmitted the message and has responded
with a definite status, the driver passes the status (if requested to do so)
back to the calling program. If the calling program also requires the
message buffer to be sent back with the status response, it is picked up
from the unacknowledged queue. Once the driver has passed the
message to the program, the message is removed from the
unacknowledged queue.
Messages in the unacknowledged queues for each terminal are also used
in a Mux restart: the messages are movedback to the high priority queue
to b e resent. The size of the unacknowledged queue is configurable in the
TTGEN configuration file.
28Chapter2
ZCOM Message Handling
Priorities
Priorities
Priorities only apply to messages that are destined for terminals.
MessagestoprogramZLUsaresimplyaddedtotheendoftheinput
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_LPRand ZCOM_ZSEND_XPS of the mode parameter, in
the zsend and zcntl routine calls. If the ZCOM_ZSEND_XPS bit is set,
then the message is queued on the express queue in the physical
terminal table for that terminal ZLU. If the ZCOM_ZSEND_LPR bit is
set, then the message is queued on the low priority queue in the physical
terminal table for that terminal ZLU. If neither bit is set, then the
message is queued on the high priority queue. This enables background
tasks to be sent at lower priorities, without impacting any on-line
throughput.
The driver reads the information from the terminal tables, looking at the
high priority queue for each terminal and sending the message at the
head of that queue. The driver only checks the low priority queue if there
are no messages on the high priority queue. This means that any
message on the high priority queue will be sent first.
NOTEThe Express Queue should be reserved for Protocol Control events, such
as, interrupts or resets. Normally, data should not be sent using the
Express Queue.
Chapter 229
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 i s
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.
Some fields in the logical terminal table and in the physical terminal
table are mentioned in the following descriptions; more information on
these fields can be found in the logical terminal table and the physical
terminal table information in the section on Tables and Data Structures.
The outbound and the inbound multiplexing are separate, so although in
most situations the multiplexing program will perform both functions, it
is possible to perform only inbound multiplexing or only outbound
multiplexing in any program.
The ltflag field of the logical terminal table (zltt_type) contains two flag
bits ZCOM_LTFLAG_OMX and ZCOM_LTFLAG_IMX, which indicate
whether messages to or from the logical terminal respectively, are to be
handled by a multiplexing program. These bits are set by TTGEN
according to the device type.
When more than one logical terminal is mapped to a single physical
terminal, the ltgzlk field (<zltt_type>.ltgzlk) linkage forms a circular list
of terminals in the same multiplexed group (i.e., mapped to the same
physical terminal). The ltqzlk field contains the ZLU number (16-bit) of
the next terminal in the group. For a non-multiplexing terminal, this
field contains the ZLU number of the current terminal (i.e., pointing
back to itself, a special case for circular list).
30Chapter2
Loading...
+ 268 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.