HP TR3271 Programming Manual
Networking and Data Communications Library
TR3271
Management
Programming
Manual
Abstract This manual describes the control-and-inquiry interface and the event messages available to an
application program controlling or monitoring the TR3271 subsystem. This manual is for programmers.
Part Number 14948
Tandem Computers Incorporated
Document History Edition Part Number Product Version Operating System Version Date
First Edition 14948 TR3271 C20 GUARDIAN 90C20 March 1989
New editions incorporate any updates issued since the previous edition.
Copyright All rights reserved. No part of this document may be reproduced in any form, including photocopying or
translation to another language, without the prior written consent of Tandem Computers Incorporated.
Copyright 1989 Tandem Computers Incorporated.
CONTENTS
PREFACE ..................................................... vii
NOTATION CONVENTIONS ......................................... ix
SECTION 1. INTRODUCTION .................................... 1-1
Brief Overview of TR3271 .................................. 1-1
Objects Controlled by the Subsystem ....................... 1-1
Required Management Functions ............................. 1-2
Relationship With Other Subsystems ........................ 1-4
Subsystem Architecture .................................... 1-5
SECTION 2. MANAGEMENT PROGRAMMING FOR TR3271 ............... 2-1
How a Management Application Fits Into the Architecture ... 2-2
Commands .................................................. 2-4
Event Messages ........................................... 2-10
Communicating With the TR3271 Subsystem .................. 2-11
SECTION 3. ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM ...... 3-1
Definition Files .......................................... 3-2
Naming Rules and Guidelines for Applications .............. 3-4
Common Syntax Elements for the Subsystems ................. 3-4
Command Numbers ......................................... 3-4
Object Types ............................................ 3-5
Object Names ............................................ 3-6
Event Numbers ........................................... 3-7
Subjects of Event Messages .............................. 3-7
Tokens .................................................. 3-8
Constructs Involving Multiple Tokens ................... 3-11
Components of a Command, Response and Event ............ 3-11
SECTION 4. SPI PROGRAMMING CONSIDERATIONS FOR TR3271 ....... 4-1
Building the Command Buffer ............................... 4-1
Discontinuing a Command in Progress ....................... 4-2
Receiving and Decoding the Response Buffer ................ 4-3
Error Handling ............................................ 4-4
Security .................................................. 4-4
Command Protocol .......................................... 4-5
iii
CONTENTS
SECTION 5. COMMON DEFINITIONS .............................. 5-1
SPI Standard Definitions .................................. 5-1
EMS Standard Definitions .................................. 5-9
Data-Communications Standard Definitions ................. 5-11
Common Definitions for the TR3271 Subsystem .............. 5-17
TR3271 Buffer Declarations ............................. 5-17
TR3271 Predefined Token and Field Values ............... 5-18
TR3271 Simple Tokens ................................... 5-18
TR3271 Extensible Structured Tokens .................... 5-19
TR3271 Tokens in Error Lists ........................... 5-19
TR3271 Tokens in Event Messages ........................ 5-20
SECTION 6. COMMANDS AND RESPONSES .......................... 6-1
Commands by Object Type ................................... 6-4
Sensitive and Nonsensitive Commands ....................... 6-6
Command Descriptions ...................................... 6-6
ABORT Command ........................................... 6-8
ADD Command ............................................ 6-13
ALTER Command .......................................... 6-20
CONNECT Command ........................................ 6-31
DELETE Command ......................................... 6-36
DISCONNECT Command ..................................... 6-41
GETVERSION Command ..................................... 6-46
INFO Command ........................................... 6-50
LISTOBJECTS Command .................................... 6-63
LOAD Command ........................................... 6-68
RESET Command .......................................... 6-72
RESETSTATS Command ..................................... 6-76
START Command .......................................... 6-84
STATISTICS Command ..................................... 6-89
STATUS Command ......................................... 6-97
STOP Command .......................................... 6-108
SWITCH Command ........................................ 6-114
TRACE Command ......................................... 6-119
SECTION 7. TR3271 EVENT MANAGEMENT ......................... 7-1
Subsystem Processes That Report Events .................... 7-1
Critical Events ........................................... 7-3
Event-Management Programming .............................. 7-3
Event-Message Descriptions ................................ 7-4
3: ZTR3-EVT-IOBUS-ERR ................................... 7-6
4: ZTR3-EVT-CIU-ERR .................................... 7-10
6: ZTR3-EVT-OBJ-STARTED ................................ 7-15
7: ZTR3-EVT-OBJ-STOPPED ................................ 7-18
67: ZTR3-EVT-SUBDEV-ERR ................................ 7-21
74: ZTR3-EVT-INTL-ERR .................................. 7-24
90: ZTR3-EVT-PROC-ABEND ................................ 7-27
106: ZTR3-EVT-INSUFF-BUF ............................... 7-31
112: ZTR3-EVT-DISCARD-ERR .............................. 7-34
141: ZTR3-EVT-CLIP-DWLOAD .............................. 7-37
147: ZTR3-EVT-CSS-PROBE-ERR ............................ 7-40
157: ZTR3-EVT-CSS-FRAME-ERR ............................ 7-44
iv
CONTENTS
158: ZTR3-EVT-CSS-UNEXP-BRKPT .......................... 7-48
160: ZTR3-EVT-CSS-LIU-CONFIG-ERR ....................... 7-51
164: ZTR3-EVT-CSS-LINE-ERR ............................. 7-54
165: ZTR3-EVT-CSS-SUBDEV-ERR ........................... 7-58
-1: ZCOM-EVT-CPU-SWITCH ................................ 7-62
-2: ZCOM-EVT-PATH-SWITCH ............................... 7-65
-3: ZCOM-EVT-SUMSTATE-CHG .............................. 7-69
Examples of Filters ...................................... 7-72
Example 1 .............................................. 7-72
Example 2 .............................................. 7-73
APPENDIX A. ERROR NUMBERS AND ERROR LISTS .................. A-1
Notation Used ............................................. A-1
2: ZTR3-ERR-CLIP-PROB ................................. A-3
3: ZTR3-ERR-TARGET-OBJ-NOT-FOUND ...................... A-4
4: ZTR3-ERR-ATTR-CONFL-SU ............................. A-5
5: ZTR3-ERR-NOT-PTP-SU ................................ A-7
6: ZTR3-ERR-ALRDY-USING-ADDR .......................... A-8
7: ZTR3-ERR-NO-OBJ-IN-SEL-STATE ....................... A-9
8: ZTR3-ERR-OPENED-SU-EXIST .......................... A-10
10: ZTR3-ERR-TARGET-OBJNAME-INV ....................... A-11
11: ZTR3-ERR-NO-OWNER ................................. A-12
12: ZTR3-ERR-CONN-EXIST ............................... A-13
13: ZTR3-ERR-SU-OPENED ................................ A-14
APPENDIX B. TR3271 SUBSYSTEM DDL ........................... B-1
v
CONTENTS
FIGURES
1-1. TR3271 Subsystem Architecture ......................... 1-6
2-1. How an Application Fits Into the Architecture ......... 2-3
TABLES
2-1. TR3271 Programmatic Commands .......................... 2-4
2-2. SCF Commands and Programmatic Commands ................ 2-6
2-3. CMI Commands and Programmatic Commands ................ 2-8
4-1. Command Protocol Summary State Changes ................ 4-5
5-1. SPI Standard Definitions .............................. 5-2
5-2. EMS Standard Definitions .............................. 5-9
5-3. Data-Communications Standard Definitions ............. 5-12
6-1. Commands and Their Symbolic Names ..................... 6-2
7-1. TR3271 Event Messages ................................. 7-2
vi
PREFACE
In the Tandem environment, TR3271 provides application programs
with the ability to communicate with IBM hosts and IBM
3270-family devices. This manual provides subsystem-specific
information for application programmers using the managementprogramming interfaces to manage the TR3271 subsystem. The
management-programming interfaces are based on the Subsystem
Programmatic Interface (SPI). This manual describes the controland-inquiry interface and the Event Management Service (EMS)
interface available to an application program for subsystemmanagement purposes.
This manual is intended for application programmers in one of the
following categories:
• TAL, COBOL85, and C programmers who are writing management
applications that communicate with the TR3271 subsystem.
• TACL users who are writing macros and routines to perform
management functions on the TR3271 subsystem.
This manual serves as a reference manual for the development of
management applications. The seven sections and two appendixes
of this manual contain information as follows:
• Section 1 introduces the TR3271 subsystem and the objects
it controls. It also describes the required management
functions, the relationship of the subsystem to other
subsystems, and the architecture of the TR3271 subsystem.
• Section 2 describes management programming. This section
describes the purpose of management programming and how
applications fit into the Distributed Systems Management
(DSM) architecture. It also contains tables of TR3271
programmatic commands and a comparison of programmatic and
operator commands.
• Section 3 describes the elements of SPI messages.
vii
PREFACE
• Section 4 describes SPI programming considerations for the
subsystem. This description includes information about building the command buffer, canceling commands, receiving and
decoding response buffers, error handling, version
compatibility, and security.
• Section 5 summarizes standard SPI definitions, EMS
definitions, and data-communications definitions used by the
subsystem in multiple commands, responses, or event messages.
These definitions include token codes, token maps, token
types, token values, field types, and field values.
• Section 6 describes all available commands and associated
responses when communicating with the TR3271 subsystem.
• Section 7 describes event management for applications communi-
cating with the TR3271 subsystem. This section contains
information on how to obtain event messages reported by the
subsystem, a description of each event message that can be
issued by the subsystems, and examples of filters that could
be used by an application.
• Appendix A describes the error numbers and error lists that
can be issued by the TR3271 subsystem.
• Appendix B is a listing of the TR3271 subsystem's DDL.
To use this manual, you should be familiar with Tandem system
architecture, have a reading knowledge of DDL, and have a working
knowledge of TR3271 and the language in which you are working:
TAL, COBOL85, TACL, and C. In addition, you should be familiar
with distributed systems management. Therefore, before using
this manual, you must be familiar with the material covered in
the following Tandem manuals:
•
Data Definition Language (DDL) Reference Manual
•
Device-Specific Access Methods--AM3270/TR3271
•
Introduction to Distributed Systems Management
•
Distributed Systems Management (DSM) Programming Manual
•
Communications Management Programming Manual
•
Event Management System (EMS) Manual
viii
NOTATION CONVENTIONS
The following list summarizes the conventions used in this
manual, including the boxed descriptions of programmatic
commands, event messages, and error lists in this manual.
Notation Meaning
UPPERCASE Uppercase letters represent names from the
LETTERS definition files, SCF commands, or CMI commands;
enter these names exactly as shown.
lowercase Lowercase letters represent words that are part of
letters the notation.
Ellipsis An ellipsis immediately following a pair of brackets
... or braces indicates that you can repeat the enclosed
syntax items any number of times.
The following notation appears to the right of the description
of a token or field within a command, response, or event-message
box.
Command Message
!{} You must specify this token or field.
!... You can repeat this token or field.
!
name
Specify or omit this token or field depending on the
token, field, or value identified by
name
. See the text
for the exact nature of the dependency.
!{a} You must choose only one of the set of tokens or
fields that are indicated by !{a}, where a is the same
uppercase letter of the alphabet; for example, !{A}.
![a] You can choose zero or one of the set of tokens or
fields that are indicated by ![a], where a is the same
uppercase letter of the alphabet; for example, ![A].
!{a}... You must choose at least one--and you can choose more
than one--of the set of tokens or fields indicated by
!{a}..., where a is the same uppercase letter of the
alphabet; for example, !{A}... .
![a]... You can choose zero or one or more of the set of tokens
or fields indicated by ![a]..., where a is the same
uppercase letter of the alphabet; for example, ![A]... .
ix
NOTATION CONVENTIONS
Response Message
!{} This token or field is always present.
!... This token or field can occur multiple times.
!
name
The presence or absence of this token or field depends
on the token, field, or value identified by
the text for the exact nature of the dependency.
Event Message
!... This token or field can occur multiple times.
!
name
The presence or absence of this token or field depends
on the token, field, or value identified by
the text for the exact nature of the dependency.
name
name
. See
. See
x
SECTION 1
INTRODUCTION
This section describes management concepts applicable to the
TR3271 subsystem in the 6100 CSS environment. Although the
utilities available in a non-6100 environment are mentioned, this
section is oriented to the application programmer responsible for
managing the TR3271 subsystem in the 6100 CSS environment. Some
of the concepts discussed are the types of objects controlled
by the TR3271 subsystem and the available monitoring and control
functions.
BRIEF OVERVIEW OF TR3271
In the Tandem environment, the TR3271 access method allows
an application program to access a host computer. The host
computer can be an IBM host or a Tandem host. TR3271 emulates
one or more 3270-family controllers with multiple terminals or
printers attached. TR3271 has two distinct configurations. In
one configuration, TR3271 communicates with an application (for
example, EM3270) that allows non-3270 terminals to access an IBM
host. In the other configuration, TR3271 can be linked to AM3270
to provide pass-through function using the pass-through protocol
(PTP). While in pass-through mode, data can be passed between an
AM3270 device and a host by means of TR3271 without requiring an
intervening application program.
OBJECTS CONTROLLED BY THE SUBSYSTEM
The TR3271 subsystem controls a process, line, and subdevices
(SUs). The SU object can be added using various interfaces,
but cannot be defined to SYSGEN. The PROCESS and LINE objects,
1-1
INTRODUCTION
Required Management Functions
on the other hand, are defined at system-generation time, but
can be dynamically added or deleted using Configuration Utility
Program (COUP) commands available through the Dynamic System
Configuration (DSC) facility. Refer to the
Configuration Manual
for details.
Dynamic System
In the TR3271 subsystem, a Tandem system communicates with an
individual physical device by means of physical communications
lines. Each communications line is controlled by an I/O process
that is referred to by its process object name. In TR3271, each
I/O process controls one line. Therefore, you can identify a
process by using the name associated with the line controlled by
the process.
A line can have as many as 253 subordinate subdevices. Once
a subdevice is added and started, an application accesses the
subdevice--with the exception of pass-through protocol (PTP)
subdevices--through file-system requests such as OPEN and performs poll and select operations using READ and WRITE.
PTP subdevices are handled differently from other subdevices.
Once added and started, a TR3271 PTP subdevice must be connected
to an AM3270 PTP subdevice using the CONNECT command through
the control-and-inquiry interface or the CONTROL CONNECT command
through the Communications Management Interface (CMI). Data
transfer between AM3270 and TR3271 occurs without an intervening
application. The application on the host does not explicitly use
the OPEN, READ, and WRITE file-system requests for data transfer
because they rely on the message-system interface.
A line within an TR3271 subsystem can be identified by its
unique line object name. Each subdevice can be identified by its
subdevice object name. You must assign a unique name to each
subdevice configured on a single line. Subdevices on separate
lines can have identical names; therefore, you must use the line
name in addition to the subdevice name to reference a specific
subdevice. For details on object names, see "Object Names" in
Section 3, "Elements of SPI messages for the Subsystem."
REQUIRED MANAGEMENT FUNCTIONS
Management of a subsystem involves monitoring and controlling the
objects defined in the subsystem, and monitoring and handling
events occurring in the subsystem.
The ability to monitor the TR3271 subsystem is significant. With
the information made available to you through monitoring, you
can make decisions needed to maintain a productive computing
environment.
1-2
INTRODUCTION
Required Management Functions
Monitoring your subsystem includes such tasks as the following:
• Obtaining the version level of the subsystem software
• Obtaining current attribute values for a line and subdevices
• Obtaining the names of lines and subdevices known to the
subsystem
• Obtaining the current values of the statistics counters for
lines and subdevices
• Obtaining information about the current states of the line and
subdevices
• Retrieving information about events occurring in the subsystem
After gaining this information, you can make informed decisions
for controlling your subsystem. Action can be taken either
programmatically or interactively with the available commands.
Controlling your subsystem includes such tasks as the following:
• Terminating the operation of a line and subdevices
• Adding subdevices to the subsystem
• Changing certain attributes of a line and subdevices
• Establishing or clearing the link between a TR3271 subdevice
and an AM3270 subdevice when using the pass-through configuration
• Removing subdevices from the subsystem
• Downloading the Communications Line Interface Processor (CLIP)
• Placing the CLIP in the boot state
• Obtaining the current values of the statistics counters for a
line and subdevices
• Resetting the statistics counters
• Initiating the operation of a line and subdevices
• Changing the system resources used by a process or a line
• Tracing the activity on a line
• Taking remedial action, if necessary, in response to event
information previously retrieved
1-3
INTRODUCTION
Relationship With Other Subsystems
RELATIONSHIP WITH OTHER SUBSYSTEMS
The TR3271 subsystem is closely related to the AM3270 subsystem.
The two subsystems can be linked by connecting an AM3270
subdevice with a TR3271 subdevice. When linked in this way,
data from AM3270 terminals can be passed to the host through
TR3271, and data from the host can be passed to the AM3270
terminals through AM3270 without the necessity for an intervening
application program.
You can selectively switch an AM3270 terminal between the control
of a PATHWAY application and the control of TR3271 connected to
an IBM host. Of course, there must be communication between
the PATHWAY application and the user application associated with
TR3271 to determine which is the controlling application.
1-4
INTRODUCTION
Subsystem Architecture
SUBSYSTEM ARCHITECTURE
The TR3271 subsystem consists of one process controlling one
line. However, the subsystem can be combined to provide a passthrough function between AM3270 terminals and a host by means of
TR3271. Figure 1-1 illustrates the architecture of the TR3271
subsystem and the various interfaces to the subsystem.
3270 Terminals
and Printers
Interactive
Interfaces
CMI
CUP
COUP
SCF
3271 Cluster
Controller
$TR
Line
TR3271
I/O Process
Host
Programmatic
Interfaces
EMS
SCP
VIEWPOINT
Figure 1-1. TR3271 Subsystem Architecture
S8009-001
1-5
INTRODUCTION
Subsystem Architecture
You can manage the TR3271 subsystem through both interactive and
programmatic interfaces. The interactive interfaces for managing
the TR3271 subsystem are the following:
• The Subsystem Control Facility (SCF), which can be used to
monitor, configure, and control the TR3271 subsystem. SCF
provides an operator interface to the Subsystem Control Point
(SCP) which provides an interface to the TR3271 subsystem.
SCF can be used for the TR3271 subsystem only in 6100 CSS
environments.
• The Communications Management Interface (CMI), which can be
used to configure and control the line and subdevices, as well
as to obtain information from the TR3271 subsystem about the
line and subdevices. This interface can be used only in the
6100 Communications Subsystem (6100 CSS) environment and is
being replaced with SCF.
• The Configuration Utility Program (COUP), which can be used to
dynamically add or delete processes and lines.
• VIEWPOINT, which can be used to monitor event messages that
display at the VIEWPOINT console.
The programmatic interfaces for managing the TR3271 subsystem are
the following:
• The control-and-inquiry interface, which provides control and
inquiry capability to an application program. An application
program can send a command to a subsystem to control the
subsystem or to obtain information.
• The Event Management Service (EMS) interface which provides
event-management capability to an application program. This
interface allows an application program to retrieve event
messages previously sent to EMS by the subsystem.
The programmatic management interfaces use SPI message formats
and conventions and can only be used in a 6100 CSS environment.
When selecting the interfaces that would best serve your management needs, determine the features and capabilities of each and
the environment in which they will be used.
1-6
SECTION 2
MANAGEMENT PROGRAMMING FOR TR3271
You can manage the TR3271 subsystem interactively or programmatically. For 6100 CSS environments, the Subsystem Control Facility
(SCF), the Communications Management Interface (CMI), and
VIEWPOINT provide interactive subsystem management, while the
control-and-inquiry interface and the Event Management Service
(EMS) interface provide programmatic subsystem management. Note
that although the Configuration Utility Program (COUP) is an
interactive interface, it will not be compared with the controland-inquiry interface. COUP has limited application to the
TR3271 subsystem; you can only add or delete a process or line
using this facility.
The division of management tasks between operator control and
programmatic control depends upon the subsystem configuration,
the subsystem environment, and your needs as a subsystem user.
To determine the most effective division of management tasks,
you must be familiar with the functions available to you in both
the interactive and programmatic interfaces. The interactive
functions available depend on the interactive interface you
are using, SCF or CMI. Tables later in this section show
the commands available programmatically and those available
interactively.
2-1
MANAGEMENT PROGRAMMING FOR TR3271
How a Management Application Fits Into the Architecture
Managing a subsystem programmatically can mean a more efficient
use of resources as follows:
• If routine management tasks are performed programmatically
instead of interactively, the human operator can spend more
time on tasks that require more judgment and creativity.
• Where appropriate, a management application can standardize
responses to errors or other information obtained from the
subsystem. This standardization allows you to establish
procedures without having to train several operators to use
the procedures.
• A single management application can communicate with several
subsystems using an SPI interface instead of using several
different types of interactive interfaces, each providing
different capabilities.
• You have more latitude in responding to errors returned by
the subsystem. A management application can be designed to
take immediate remedial action to selected reported errors as
compared to the delay between the time the error is reported
and the operator responds.
• You can customize a management application to respond to the
specific needs of your computer system or network.
HOW A MANAGEMENT APPLICATION FITS INTO THE ARCHITECTURE
A management application uses Subsystem Programmatic Interface
(SPI) messages to communicate with the TR3271 subsystem. SPI
messages are passed between the management application and
the TR3271 subsystem by means of the Subsystem Control Point
(SCP) or the EMS interface. The function of an SPI message
determines whether the message is passed through SCP or EMS.
SCP is a management process that provides the control-andinquiry interface. EMS is a collection of processes, tools,
and interfaces that support the reporting and retrieval of event
information.
The control-and-inquiry interface differs from the EMS interface
in key areas. Most notably, the control-and-inquiry interface
requires a management application to initiate the communication
with the subsystem by sending a command through SCP to the
subsystem. The subsystem then returns the appropriate response
to the application through SCP. This means that the exchange of
a command and response between your application and the subsystem
is bidirectional and occurs synchronously.
2-2
MANAGEMENT PROGRAMMING FOR TR3271
How a Management Application Fits Into the Architecture
The EMS interface requires the subsystem to initiate the communication. The subsystem reports event information when events
happen, not in response to a request from a management application. The communication between EMS and your management application is unidirectional and occurs asynchronously. A management
application using EMS can monitor events that occur in the TR3271
subsystem. The application can thereby handle problems occurring
in the subsystem or track the current status of the subsystem.
An application can then retrieve the event messages from the
consumer distributor process. If you want your application to
retrieve only specific information, you can write a filter.
Figure 2-1 illustrates how a management application fits into the
TR3271 subsystem architecture.
SCF User
Retrieve
Event
Filter
Return
Event
Management
Application
Return
Event
Consumer
Distributor
Retrieve
Event
VIEWPOINT
TCP
Commands
Event
Messages
Commands
SCP
Responses Responses
Event
Log
Event
Messages
Compatibility
Distributor
Filter
Commands
Event
Messages
Event Messages/
Console Messages
Responses
Subsystem
SCF
TR3271
Event
Messages
EMS
Collector
($0)
Messages
Event
Other
Subsystems
Console
VIEWPOINT
User
Figure 2-1. How an Application Fits Into the Architecture
S8009-002
2-3
MANAGEMENT PROGRAMMING FOR TR3271
Commands
COMMANDS
Table 2-1 lists and briefly describes the commands that a
management application can send to the TR3271 subsystem using
the control-and-inquiry interface. For detailed descriptions of
these commands as they relate to the TR3271 subsystem, refer to
Section 6, "Commands and Responses." For a description of these
commands as they relate to all data-communications subsystems,
or for information about using SPI messages to communicate
with data-communications subsystems in general, refer to the
Communications Management Programming Manual
.
Table 2-1. TR3271 Programmatic Commands (Page 1 of 2)
COMMAND DESCRIPTION
ABORT Terminates the operation of a line and
subdevices immediately.
ADD Adds a subdevice to the TR3271
subsystem.
ALTER Changes the values of the attributes of a
line or subdevice.
CONNECT Establishes a link between a TR3271 subdevice
and an AM3270 subdevice when in
pass-through mode.
DELETE Removes subdevices from the TR3271 subsystem.
DISCONNECT Breaks the link between a TR3271 subdevice and
an AM3270 subdevice when in pass-through
mode.
GETVERSION Returns the version level and version banner
for the TR3271 subsystem.
INFO Returns the current values of the attributes
of lines and subdevices.
2-4
MANAGEMENT PROGRAMMING FOR TR3271
Commands
Table 2-1. TR3271 Programmatic Commands (Page 2 of 2)
COMMAND DESCRIPTION
LISTOBJECTS Returns the names of a line and subdevices
known to the TR3271 subsystem.
LOAD Initiates a download of the Communications
Line Interface Processor (CLIP).
RESET Places the CLIP in the boot state.
RESETSTATS Returns statistical information about a line
and subdevices and then resets the statistics
counters to the subsystem default values.
START Initiates the operation of a line and
subdevices.
STATISTICS Returns statistical information about a line
and subdevices.
STATUS Returns information about the current state of
a line and subdevices.
STOP Terminates the operation of a line and
subdevices.
SWITCH Changes the system resources used by a process
or a line.
TRACE Initiates, modifies, or terminates trace mode
on a line.
Table 2-2 shows the correspondence between the Subsystem Control
Facility (SCF) commands a human operator issues to control and
monitor the TR3271 subsystem and the programmatic commands a
management application sends to the subsystem. For clarity, the
table contains the command and object names in the form that you
must use in applications. However, later in this manual, for
example in the text and headings for the command descriptions,
the commands and object types appear in a shortened form (that
is, without the ZCOM-CMD- and ZCOM-OBJ- prefixes).
2-5
MANAGEMENT PROGRAMMING FOR TR3271
Commands
Table 2-2. SCF Commands and Programmatic Commands (Page 1 of 2)
SCF COMMAND PROGRAMMATIC COMMAND
AND OBJECT TYPE AND OBJECT TYPE
ABORT LINE ZCOM-CMD-ABORT ZCOM-OBJ-LINE
ABORT SU ZCOM-CMD-ABORT ZCOM-OBJ-SU
ADD SU ZCOM-CMD-ADD ZCOM-OBJ-SU
ALTER LINE ZCOM-CMD-ALTER ZCOM-OBJ-LINE
ALTER SU ZCOM-CMD-ALTER ZCOM-OBJ-SU
BOOT LINE ZCOM-CMD-RESET ZCOM-OBJ-LINE
CONNECT SU ZCOM-CMD-CONNECT ZCOM-OBJ-SU
DELETE SU ZCOM-CMD-DELETE ZCOM-OBJ-LINE*
ZCOM-CMD-DELETE ZCOM-OBJ-SU
DISCONNECT SU ZCOM-CMD-DISCONNECT ZCOM-OBJ-SU
INFO LINE ZCOM-CMD-INFO ZCOM-OBJ-LINE
INFO SU ZCOM-CMD-INFO ZCOM-OBJ-SU
LOAD LINE ZCOM-CMD-LOAD ZCOM-OBJ-LINE
NAMES LINE ZCOM-CMD-LISTOBJECTS ZCOM-OBJ-LINE
ZCOM-OBJ-SU
ZCOM-OBJ-NULL
* The LINE object can be specified, but the SUB
modifier must be present. The only valid value
for the SUB modifier is ZCOM-VAL-SUB-ONLY.
2-6
MANAGEMENT PROGRAMMING FOR TR3271
Commands
Table 2-2. SCF Commands and Programmatic Commands (Page 2 of 2)
SCF COMMAND PROGRAMMATIC COMMAND
AND OBJECT TYPE AND OBJECT TYPE
PRIMARY PROCESS ZCOM-CMD-SWITCH ZCOM-OBJ-PROC
START LINE ZCOM-CMD-START ZCOM-OBJ-LINE
START SU ZCOM-CMD-START ZCOM-OBJ-SU
STATS LINE ZCOM-CMD-STATISTICS ZCOM-OBJ-LINE
STATS SU ZCOM-CMD-STATISTICS ZCOM-OBJ-SU
STATS LINE, ZCOM-CMD-RESETSTATS ZCOM-OBJ-LINE
RESET
STATS SU, ZCOM-CMD-RESETSTATS ZCOM-OBJ-SU
RESET
STATUS LINE ZCOM-CMD-STATUS ZCOM-OBJ-LINE
STATUS SU ZCOM-CMD-STATUS ZCOM-OBJ-SU
STOP LINE ZCOM-CMD-STOP ZCOM-OBJ-LINE
STOP SU ZCOM-CMD-STOP ZCOM-OBJ-SU
SWITCH LINE ZCOM-CMD-SWITCH ZCOM-OBJ-LINE
TRACE LINE ZCOM-CMD-TRACE ZCOM-OBJ-LINE
VERSION ZCOM-CMD-GETVERSION ZCOM-OBJ-NULL
VERSION PROCESS
VERSION LINE ZCOM-OBJ-PROC
For detailed descriptions of the SCF commands, refer to the
Subsystem Control Facility (SCF) Reference Manual
.
2-7
MANAGEMENT PROGRAMMING FOR TR3271
Commands
Table 2-3 shows the correspondence between the Communications
Management Interface (CMI) commands a human operator issues to
control and monitor the TR3271 subsystem and the programmatic
commands a management application sends to the subsystems. For
clarity, the table contains the command and object names in the
form that you must use in applications.
Table 2-3. CMI Commands and Programmatic Commands (Page 1 of 3)
CMI COMMAND PROGRAMMATIC COMMAND
AND OBJECT TYPE AND OBJECT TYPE
ABORT LINE ZCOM-CMD-ABORT ZCOM-OBJ-LINE
ABORT SU ZCOM-CMD-ABORT ZCOM-OBJ-SU
ADD SUB ZCOM-CMD-ADD ZCOM-OBJ-SU
ALTER LINE ZCOM-CMD-ALTER ZCOM-OBJ-LINE
ALTER PROCESS, ZCOM-CMD-SWITCH ZCOM-OBJ-LINE
PATH
ALTER PROCESS, ZCOM-CMD-SWITCH ZCOM-OBJ-PROC
CPU
ALTER SU ZCOM-CMD-ALTER ZCOM-OBJ-SU
CONTROL SU, ZCOM-CMD-CONNECT ZCOM-OBJ-SU
CONNECT
CONTROL LINE, ZCOM-CMD-LOAD ZCOM-OBJ-LINE
LOAD
CONTROL LINE, ZCOM-CMD-RESET ZCOM-OBJ-LINE
RESET
2-8
MANAGEMENT PROGRAMMING FOR TR3271
Commands
Table 2-3. CMI Commands and Programmatic Commands (Page 2 of 3)
CMI COMMAND PROGRAMMATIC COMMAND
AND OBJECT TYPE AND OBJECT TYPE
DELETE SU ZCOM-CMD-DELETE ZCOM-OBJ-LINE*
ZCOM-CMD-DELETE ZCOM-OBJ-SU
CONTROL SU, ZCOM-CMD-DISCONNECT ZCOM-OBJ-SU
DISCONNECT
None ZCOM-CMD-GETVERSION ZCOM-OBJ-NULL
ZCOM-OBJ-PROC
INFO LINE ZCOM-CMD-INFO ZCOM-OBJ-LINE
INFO SU ZCOM-CMD-INFO ZCOM-OBJ-SU
INFO LINE, ZCOM-CMD-LISTOBJECTS ZCOM-OBJ-LINE
NAMES
INFO SU, ZCOM-CMD-LISTOBJECTS ZCOM-OBJ-SU
NAMES
None ZCOM-CMD-LISTOBJECTS ZCOM-OBJ-NULL
START LINE ZCOM-CMD-START ZCOM-OBJ-LINE
START SU ZCOM-CMD-START ZCOM-OBJ-SU
STATUS LINE ZCOM-CMD-STATUS ZCOM-OBJ-LINE
STATUS SU ZCOM-CMD-STATUS ZCOM-OBJ-SU
* The LINE object can be specified, but the SUB
modifier must be present. The only valid value
for the SUB modifier
is ZCOM-VAL-SUB-ONLY.
2-9
MANAGEMENT PROGRAMMING FOR TR3271
Event Messages
Table 2-3. CMI Commands and Programmatic Commands (Page 3 of 3)
CMI COMMAND PROGRAMMATIC COMMAND
AND OBJECT TYPE AND OBJECT TYPE
STATUS LINE, ZCOM-CMD-STATISTICS ZCOM-OBJ-LINE
DETAIL
STATUS SU, ZCOM-CMD-STATISTICS ZCOM-OBJ-SU
DETAIL
STATUS LINE, ZCOM-CMD-RESETSTATS ZCOM-OBJ-LINE
RESET
STATUS SU, ZCOM-CMD-RESETSTATS ZCOM-OBJ-SU
RESET
STOP LINE ZCOM-CMD-STOP ZCOM-OBJ-LINE
STOP SUBDEVICE ZCOM-CMD-STOP ZCOM-OBJ-SU
TRACE LINE ZCOM-CMD-TRACE ZCOM-OBJ-LINE
For detailed descriptions of the CMI commands, refer to the
Communications Management Interface (CMI) Operator’s Guide
.
EVENT MESSAGES
An event message describes an event that has occurred in a
subsystem, such as a hardware error or a software error. All
event messages are in SPI message format.
All event messages issued by the TR3271 subsystem are sent to
the EMS collector process ($0). These event messages are then
placed into the user-specified log files. Once placed into the
log files, the consumer distributor process can read the event
messages and retrieve the selected events for the management
application.
2-10
MANAGEMENT PROGRAMMING FOR TR3271
Communicating With the TR3271 Subsystem
The management application retrieves event messages by sending
commands in SPI message format to an EMS consumer distributor.
To select event messages, you can write a filter that is specific
to your needs. If no filter is used, all event messages in
the log file are passed to the management application by the
consumer distributor. Figure 2-1 illustrates the flow of data
between the TR3271 subsystem and a management application in the
EMS environment. For detailed descriptions of event messages
and event management as they relate to the TR3271 subsystem,
refer to Section 7, "Event Management." For a description of
event messages and event management in general, refer to the
Event Management Service (EMS) Manual
monitor event through VIEWPOINT. Reffer to the
. Note that an operator can
VIEWPOINT Manual
for details.
COMMUNICATING WITH THE TR3271 SUBSYSTEM
A management application communicates with the TR3271 subsystem
by means of SCP or the EMS distributor process. When communicating with SCP or EMS, an application calls SPI procedures to
build messages to be sent to the subsystem and to retrieve
messages sent from the subsystem. However, to send and receive
SPI messages, and to establish and terminate communication with
SCP or the EMS distributor process, an application must use the
GUARDIAN 90 file system. How you use the GUARDIAN 90 file system
depends on the language in which your application is written.
If your application is written in TAL, you use the file-system
procedures directly to send and receive the SPI messages. If
your application is written in COBOL85--COBOL 74 does not support
SPI--you use the file-system procedures indirectly by invoking
them through COBOL85 verbs. If your application is written in
TACL, you use the file-system procedures indirectly by invoking
them through TACL built-ins.
2-11
MANAGEMENT PROGRAMMING FOR TR3271
Communicating With the TR3271 Subsystem
Regardless of the language you are using, the tasks an application must perform when communicating with either SCP or the EMS
distributor process are as follows:
1. Establish communication with SCP or the EMS distributor
process.
2. Call SPI procedures to build a message.
3. Send the message to SCP or the EMS distributor process.
4. Receive the response.
5. Check for error codes and handle any error.
6. Decode the response.
7. Take appropriate action and return to step 2, if necessary.
8. Terminate communication with SCP or the EMS distributor
process.
All data-communications subsystems must use the same message
protocol for communicating with SCP. For details on this
protocol, refer to the
Manual
Manual
and the
Distributed Systems Management (DSM) Programming
. For details on communicating with the EMS distributor
Communications Management Programming
process for the TR3271 subsystem, refer to Section 7, "Event
Management." For general information about communicating with
the EMS distributor process, refer to the
Service (EMS) Manual
.
Event Management
2-12
SECTION 3
ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM
The Subsystem Programmatic Interface (SPI) procedures facilitate
the communication between a management application and the TR3271
subsystem. These procedures allow a management application to
build commands in SPI message format to be sent through SCP
to the subsystem. These procedures also allow a management
application to decode the responses from the subsystem that have
been sent through SCP in SPI message format. However, GUARDIAN
90 procedures, not SPI procedures, are used to transport SPIformatted commands and responses between a management application
and SCP, and between SCP and a subsystem. For details on message
transport, refer to the
Programming Manual
.
Distributed Systems Management (DSM)
NOTE
SCP is responsible for the communication between SCP and
the TR3271 subsystem. Your management application needs to
be concerned only with the steps enumerated in Section 2,
"Management Programming for TR3271."
SPI procedures are also used to obtain complete event messages
from the Event Management Service (EMS) distributor process.
The EMS procedure EMSGET is used to extract tokens from event
messages, and the EMS procedure EMSTEXT is used to obtain text
versions of event messages. Like commands and responses sent
through SCP, event messages are sent and received in SPI message
format.
3-1
ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM
The commands sent to the subsystem and the responses and event
messages received from the subsystem are made up of tokens.
The concept of tokens is described in the
Management Manual
. See Section 5, "Common Definitions," in this
Distributed Systems
manual for an explanation of tokens present in multiple commands,
responses, or event messages for the TR3271 subsystem.
This manual does not attempt to give a complete explanation
of tokens; it provides subsystem-specific information about the
tokens used to communicate with the TR3271 subsystem. General
information about tokens can be found in the
Management (DSM) Programming Manual
, and information about tokens
Distributed Systems
common to all data-communications subsystems can be found in the
Communications Management Programming Manual
.
DEFINITION FILES
Definition files supplied by Tandem provide declarations of
commonly needed tokens and other variables, as well as structures
and values. The declaration names in these files have a standard
form that identifies the definition file they come from and
what the declaration defines. In addition, each source of
definitions, such as the TR3271 subsystem or SPI, has associated
with it a set of five definition files: one in TAL, one in
COBOL85, one in TACL, one in C, and one in DDL. The definition
files in TAL, COBOL85, and TACL are derived from the definition
file in DDL.
To include the definition files in your management application,
use the mechanism that is appropriate for the programming
language in which the application is written. Some of the
mechanisms are as follows:
• In TAL, source in the definition files using ?SOURCE compiler
directives.
• In COBOL85, copy the definition files into your program using
COPY statements.
• In TACL, load the definition files using LOAD commands.
The definitions in a COBOL85 definition file are grouped into
sections to enable COBOL85 programmers to declare multiple copies
of structures in the definition file. When programming in TAL,
always source in the entire definition file, and when using TACL,
always load the entire file. For further information on how a
management application accesses definition files, refer to the
Distributed Systems Management (DSM) Programming Manual
.
3-2
Loading...