HP TR3271 Owner's manual

Networking and Data Communications Library
Tandem Computers Incorporated
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

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 management-
programming interfaces to manage the TR3271 subsystem. The
management-programming interfaces are based on the Subsystem
Programmatic Interface (SPI). This manual describes the control-
and-inquiry interface and the Event Management Service (EMS)
interface available to an application program for subsystem-
management 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 build-
ing 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 name . See
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 name . See
the text for the exact nature of the dependency.
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 Dynamic System
Configuration Manual for details.
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 per-
forms 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 configura-
tion
•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 pass-
through 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.
S8009-001
3270 Terminals
and Printers
3271 Cluster
Controller
Host
Interactive
Interfaces
CMI
CUP
COUP
SCF
VIEWPOINT
TR3271
I/O Process
Programmatic
Interfaces
EMS
SCP
$TR
Line
Figure 1-1. TR3271 Subsystem Architecture
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 manage-
ment 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 programmati-
cally. 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 control-
and-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-and-
inquiry 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 communi-
cation. The subsystem reports event information when events
happen, not in response to a request from a management applica-
tion. The communication between EMS and your management applica-
tion 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.
S8009-002
Compatibility
Distributor Filter Console
VIEWPOINT
User
VIEWPOINT
TCP
Event
Log
Event
Messages Event Messages/
Console Messages
EMS
Collector
($0)
Return
Event Retrieve
Event
Event
Messages
Event
Messages
Return
Event
Retrieve
Event
Management
Application
Commands
Responses Responses
Commands
Commands
Responses
SCF
SCF User
SCP
Filter Consumer
Distributor
Event
Messages
Event
Messages
TR3271
Subsystem
Other
Subsystems
Figure 2-1. How an Application Fits Into the Architecture
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