HP TR3271 Programming Manual

Download

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.

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

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

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

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

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

. See

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

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM

Definition Files

A management application that communicates with the TR3271 subsystem must include the following definition files in the appropriate programming language, where

xxx

represents one of

four specific abbreviations for COBOL85, TAL, TACL, C, or DDL and

subsys

represents a subsystem identifier:

• The SPI definition file, ZSPIDEF.ZSPI

• The EMS definition file, ZSPIDEF.ZEMS

xxx

. This definition file is needed only if the application retrieves event messages or controls its EMS distributor environment

• The data-communications definition file, ZSPIDEF.ZCOM

• The TR3271 definition file, ZSPIDEF.ZTR3

• If the application communicates with other subsystems, the

definition file ZSPIDEF.Z

subsysxxx

for each of the other

xxx

subsystems must also be included.

An example of the definition files needed by an TR3271 application written in COBOL85 that retrieves event messages is as follows:

ZSPIDEF.ZSPICOB SPI definitions ZSPIDEF.ZEMSCOB EMS definitions ZSPIDEF.ZCOMCOB Data-communications definitions ZSPIDEF.ZTR3COB TR3271 definitions

These files are located on the disk volume chosen by your site. The default disk volume used by the INSTALL program is $SYSTEM.

Section 5, "Common Definitions," lists the SPI, EMS, and datacommunications standard definitions used by the TR3271 subsystem. For detailed descriptions of these standard definitions, refer to the the

Management Programming Manual

Distributed Systems Management (DSM) Programming Manual

Event Management Service (EMS) Manual

, and the

Communications

, respectively. The declarations in

the TR3271 definition files are described in this manual and are listed in Appendix B.

NOTE

This manual uses DDL to describe all tokens. For a quick explanation of DDL, refer to the appendix "Overview of DDL for SPI" in the

Programming Manual

Distributed Systems Management (DSM)

. If you are programming in TAL or TACL, substitute a circumflex (^) for each hyphen in a definition name as it appears in this manual. For example, ZCOM-OBJSU becomes ZCOM^OBJ^SU in TAL and TACL.

3-3

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM Naming Rules and Guidelines for Applications

NAMING RULES AND GUIDELINES FOR APPLICATIONS

All items in definition files are assigned symbolic names as well as numbers. Use the symbolic names to prevent transcription errors and to improve readability. Tandem uses names beginning with the letter Z for all definitions and all component fields of structures in its definition files. To avoid present and future conflicts with names defined by Tandem, do not begin any name you define in your application with uppercase or lowercase Z.

COMMON SYNTAX ELEMENTS FOR THE SUBSYSTEMS

The remainder of this section contains subsystem-specific information about elements of commands, responses, and event messages. For more complete information about these elements as they relate to data-communications subsystems, refer to the

Management Programming Manual

Communications

Command Numbers

Command numbers specify a command to the TR3271 subsystem or a response to a management application. The management application uses a symbolic name to express the command number to the TR3271 subsystem and the subsystem uses the symbolic name to identify the corresponding response. The symbolic name is of the form ZCOM-CMD-

name

, where

name

identifies the command. For example, ZCOM-CMD-ADD identifies the ADD command in all datacommunications subsystems, including the TR3271 subsystem.

The command number specified by the management application is stored in the header of the command message. The subsystem and management application can read the command number from the header using the token ZSPI-TKN-COMMAND in the SSGET SPI procedure.

Your management application does not normally use the token ZSPI-TKN-COMMAND to place the command number into the message header since the command number to be specified is already known. Instead, to place the command number into the message header, your management application only needs to use the symbolic name of the form ZCOM-CMD-

name

, which is the value of the token ZSPI-

TKN-COMMAND, in the SSPUT SPI procedure.

3-4

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM

Command Numbers

Although all data-communications subsystems must use symbolic names of the form ZCOM-CMD-

name

, each subsystem defines which command numbers it supports. The TR3271 subsystem supports the following commands:

ABORT LOAD ADD RESET ALTER RESETSTATS CONNECT START DELETE STATISTICS DISCONNECT STATUS GETVERSION STOP INFO SWITCH LISTOBJECTS TRACE

These commands are described in Section 6, "Commands and Responses."

Object Types

Object-type numbers represent the object type (class) of an object. The value of the object-type number is subsystemspecific and has a symbolic name. The symbolic name of the value is of the form ZCOM-OBJ-

type

, where

type

identifies the object type. For example, ZCOM-OBJ-SU identifies the subdevice object type in data-communications subsystems, including the TR3271 subsystem.

Note that object-type numbers are part of the header of each command and response. The header token named ZSPI-TKN-OBJECTTYPE contains the object-type number. However, if there are multiple objects in a response or an object is returned within a data list, an object-type number is contained in the ZCOM-TKNOBJTYPE token. The symbolic name of the value is also of the form ZCOM-OBJ-

type

, where

type

identifies the object type.

The TR3271 subsystem supports the following object types:

PROCESS LINE SU NULL

The objects controlled by the TR3271 subsystem are organized in a hierarchy by object type. In descending order, the hierarchy is PROCESS, LINE, and SU. The NULL object type is not within the hierarchy and applies to only two commands, GETVERSION and LISTOBJECTS.

3-5

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM Object Names

Object Names

An object name identifies a specific object. The object specified by an object name belongs to one of the object types PROCESS, LINE, or SU. The NULL object type does not have an object name associated with it.

In the TR3271 subsystem, there is a one-to-one correspondence between a process and a line. Therefore, you can identify a process by using the same object name associated with the line controlled by the process.

When you assign an object name to a line, you must assign a unique name. The name must be preceded by a dollar sign ($) and can have a maximum of seven alphanumeric characters, not including the dollar sign. The first character following the dollar sign must always be a letter. An example of a valid object name for a line is $TR3271A.

When you assign an object name to a subdevice, you must assign a unique name to each subdevice on a single line. The name must be preceded by a pound sign (#) and can have a maximum of seven alphanumeric characters, not including the pound sign. The first character following the pound sign must always be a letter. Subdevices on separate lines can have identical object names; therefore, the line name and a period must precede the subdevice name to reference a specific subdevice. An example of a valid object name for a subdevice is $TR3271A.#TERM1.

Some TR3271 commands can affect multiple objects. You must use the subordinate-modifier token, ZCOM-TKN-SUB, to indicate that a command affects multiple objects.

The select-state modifier, ZCOM-TKN-SEL-SUMSTATE, allows your management application to select objects based on their summary state. Your management application can use the select-state modifier only in the STATUS command. In fact, for the STATUS command, the TR3271 subsystem allows your management application to use the subordinate-modifier token, the select-state modifier token, or both to indicate that a command affects multiple objects.

Note that the TR3271 subsystem does not support object-name templates.

3-6

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM

Event Numbers

Event numbers identify event messages issued by the TR3271 subsystem and most event numbers correspond to the numbers that identify console messages which are described in the manual

Operator Messages: Console Format

. Each event message that can be reported by the TR3271 subsystem has a different event number assigned to it. The TR3271 event numbers and their associated event messages are described in Section 7, "Event Management."

An event number is part of the header of an event message. The header token named ZEMS-TKN-EVENTNUMBER contains the event number. The value of the event number is subsystem-specific and also has a symbolic name. Because event numbers represent unique events for a particular subsystem, you must know both the event number and the three-character abbreviation of the subsystem that created the event. The symbolic name of event numbers are of the form Z abbreviation for the subsystem and

subsys

-EVT-

event

, where

subsys

event

is a three-character identifies the event.

The TR3271 subsystem is represented by the abbreviation TR3.

Subjects of Event Messages

The subject of an event message is always preceded by the ZEMSTKN-SUBJECT-MARK token and is made up of two parts: the logical device name and the logical device number of the subsystem process reporting the event. The logical device name is a 32-byte file name in the internal format, which includes the name of the system node. The ZEMS-TKN-LDEVNAME token contains the logical device name. The logical device number is an unsigned integer and is contained by the ZEMS-TKN-LDEV token.

The application obtains the subject of an event message by passing the ZEMS-TKN-SUBJECT token to the EMSGET procedure. Refer to the

Event Management Service (EMS) Manual

for details on

obtaining subjects of event messages.

3-7

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM Tokens

Tokens

The TR3271 subsystem uses tokens for parameters in commands, responses to commands, and elements of event messages. Each token has a token code and token value associated with it. A token code is an identifying tag that programs refer to by name, and a token value is a data item that programs also refer to by name. The token code has two parts: a token type that specifies the data type and length of the token value, and a token number that uniquely identifies the token for the subsystem. See "Token Types" in this section for a list of the token types used in the TR3271 subsystem.

The actual token value can be in one of the following forms:

• A single field, such as an integer or a character string

• A fixed structure

• An extensible structure

Tokens that have a token value that is a single field or a fixed structure are called simple tokens. Tokens that have a token value that is an extensible structure are called extensible structured tokens.

Simple Tokens

Simple tokens are tokens whose values are single fields or fixed structures. The token codes for the simple tokens used by the TR3271 subsystem are represented by symbolic names of the form Z

subsys

abbreviation and

-TKN-

name

, where

name

identifies the token code. For example,

subsys

is a three-character subsystem

the token code ZEMS-TKN-LDEV identifies a simple token that contains a logical device number. They are considered simple tokens because you do not need a map to decode or build the structure.

3-8

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM

Tokens

Extensible Structured Tokens

Extensible structured tokens--tokens whose values are extensible structures--are identified by special token codes called token maps. The structures are defined in a DDL definition associated with each token map. The token maps for the extensible structured tokens used by the TR3271 subsystem are represented by symbolic names of the form Z is a three-character subsystem abbreviation and

subsys

-MAP-

name

, where

name

subsys

identifies the token map. For example, the token map ZTR3-MAP-INFO-SU identifies an extensible structured token that contains all the configuration parameters for a subdevice.

All TR3271 commands can contain extensible structured tokens and all of the commands contain the ZCOM-MAP-REQID token map. Currently, only the ADD and ALTER commands use extensible structured tokens defined by the TR3271 subsystem within the command buffer. These extensible structured tokens are declared in the definition files for the TR3271 subsystem. Note that extensible structured tokens do not appear in any event message issued by the TR3271 subsystem.

Responses to the following TR3271 commands can contain extensible structured tokens:

INFO RESETSTATS STATISTICS STATUS

Token Types

The token types used by the TR3271 subsystem are represented by symbolic names of the form Z three-character subsystem abbreviation and

subsys

-TYP-

name

, where

name

identifies the

subsys

is a

token type. The token types used by the TR3271 subsystem are as follows:

ZSPI-TYP-INT ZSPI-TYP-BOOLEAN ZSPI-TYP-INT-PAIR ZSPI-TYP-BYTE ZSPI-TYP-INT2 ZSPI-TYP-BYTE-PAIR ZSPI-TYP-INT4 ZSPI-TYP-BYTESTRING ZSPI-TYP-LIST ZSPI-TYP-CHAR ZSPI-TYP-MARK ZSPI-TYP-CHAR8 ZSPI-TYP-SSCTL ZSPI-TYP-CHAR50 ZSPI-TYP-SSID ZSPI-TYP-CRTPID ZSPI-TYP-STRING

3-9

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM Tokens

ZSPI-TYP-ENUM ZSPI-TYP-TIMESTAMP ZSPI-TYP-FNAME ZSPI-TYP-TOKENCODE ZSPI-TYP-FNAME32 ZSPI-TYP-UINT

The TR3271 subsystem does not define any private token types; that is, no token types have names of the form ZTR3-TYP-

name

Predefined Value Names

The predefined values used by the TR3271 subsystem are represented by symbolic names Z three-character subsystem abbreviation and

subsys

-VAL-

name

, where

name

subsys

is a

identifies the predefined value. For example, the predefined value ZTR3-VALSSID represents the subsystem ID of the TR3271 subsystem that is present in all commands and responses associated with the TR3271 subsystem. The predefined value names used by the TR3271 subsystem are as follows:

ZCOM-VAL-BUFLEN ZTR3-VAL-VERSION ZTR3-VAL-EVT-BUFLEN ZSPI-VAL-FALSE ZCOM-VAL-MAXBUFLEN ZSPI-VAL-TANDEM ZTR3-VAL-SSID ZSPI-VAL-TRUE

For descriptions of these predefined value names, see the subsection "Predefined Token and Field Values" in Section 5, "Common Definitions"

Field Types

The field types used by the TR3271 subsystem are represented by symbolic names of the form Z is a three-character subsystem abbreviation and

subsys

-DDL-

name

, where

name

subsys

identifies the field type. For example, the field type ZSPI-DDL-BOOLEAN represents the Boolean data type. Some field types are defined by SPI; others are private field types defined by the subsystem.

The field types that can be used by the TR3271 subsystem are as follows:

ZSPI-DDL-BOOLEAN ZSPI-DDL-FNAME32 ZSPI-DDL-BYTE ZSPI-DDL-INT ZSPI-DDL-CHAR ZSPI-DDL-INT-PAIR ZSPI-DDL-CHAR6 ZSPI-DDL-INT2 ZSPI-DDL-CHAR8 ZSPI-DDL-INT4 ZSPI-DDL-CRTPID ZSPI-DDL-TIMESTAMP ZSPI-DDL-ENUM ZSPI-DDL-UINT ZSPI-DDL-FNAME

3-10

ELEMENTS OF SPI MESSAGES FOR THE SUBSYSTEM

Constructs Involving Multiple Tokens

The TR3271 subsystem supports two kinds of constructs that involve multiple tokens: data lists and error lists. For the TR3271 subsystem, these constructs are found only in responses from the subsystem. A data list begins with the token ZSPI-TKNDATALIST, while an error list begins with the token ZSPI-TKNERRLIST; both end with the token ZSPI-TKN-ENDLIST.

A data list is used in a response to enclose information about one object or, in some cases, a related group of objects.

An error list is used in a response to enclose information about an error or warning.

For details on these two constructs, refer to the

Systems Management (DSM) Programming Manual

Distributed

Components of a Command, Response and Event

For general information about components of a command, response, or event message, refer to the

Programming Manual

Communications Management

For information on the tokens associated with each TR3271 command, response or event message, see Section 6, "Commands and Responses," and Section 7, "Event Management," in this manual. For information about consideratins for building and retrieving SPI buffers, see Section 4, "SPI Programming Considerations for TR3271."

3-11

SECTION 4

SPI PROGRAMMING CONSIDERATIONS FOR TR3271

The

Communications Management Programming Manual

discusses general programming considerations for writing applications that use the Subsystem Programmatic Interface (SPI) to communicate with data-communications subsystems like the TR3271 subsystem. This section discusses SPI programming considerations that are specific to the TR3271 subsystem.

BUILDING THE COMMAND BUFFER

The following programming considerations apply when an application builds the command buffer for an TR3271 command.

The recommended buffer length in bytes for a command is a predefined value with the symbolic name ZCOM-VAL-MAXBUFLEN.

The subsystem does not support multiple commands in a single request message. However, some of the commands can contain the subordinate-modifier token, so one command can affect multiple objects.

The subsystem does not support continuation of a command across multiple messages, but it does support the special case of receiving multiple reply messages using the context token, as described in the

Manual

Distributed Systems Management (DSM) Programming

4-1

SPI PROGRAMMING CONSIDERATIONS FOR TR3271 Discontinuing a Command in Progress

The command buffers for all commands can contain extensible structured tokens. An extensible structured token that is to appear in a command should always be initialized by the SPI procedure SSNULL to ensure that every field of the token is initialized to its null value. This action is important because an operation will be performed if a field contains a value other than its null value. For example, in the ALTER command, if a field of the extensible structured token that describes the line attributes contains a value other than its null value, that value is assigned to the attribute corresponding to that field. Using SSNULL is important even when every field of an extensible structured token will have a value assigned to it, so that the application will continue to work if it is compiled with new definition files that add new fields to the token.

The only tokens that can appear more than once in a command are ZSPI-TKN-COMMENT and ZCOM-TKN-TRACE-OPT. ZSPI-TKN-COMMENT is the comment token, described in the

(DSM) Programming Manual

. ZCOM-TKN-TRACE-OPT is a token used

Distributed Systems Management

in the TRACE command and is described in Section 5, "Common Definitions."

If any of the other tokens in a command appear more than once, an error is returned.

DISCONTINUING A COMMAND IN PROGRESS

General programming considerations for discontinuing a command in progress are discussed in the

Programming Manual

Communications Management

The subsystem supports the use of the token ZSPI-TKN-ALLOWTYPE, which allows an application to specify, in a command operating on multiple objects, whether the subsystem should continue immediately to the next object if it failed on the previous one. If no value is specified for this token, the TR3271 subsystem continues to the next object only if no errors or warnings occurred on the previous one. The possible values for this token are ZSPI-VAL-WARN-AND-NORM and ZSPI-VAL-NORM-ONLY.

When the TR3271 subsystem discontinues a command because of an error or warning, it immediately sends a reply message to the application. The reply message contains a context token. The application can choose to resend the command, causing the TR3271 subsystem to proceed to the next object, or to abandon the command.

4-2

SPI PROGRAMMING CONSIDERATIONS FOR TR3271

Receiving and Decoding the Response Buffer

RECEIVING AND DECODING THE RESPONSE BUFFER

The following programming considerations apply when an application receives and decodes the response buffer.

In responses to TR3271 commands that operate on objects, a response record always contains response information for the operation of the command on a single object.

The subsystem supports multiple response records in a single reply message. The number of response records returned in one reply message is controlled by the value of the header token ZSPI-TKN-MAXRESP in the command. The supported values of the token ZSPI-TKN-MAXRESP are 0, -1, and n (any value greater than

0). If multiple response records are to be returned in one reply

message, the recommended buffer size in bytes for the response is a predefined value with the symbolic name ZCOM-VAL-MAXBUFLEN. If a single response record is to be returned in each reply message, the recommended buffer size in bytes for the response is the predefined value ZCOM-VAL-BUFLEN.

The subsystem supports multiple response records over multiple messages (continuation) by returning a context token when a response is continued.

The subsystem also supports the use of the token ZSPI-TKNRESPONSE-TYPE, which allows an application to specify, in a command operating on multiple objects, which kinds of response records should be returned--one for every object, or only those for objects on which errors or warnings occurred. If no value is specified for this token, the subsystems return a response record for every object.

Note that for commands such as the INFO command whose purpose is to return information, using ZSPI-TKN-RESPONSE-TYPE to request the return of only those response records for objects on which errors or warnings occurred can result in no information being returned.

The responses to the INFO, RESETSTATS, STATISTICS, and STATUS commands each contain an extensible structured token that returns the requested information.

The object-name token ZCOM-TKN-OBJNAME can appear more than once in a response record returned by the LISTOBJECTS command. This is the only case where a token might appear multiple times in a response record.

4-3

SPI PROGRAMMING CONSIDERATIONS FOR TR3271 Error Handling

ERROR HANDLING

General programming considerations for handling errors that occur when using the management-programming interfaces are discussed in the

Communications Management Programming Manual

In the programmatic control-and-inquiry interface to the subsystem, there are two values for the return token that indicate that the response record does not contain an error list. One is the value ZSPI-ERR-OK, which means that no error or warning occurred. The other is a ZCOM error number that signifies the "empty" response record. This value, ZCOM-ERREMPT-RSP, is returned, for example, when an application requests through ZSPI-TKN-RESPONSE-TYPE that only response records for objects on which errors or warnings occurred be returned, and the command finishes processing without encountering any errors or warnings.

Error-handling considerations for specific commands are described in Section 6, "Commands and Responses." The error numbers returned by the subsystems are described in Appendix A.

SECURITY

Security for the subsystems is handled by SCP, as described in the

Communications Management Programming Manual

Some of the commands are sensitive commands, meaning that they can be issued only by certain users. When an application that is not allowed to issue sensitive commands attempts to issue one, SCP returns an error. For more information on sensitive commands, refer to Section 6, "Commands and Responses."

4-4

SPI PROGRAMMING CONSIDERATIONS FOR TR3271

Command Protocol

COMMAND PROTOCOL

Table 4-1 shows the state transitions of objects as a result of some of the TR3271 commands.

Table 4-1. Command Protocol Summary State Changes

COMMAND OLD STATE NEW STATE

START STOPPED STARTED ABORT STARTED STOPPED STOP STARTED STOPPED CONNECT STARTED STARTED DISCONNECT STARTED STARTED

4-5

SECTION 5

COMMON DEFINITIONS

The management interfaces to the TR3271 subsystem use definitions from four sources: SPI standard definitions, EMS standard definitions, data-communications standard definitions, and TR3271 subsystem-specific definitions. Many of the definitions are used in multiple commands, responses, event messages, or error lists.

This section contains general information that applies to all uses of the common definitions in the interfaces to the TR3271 subsystem. Information about a definition that is specific to a particular command, response, event message, or error list is given in the description for that item.

All definitions in this section are represented in DDL. Structures, both fixed and extensible, are defined by using DDL DEF statements. For a quick explanation of DDL as it applies to SPI, refer to the appendix "Overview of DDL for SPI" in the

Distributed Systems Management (DSM) Programming Manual

SPI STANDARD DEFINITIONS

Definitions whose names begin with ZSPI- are Subsystem Programmatic Interface (SPI) standard definitions. These definitions are available to all subsystems that support SPI procedures.

Table 5-1 lists only those SPI standard definitions that are used in the management-programming interfaces to the TR3271 subsystem. It does not list SPI error numbers or definitions used only in error lists associated with those error numbers. For a description of all SPI standard definitions, refer to the

Distributed Systems Management (DSM) Programming Manual

5-1

COMMON DEFINITIONS SPI Standard Definitions

The SPI definitions applicable to the TR3271 subsystem consist of the following:

• Header tokens

• Simple tokens

• Names of token and field values

• Token types

• Fixed structures

Table 5-1. SPI Standard Definitions (Page 1 of 2)

Header Tokens Other Simple Tokens

ZSPI-TKN-CHECKSUM ZSPI-TKN-ALLOW-TYPE ZSPI-TKN-COMMAND ZSPI-TKN-COMMENT ZSPI-TKN-HDRTYPE ZSPI-TKN-CONTEXT ZSPI-TKN-LASTERR ZSPI-TKN-DATALIST ZSPI-TKN-LASTERRCODE ZSPI-TKN-ENDLIST ZSPI-TKN-LASTPOSITION ZSPI-TKN-ERRLIST ZSPI-TKN-MAX-FIELD-VERSION ZSPI-TKN-MANAGER ZSPI-TKN-MAXRESP ZSPI-TKN-RESPONSE-TYPE ZSPI-TKN-OBJECT-TYPE ZSPI-TKN-RETCODE ZSPI-TKN-SERVER-VERSION ZSPI-TKN-SERVER-BANNER ZSPI-TKN-SSID ZSPI-TKN-USEDLEN

Special Tokens Value Names

ZSPI-TKN-ADDR ZSPI-SSN-ZTR3 ZSPI-TKN-CLEARERR ZSPI-VAL-FALSE ZSPI-TKN-COUNT ZSPI-VAL-TANDEM ZSPI-TKN-DATA-FLUSH ZSPI-VAL-TRUE ZSPI-TKN-DEFAULT-SSID ZSPI-TKN-DELETE ZSPI-TKN-INITIAL-POSITION ZSPI-TKN-LEN ZSPI-TKN-NEXTCODE ZSPI-TKN-NEXTTOKEN ZSPI-TKN-OFFSET ZSPI-TKN-RESET-BUFFER

5-2

COMMON DEFINITIONS

SPI Standard Definitions

Table 5-1. SPI Standard Definitions (Page 2 of 2)

Token Types Fixed Structures

ZSPI-TYP-BOOLEAN ZSPI-DDL-BOOLEAN ZSPI-TYP-BYTE ZSPI-DDL-BYTE ZSPI-TYP-BYTE-PAIR ZSPI-DDL-CHAR ZSPI-TYP-BYTESTRING ZSPI-DDL-CHAR6 ZSPI-TYP-CHAR ZSPI-DDL-CHAR8 ZSPI-TYP-CHAR8 ZSPI-DDL-CRTPID ZSPI-TYP-CHAR50 ZSPI-DDL-ENUM ZSPI-TYP-CRTPID ZSPI-DDL-EXIOADDR ZSPI-TYP-ENUM ZSPI-DDL-FNAME ZSPI-TYP-FNAME ZSPI-DDL-FNAME32 ZSPI-TYP-FNAME32 ZSPI-DDL-INT ZSPI-TYP-INT ZSPI-DDL-INT-PAIR ZSPI-TYP-INT-PAIR ZSPI-DDL-INT2 ZSPI-TYP-INT2 ZSPI-DDL-INT4 ZSPI-TYP-INT4 ZSPI-DDL-TIMESTAMP ZSPI-TYP-LIST ZSPI-DDL-UINT ZSPI-TYP-MARK ZSPI-TYP-SSCTL ZSPI-TYP-SSID ZSPI-TYP-STRING ZSPI-TYP-TIMESTAMP ZSPI-TYP-TOKENCODE ZSPI-TYP-UINT

All SPI standard definitions are fully described in the

Distributed Systems Management (DSM) Programming Manual

. Information about these definitions that is specific to the TR3271 subsystem is given below.

ZSPI-SSN-ZTR3 specifies the subsystem number assigned to the TR3271 subsystem. This value name is defined as a constant in the SPI DDL file, ZSPIDEF.ZSPIDDL.

5-3

COMMON DEFINITIONS SPI Standard Definitions

ZSPI-TKN-ALLOW-TYPE within a command buffer indicates the conditions under which processing of a set of objects will continue. This token applies to commands that apply to multiple objects. The ALLOW-TYPE token controls whether the subsystem continues to the next object of a set when there is an error or warning during processing of the object. It does not control the response when the tokens within a command message are incorrect or missing. The TR3271 subsystem provides full support for the ALLOW-TYPE token; that is, your management application can specify any of the following values:

ZSPI-VAL-NORM-ONLY The subsystem continues to process

the next object in the set if the command completed successfully on the previous object. There cannot be an error list in the response buffer. This is the default value.

ZSPI-VAL-WARN-AND-NORM The subsystem continues to process

the next object in the set even though warnings occurred during processing of the command on the previous object. A warning is indicated by a zero value in the RETCODE token, but an error list is present.

ZSPI-VAL-ERR-WARN-AND-NORM The subsystem continues to process

the next object in the set despite errors or warnings that have occurred during processing of the command on the previous object.

ZSPI-TKN-CHECKSUM provides checksum protection against accidental corruption of the SPI buffer between calls to the SPI procedures. The possible values are:

ZSPI-VAL-FALSE indicates that there is no checksum

protection.

ZSPI-VAL-TRUE indicates that there is checksum

protection.

ZSPI-TKN-COMMAND specifies the command number of a TR3271 command. The value of this token is always ZCOM-CMD-

name

specifies the command to be performed. The commands

name

, where

supported by TR3271 are described in Section 6, "Commands and Responses."

5-4

COMMON DEFINITIONS

SPI Standard Definitions

ZSPI-TKN-COMMENT allows your management application to include information of its own which is not acted upon by the TR3271 subsystem or returned by the subsystem. A management application can include as many as 80 bytes of comment in every command. If the comment exceeds this number of bytes and causes a a command to be too large for the server's read buffer, the server is not responsible. The TR3271 subsystem only guarantees 80 bytes.

ZSPI-TKN-CONTEXT indicates to your management application whether there are more objects to process and consequently more responses to receive. This token applies only when a command references more than one object. The TR3271 subsystem places information in this token which it requires to continue execution of the command at the next object. Your management application copies the context token into a duplicate of the original command message and sends it to the subsystem. The server then processes the next object in the set, where it left off.

Once all the objects in the set are processed, the ZSPI-TKNCONTEXT is not placed in the reply by the subsystem. Its absence indicates that all objects of the set have been processed.

Note that if the TR3271 subsystem receives a command with the context token and there are no more objects to be processed, the subsystem returns a return code that is the empty response.

The contents of the ZSPI-TKN-CONTEXT are not to be used by your management application; the contents are only to be reflected back to the subsystem in a command. Only one context token can be present in a command.

ZSPI-TKN-DATALIST indicates the beginning of a data list within a response. The presence of this token depends on the value of ZSPI-TKN-MAXRESP. If the value of ZSPI-TKN-MAXRESP is nonzero, the response tokens, excluding header tokens and the ZSPI-TKNCONTEXT token, are enclosed in a data list. There can be multiple data lists within a single response buffer; however, each data list contains information about a separate object.

ZSPI-TKN-ENDLIST indicates the end of a data list or an error list within a response.

ZSPI-TKN-ERRLIST indicates the beginning of an error list. All information about warnings or errors, except ZSPI-TKN-RETCODE must be enclosed in an error list. An error list is only present if the return code is nonzero; the empty response does not contain an error list. The contents of an error list are owned by the server returning the error list. The exception is a nested error list, which may have a different owner.

5-5

COMMON DEFINITIONS SPI Standard Definitions

ZSPI-TKN-HDRTYPE indicates whether the SPI buffer is for an event message or a command. If the buffer is for a command, the value of this token is ZSPI-VAL-CMDHDR; if the buffer is for an event the value of this token is ZSPI-VAL-EVTHDR.

ZSPI-TKN-MAX-FIELD-VERSION contains the highest version associated with the nonnull fields within an extensible structured token. This value is compared to the server version. If the server version is lower than the value of the ZSPI-TKN-MAX-FIELDVERSION, then the command is rejected. The subsystem needs to be a more recent version.

ZSPI-TKN-MANAGER is an optional token in all TR3271 commands. Since the subsystem does not use a manager process, if the token is present, the TR3271 subsystem ignores it.

ZSPI-TKN-MAXRESP within a command buffer indicates the maximum number of responses your management application can accept in a response buffer. The MAXRESP token default value is provided when a management application uses the SSINIT procedure. However, if a managment application chooses to specify a value other than the default value for the MAXRESP token, the management application must specify a value using the SSPUT procedure. The TR3271 subsystem provides full support for the MAXRESP token; that is, the management application can specify any of the following values:

-1 As many responses as will fit in the response buffer can be returned. Each response will be enclosed in a data list.

0 Only one response will be returned. The response will

not be enclosed in a data list. This is the default.

n As many as n responses will be returned. Each response

will be enclosed in a data list.

ZSPI-TKN-OBJECT-TYPE specifies the object-type number of a TR3271 object. The value of this token for the TR3271 subsystem is always ZCOM-OBJ-

name

, where

name

specifies the object. The valid object types for this subsystem are PROC, LINE, SU, and NULL. The object types associated with a command vary with each command. Refer to Section 6, "Commands and Responses," to learn which objects are valid for a specific command.

5-6

COMMON DEFINITIONS

SPI Standard Definitions

ZSPI-TKN-RESPONSE-TYPE specifies which types of responses the management application wants returned. This token can apply to all commands supported by the TR3271 subsystem. The RESPONSETYPE token controls whether the subsystem returns a response for every object or returns only responses for objects that experience an error or warning. A management application can specify any of the following values:

ZSPI-VAL-ERR-AND-WARN The subsystem returns responses

about objects for which something unusual has happened. This includes errors and warnings.

ZSPI-VAL-ERR-WARN-AND-NORM The subsystem returns responses

about every object the command applies to.

ZSPI-TKN-RETCODE is the return token, which specifies whether a command completed successfully. If the command completed successfully, including when a command completes with a warning, the value of this token is zero. Note that if the empty response is returned, the value of this token is nonzero even though the command has completed successfully. If the command did not complete successfully, the value of this token indicates the reason the command failed. The meaning of each error number is subsystem-specific and possibly command-specific. For descriptions of all TR3271 error numbers, refer to Appendix A. For descriptions of all common data-communications error numbers, refer to the

Communications Management Programming Manual

ZSPI-TKN-SERVER-BANNER contains the server-banner string for the TR3271 subsystem. This token is returned only for the GETVERSION command. The server banner for TR3271 is:

TR3271- T9372C20 - 15FEB89

ZSPI-TKN-SERVER-VERSION specifies the server version of the TR3271 subsystem. This token is required in both the command buffer and the response buffer. The SSINIT procedure initializes the command buffer with this token using the value defined in the subsystem's DDL file. The value used for TR3271 is ZTR3-VALVERSION. The subsystem provides the value of this token for purposes of comparison. The value provided by the subsystem must be at least as current as the value provided by SSINIT. If it is not as current, the subsystem rejects the command.

5-7

COMMON DEFINITIONS SPI Standard Definitions

ZSPI-TKN-SSID specifies the subsystem ID. This token is required in both the command and the response. The SSINIT procedure initializes the command buffer with this token using the value defined in the subsystem's DDL file. The value used for TR3271 is ZTR3-VAL-SSID. ZTR3-VAL-SSID has the following structure definition:

def ZTR3-VAL-SSID tacl ssid.

02 Z-FILLER type character 8

value is ZSPI-VAL-TANDEM.

02 Z-OWNER redefines Z-FILLER

type ZSPI-DDL-CHAR8.

02 Z-NUM type ZSPI-DDL-INT

value is ZSPI-SSN-ZTR3.

02 Z-VSN type ZSPI-DDL-UINT

value is ZTR3-VAL-VERSION.

end.

ZSPI-TKN-USEDLEN specifies the length of the used portion of the command message. The value of this token is used to verify that the entire message has been read by the server. The value is compared to the count-read value supplied by the file-system. If the value of the ZSPI-TKN-USEDLEN is greater than the count-read value, then the TR3271 subsystem rejects the command because the command length was too long.

ZSPI-VAL-TANDEM indicates that the destination subsystem is on a Tandem system. The requester must assign this value to the owner field of the ZSPI-TKN-SSID token before sending a command to a Tandem system.

5-8

COMMON DEFINITIONS

EMS Standard Definitions

EMS STANDARD DEFINITIONS

Definitions whose names begin with ZEMS- are Event Management Service (EMS) standard definitions. These definitions are available to all subsystems that support EMS and can be found in the EMS DDL file, ZSPIDEF.ZEMSDDL.

Table 5-2 lists only those EMS standard definitions that are used in the management-programming interfaces to the TR3271 subsystem. It does not list EMS error numbers or definitions used only in error lists. For a description of all EMS standard definitions, refer to the

Event Management Service (EMS) Manual

The EMS definitions used by the TR3271 subsystem consist of the following:

• Header tokens

• Simple tokens

• Extensible structured tokens

Table 5-2. EMS Standard Definitions

Header Tokens Other Simple Tokens

ZEMS-TKN-CONSOLE-PRINT ZEMS-TKN-CU ZEMS-TKN-CPU ZEMS-TKN-LDEV ZEMS-TKN-CRTPID ZEMS-TKN-LDEVNAME ZEMS-TKN-EMPHASIS ZEMS-TKN-SUBJECT-MARK ZEMS-TKN-EVENTNUMBER ZEMS-TKN-GENTIME Extensible ZEMS-TKN-LOGTIME Structured Tokens ZEMS-TKN-PIN ZEMS-TKN-SYSTEM ZEMS-MAP-EXIOADDR ZEMS-TKN-USERID

All EMS standard definitions are fully described in the

Management System (EMS) Manual

. Information about these defini-

Event

tions that is specific to the TR3271 subsystem is given below.

5-9

COMMON DEFINITIONS EMS Standard Definitions

ZEMS-MAP-EXIOADDR is a Tandem internal extensible structured token. This token specifies the physical I/O address. This I/O I/O address scheme supersedes the subchannel-type I/O addresses previously supported using the ZEMS-TKN-CU.

ZEMS-TKN-CONSOLE-PRINT specifies whether the event messages are processed by the compatibility distributor for printing on the consoe. The value of this token for the TR3271 subsystem is always ZSPI-VAL-TRUE. The ZSPI-VAL-TRUE value causes all TR3271 event messages to print on the operator console.

ZEMS-TKN-CPU specifies the CPU of the TR3271 subsystem reporting the event.

ZEMS-TKN-CRTPID specifies the process ID of the TR3271 subsystem reporting the event.

ZEMS-TKN-CU specifies the controller and unit number of the object reprting the event. This token is present in the event message buffer only if the controller used by the I/O process uses the subchannel-type I/O addressing scheme. The information in this token is repeated in the ZEMS-MAP-EXIOADDR token. This token is volatile and is used for backward compatibility.

ZEMS-TKN-EMPHASIS specifies whether the event message is considered critical. If the value of the token is ZSPI-VAL-TRUE, the event is considered critical; if the value is ZSPI-VAL-FALSE, the event is not considered critical. The description of each event message states whether the event is critical or not.

ZEMS-TKN-EVENTNUMBER specifies the event number of a TR3271 event message. Most of the event numbers are equivalent to console message numbers in releases of GUARDIAN 90 earlier than C00. These event numbers and their associated event messages are described in Section 7, "Event Management."

ZEMS-TKN-GENTIME is the time, in Greenwich Mean Time (GMT), that the subsystem created the event message.

ZEMS-TKN-LDEV specifies the logical device number of the TR3271 line that is the subject of the event message.

ZEMS-TKN-LDEVNAME is the subject token of every TR3271 event message. This token specifies the name of the TR3271 line that is the subject of the event message. This token is always preceded by the ZEMS-TKN-SUBJECT-MARK token.

ZEMS-TKN-LOGTIME is the time, in GMT, that the EMS collector wrote the event message to its log files.

5-10

COMMON DEFINITIONS

Data-Communications Standard Definitions

ZEMS-TKN-PIN is the PIN of the TR3271 subsystem that reported the event.

ZEMS-TKN-SYSTEM is the EXPAND system number of the system (node) on which the event was reported.

ZEMS-TKN-USERID specifies the user ID of the TR3271 subsystem process.

DATA-COMMUNICATIONS STANDARD DEFINITIONS

Definitions whose names begin with ZCOM- are data-communications standard definitions. These definitions are available to all data-communications subsystems, such as TR3271, and are found in the ZSPIDEF.ZCOMDDL definition file. Refer to "Definition Files" in Section 3 for details.

Table 5-3 lists only those data-communications standard definitions that are used in the management-programming interfaces to the TR3271 subsystem. It does not list data-communications error numbers or definitions used only in error lists. For a description of all data-communications standard definitions and error numbers, refer to the

Manual

. The data-communications definitions used by the TR3271

Communications Management Programming

subsystem consist of the following:

• Simple tokens

• Extensible structured tokens

• Object types

• Fixed structures

• Command numbers

• Names of token and field values

5-11

COMMON DEFINITIONS Data-Communications Standard Definitions

Table 5-3. Data-Communications Standard Definitions

Simple Tokens Command Numbers

ZCOM-TKN-CAUSE-CPU-SWITCH ZCOM-CMD-ABORT ZCOM-TKN-CAUSE-PATH-SWITCH ZCOM-CMD-ADD ZCOM-TKN-CAUSE-SUMSTATE-CHG ZCOM-CMD-ALTER ZCOM-TKN-CMD-TIMEOUT ZCOM-CMD-CONNECT ZCOM-TKN-NEW-CPU ZCOM-CMD-DELETE ZCOM-TKN-NEW-PATH ZCOM-CMD-DISCONNECT ZCOM-TKN-OBJNAME ZCOM-CMD-GETVERSION ZCOM-TKN-OBJSTATE ZCOM-CMD-INFO ZCOM-TKN-OBJTYPE ZCOM-CMD-LISTOBJECTS ZCOM-TKN-OLD-OBJSTATE ZCOM-CMD-LOAD ZCOM-TKN-OLD-CPU ZCOM-CMD-RESET ZCOM-TKN-OLD-PATH ZCOM-CMD-RESETSTATS ZCOM-TKN-SEL-SUMSTATE ZCOM-CMD-START ZCOM-TKN-SUB ZCOM-CMD-STATISTICS ZCOM-TKN-SWITCH-CPU ZCOM-CMD-STATUS ZCOM-TKN-SWITCH-PATH ZCOM-CMD-STOP ZCOM-TKN-TARGET-MGR ZCOM-CMD-SWITCH ZCOM-TKN-TARGET-OBJNAME ZCOM-CMD-TRACE ZCOM-TKN-TARGET-OBJTYPE ZCOM-TKN-TRACE-OPT

Extensible Object Types Structured Tokens

ZCOM-OBJ-LINE ZCOM-MAP-REQID ZCOM-OBJ-NULL ZCOM-MAP-TRACE-MODIF ZCOM-OBJ-PROCESS

ZCOM-OBJ-SU

Fixed Structures Value Names

ZCOM-DDL-REQID ZCOM-VAL-PATH-A ZCOM-DDL-TRACE-MODIF ZCOM-VAL-PATH-B

ZCOM-VAL-PATH-UNDEF

ZCOM-VAL-SUB-ALL

ZCOM-VAL-SUB-NONE

ZCOM-VAL-SUB-ONLY

ZCOM-VAL-SUMSTATE-DIAG

ZCOM-VAL-SUMSTATE-STARTED

ZCOM-VAL-SUMSTATE-STOPPED

All data-communications standard definitions are fully described in the

Communications Management Programming Manual

. Information about these definitions that is specific to the TR3271 subsystem is given below. Definitions are listed in alphabetical order.

5-12

COMMON DEFINITIONS

Data-Communications Standard Definitions

ZCOM-MAP-REQID provides security checking additional to the sensitive/nonsensitive command implementation. This token contains the GUARDIAN 90 Process ID and the PAID of the application issuing the command. The REQID is valid only if the requester is the SUPER.SUPER user ID. If the user is not the SUPER.SUPER user ID and the management application specifies ZCOM-MAP-REQID in the command, or duplicates the token in the command buffer, the command is rejected with a security violation. The contents of the token are as follows:

ZCOM-MAP-REQID

def ZCOM-MAP-REQID.

02 ZCRTPID type ZSPI-DDL-CRTPID. 02 ZPAID type ZSPI-DDL-INT.

end.

ZCOM-MAP-TRACE-MODIF is the extensible structured token sent in the TRACE command by the management application; it contains the trace parameters that control the initiation of the trace file, the selection of the trace environment, and termination of trace mode. The initiation and selection is handled in one ZCOMMAP-TRACE-MODIF token. When the trace is to be terminated, the management application sends another ZCOM-MAP-TRACE-MODIF token with the ZSTOP field containing the value ZSPI-VAL-TRUE. The contents of the token are as follows:

ZCOM-MAP-TRACE-MODIF

def ZCOM-DDL-TRACE-MODIF. !All fields are required.

02 ZSTOP type ZSPI-DDL-BOOLEAN. 02 ZPRIM type ZSPI-DDL-BOOLEAN. 02 ZREC-SIZE type ZSPI-DDL-INT. 02 ZCNT type ZSPI-DDL-INT2. 02 ZXDS-PAGES type ZSPI-DDL-INT. 02 ZCOLL type ZSPI-DDL-BOOLEAN. 02 FNAME type ZSPI-DDL-FNAME32.

end.

5-13

COMMON DEFINITIONS Data-Communications Standard Definitions

ZCOM-OBJ-LINE specifies the line object type. ZCOM-OBJ-NULL is used as the object type in commands that do not

require an object-name token. Only two commands use the NULL object, GETVERSION and LISTOBJECTS.

ZCOM-OBJ-PROC specifies the process (PROC) object type for the TR3271 I/O process running on a Tandem NonStop system.

ZCOM-OBJ-SU specifies the subdevice (SU) object type for the TR3271 subsytem. The SU object can be opened in the GUARDIAN 90 environment.

ZCOM-TKN-CMD-TIMEOUT is the maximum amount of time the management application wants to wait for a response from the TR3271 subsystem. If the specified time elapses before a response is received, SCP cancels the command that was sent to the TR3271 subsystem and sends the error ZCOM-ERR-CMD-TIMED-OUT to the management application. If this token is not present in the command buffer, no timeout is applied. Duplicate occurrences of this token are not allowed.

ZCOM-TKN-OBJNAME contains the name of a TR3271 object. The object name of a LINE object is the name of a specific line

configured on a single system. These names are assigned when the line is congifured, and they are unique within a system.

The object name of an SU object is the name of a specific subdevice configured on a single line and must be unique within the line.

The NULL object has no object name. The object name of a PROC object is the object name of the line

controlled by the process. The object-name token is required in all TR3271 commands for

which the object type is not ZCOM-OBJ-NULL. If the object type for a command is ZCOM-OBJ-NULL, the object-name token must not be present.

ZCOM-TKN-OBJTYPE contains the object type of an TR3271 object. This token is present in every response. The possible values are ZCOM-OBJ-PROC, ZCOM-OBJ-LINE, and ZCOM-OBJ-SU, ZCOM-OBJ-NULL. This token occurs only in responses. However, the values are the same as the object type specified in the command header token ZSPI-TKN-OBJECT-TYPE.

The ZCOM-TKN-OBJTYPE can be present in data lists and error lists. It indicates the object type for which information is being returned, or the object type experiencing the error.

5-14

COMMON DEFINITIONS

Data-Communications Standard Definitions

ZCOM-TKN-SEL-SUMSTATE specifies whether an object is selected based on its current summary state. This modifier consists of two fields, an enumerated field that indicates the summary state, and a Boolean field that indicates whether objects currently in that summary state are to be included in the information returned by the subsystem. The STATUS command is the only TR3271 command that supports the select-state modifier.

ZCOM-TKN-SUB indicates whether or not objects subordinate to the object whose name appears in the object-name token are to be affected by the command.

This token can appear in all TR3271 commands. If the object type is ZCOM-OBJ-SU or ZCOM-OBJ-PROC, only the ZCOM-VAL-SUB-ALL and ZCOM-VAL-SUB-NONE values are accepted. These values, however, have no effect on the command. The command is processed as if the modifier were not present. If the value ZCOM-VAL-SUB-ONLY is specified for the SU or PROC object, the command is rejected.

If the object type is ZCOM-OBJ-LINE, the possible values of the subordinate modifier vary with each command. In all commands that accept ZCOM-OBJ-LINE as the object type, the value ZCOM-VALSUB-NONE is accepted. This value has no effect on the command. If the value ZCOM-VAL-SUB-ONLY is specified, only the objects subordinate to the line are affected. The objects subordinate to an TR3271 line are the subdevices on the line. If the value ZCOM-VAL-SUB-ALL is specified, the objects subordinate to the line as well as the LINE object itself are affected by the command.

ZCOM-TKN-SWITCH-CPU specifies that the TR3271 process is to be switched to another CPU. The value of this token indicates the target CPU. If it is a single port environment, the path is also changed.

ZCOM-TKN-SWITCH-PATH specifies that the path to the Communications Interface Unit (CIU) is to be switched to the backup path. The value of this token indicates the target path.

ZCOM-TKN-TARGET-MGR specifies the name of the manager controlling the AM3270 subdevice to which you want to build or tear down a link. If your management application does not provide a value, the value of the ZSPI-TKN-MANAGER token is used by the subsystem. The value of the ZCOM-TKN-TARGET-MGR token, if specified, should always be the line name associated with the AM3270 subsystem to which you want to establish a connection.

ZCOM-TKN-TARGET-OBJNAME specifies the name of the AM3270 subdevice to which you want to build or tear down a link. This token is required.

5-15

COMMON DEFINITIONS Data-Communications Standard Definitions

ZCOM-TKN-TARGET-OBJTYPE specifies the type of object to which you want to build or or tear down a link. This token is required and must have the value ZCOM-OBJ-SU.

ZCOM-TKN-TRACE-OPT indicates what items are to be traced by the TRACE command. For information on the possible values of this token, refer to the TRACE command in Section 6. SCP creates a bit mask from the trace options specified and sends it to the CMP Trace Collector (CMPTC).

ZCOM-VAL-PATH-A is a value that represents Communications Interface Unit (CIU) path A. It can occur as a value of the token ZCOM-TKN-SWITCH-PATH and of the field ZPATH of the extensible structured token ZTR3-MAP-STATUS-LINE.

ZCOM-VAL-PATH-B is a value that represents Communications Interface Unit (CIU) path B. It can occur as a value of the token ZCOM-TKN-SWITCH-PATH and of the field ZPATH of the extensible structured token ZTR3-MAP-STATUS-LINE.

ZCOM-VAL-PATH-UNDEF is a value that appears in the EMS event ZCOM-EVT-PATH-SWITCH when the Communications Interface Unit (CIU) path is first activated. The event indicates the path has been switched from being undefined to path A or path B. This value may also appear in the information returned for the line when the STATUS command is issued. This value indicates the path has not yet been activated.

ZCOM-VAL-SUB-ALL is a value of the token ZCOM-TKN-SUB indicating that the command affects both the named line and all its subordinate subdevices. If this value is specified for the PROC or SU object, the command is treated as if the modifier is not present in the command buffer.

ZCOM-VAL-SUB-NONE is a value of the token ZCOM-TKN-SUB indicating that the command affects only the named line. The subdevices subordinate to the line are not affected. If this value is specified for the PROC or SU object, the command is treated as if the modifier is not present in the command buffer.

ZCOM-VAL-SUB-ONLY is a value of the token ZCOM-TKN-SUB indicating that the command affects only the subdevices subordinate to the named line. The line itself is not affected. This value is not valid for the PROC or SU object.

ZCOM-VAL-SUMSTATE-DIAG is a value of the field ZSTATE of the extensible structured tokens ZTR3-MAP-STATUS-LINE. It indicates that a TR3271 line is in the DIAGNOSING summary state.

ZCOM-VAL-SUMSTATE-STARTED is a value of the field ZSTATE of the extensible structured tokens ZTR3-MAP-STATUS-LINE and ZTR3-MAPSTATUS-SU. It indicates that a TR3271 line or subdevice is in the STARTED summary state.

5-16

COMMON DEFINITIONS

TR3271 Buffer Declarations

ZCOM-VAL-SUMSTATE-STOPPED is a value of the field ZSTATE of the extensible structured tokens ZTR3-MAP-STATUS-LINE and ZTR3-MAPSTATUS-SU. It indicates that a TR3271 line or subdevice is in the STOPPED summary state.

COMMON DEFINITIONS FOR THE TR3271 SUBSYSTEM

Definitions whose names begin with ZTR3- are TR3271 definitions. The definitions that appear in several commands or responses are described in this section. Information that is specific to particular commands or responses is discussed in Section 6, "Commands and Responses." Definitions are listed in alphabetical order within each category.

TR3271 Buffer Declarations

The TR3271 subsystem provides the following buffer declarations for message buffers that can be used with the SPI procedures. All applications should use one of these declarations for a buffer of the recommended size.

ZTR3-DDL-MSG-BUFFER is a message buffer whose size is that recommended for command messages and for responses in which each reply message contains a single response record.

def ZTR3-DDL-MSG-BUFFER.

02 Z-MSGCODE type ZSPI-TYP-INT. 02 Z-BUFLEN type ZSPI-TYP-UINT. 02 Z-OCCURS type ZSPI-DDL-UINT. 02 Z-FILLER type ZSPI-DDL-BYTE

occurs 0 to ZCOM-VAL-BUFLEN times depending on Z-OCCURS.

end.

5-17

COMMON DEFINITIONS TR3271 Predefined Token and Field Values

ZTR3-DDL-MSG-MAXBUF is a message buffer whose size is that recommended for responses in which each reply message contains multiple response records.

def ZTR3-DDL-MSG-MAX-BUF.

02 Z-MSGCODE type ZSPI-TYP-INT. 02 Z-BUFLEN type ZSPI-TYP-UINT. 02 Z-OCCURS type ZSPI-DDL-UINT. 02 Z-FILLER type ZSPI-DDL-BYTE

occurs 0 to ZCOM-VAL-MAXBUFLEN times depending on Z-OCCURS.

end.

TR3271 Predefined Token and Field Values

The TR3271 subsystem defines the following token and field values.

ZTR3-VAL-EVT-BUFLEN is the buffer size in bytes for event messages issued by the TR3271 subsystem.

ZTR3-VAL-SSID is the subsystem ID for the TR3271 subsystem. Its structure definition is given earlier in this section, under "SPI Standard Definitions."

For more information about ZTR3-VAL-SSID, refer to the discussion of the subsystem ID in the

Programming Manual

Distributed Systems Management (DSM)

ZTR3-VAL-VERSION is the version number of this version of the TR3271 subsystem. This value is a 16-bit unsigned integer; the left byte contains the letter part of the version as an ASCII uppercase alphabetic character, and the right byte contains the numeric part of the version as an unsigned integer value.

TR3271 Simple Tokens

The TR3271 subsystem only defines simple tokens that appear in event messages. These tokens include internal tokens, which appear in the ZTR3-EVT-INTERNAL-ERROR (74) event message. All the simple tokens defined by the TR3271 subsystem are listed below in the subsection "Tokens in Event Messages."

5-18

COMMON DEFINITIONS

TR3271 Tokens in Error Lists

TR3271 Extensible Structured Tokens

The extensible structured tokens defined by the TR3271 subsystem are as follows:

ZTR3-MAP-ADD-SU ZTR3-MAP-INFO-SU ZTR3-MAP-ALTER-LINE ZTR3-MAP-STATS-LINE ZTR3-MAP-ALTER-SU ZTR3-MAP-STATS-SU ZTR3-MAP-RSTATS-LINE ZTR3-MAP-STATUS-LINE ZTR3-MAP-RSTATS-SU ZTR3-MAP-STATUS-SU ZTR3-MAP-INFO-LINE

These tokens are described with the commands and responses they appear in. See Section 6, "Commands and Responses."

TR3271 Tokens in Error Lists

The TR3271 subsystem defines several error numbers. See Appendix A for detailed descriptions. The error numbers for TR3271 are as follows:

ZTR3-ERR-ALRDY-USING-ADDR ZTR3-ERR-ATTR-CONFL-SU ZTR3-ERR-CLIP-PROB ZTR3-ERR-CONN-EXIST ZTR3-ERR-NO-OBJ-IN-SEL-STATE ZTR3-ERR-NO-OWNER ZTR3-ERR-NOT-PTP-SU ZTR3-ERR-OPENED-SU-EXIST ZTR3-ERR-SU-OPENED ZTR3-ERR-TARGET-OBJ-NOT-FOUND ZTR3-ERR-TARGET-OBJNAME-INV

5-19

COMMON DEFINITIONS TR3271 Tokens in Event Messages

TR3271 Tokens in Event Messages

The TR3271 subsystem defines the following simple tokens in event messages. The internal tokens are indicated with an asterisk (*).

ZTR3-TKN-ABENDNUM ZTR3-TKN-FRAME-ERR ZTR3-TKN-ADDR-CTL ZTR3-TKN-P-REG* ZTR3-TKN-CIU-STATUS ZTR3-TKN-PROBE-ERR ZTR3-TKN-CLIP-FUNC ZTR3-TKN-SU ZTR3-TKN-CLIP-STATUS ZTR3-TKN-TYPE-SEQ ZTR3-TKN-CLIP-SU ZTR3-TKN-X1* ZTR3-TKN-CONFIG-ERR ZTR3-TKN-X2* ZTR3-TKN-E-REG* ZTR3-TKN-X3* ZTR3-TKN-FILE-ERR ZTR3-TKN-X4*

The tokens defined by the TR3271 subsystem that appear in event messages are described in Section 7, "Event Management," within the description of the event in which they appear.

5-20

SECTION 6

COMMANDS AND RESPONSES

This section describes each of the commands and responses in the programmatic command interface to the TR3271 subsystem. Each description includes the syntax, object types, command tokens, response tokens, operational notes, and error handling associated with the commands.

In this section, command numbers, object types, tokens, and token values are represented in DDL. For a quick explanation of DDL as it applies to SPI, refer to the appendix "Overview of DDL for SPI" in the

Distributed Systems Management (DSM) Programming

Manual

The commands available in the programmatic interface allow an application to do the following:

• Change the attributes of TR3271 objects

• Start and stop the operation of TR3271 objects

• Add a subdevice to or remove a subdevice from the TR3271

subsystem

• Obtain attribute values

• Obtain statistical and status information

• Obtain information about the object names known to the TR3271

subsystem

• Trace the activity of a TR3271 line

• Change the system resources used by a TR3271 process or line

6-1

COMMANDS AND RESPONSES

• Establish or break a link between a TR3271 subdevice and an

AM3270 subdevice

• Initiate a download of a Communications Line Interface

Processor (CLIP)

• Obtain the version of the TR3271 subsystem

Table 6-1 lists the commands that are available in the programmatic control-and-inquiry interface to the TR3271 subsystem and gives their symbolic names.

Table 6-1. Commands and Their Symbolic Names (Page 1 of 3)

SYMBOLIC NAME OF

COMMAND COMMAND AND OBJECT

ABORT ZCOM-CMD-ABORT ZCOM-OBJ-LINE

ZCOM-OBJ-SU

ADD ZCOM-CMD-ADD ZCOM-OBJ-SU

ALTER ZCOM-CMD-ALTER ZCOM-OBJ-LINE

ZCOM-OBJ-SU

CONNECT ZCOM-CMD-CONNECT ZCOM-OBJ-SU

DELETE ZCOM-CMD-DELETE ZCOM-OBJ-LINE*

ZCOM-OBJ-SU

DISCONNECT ZCOM-CMD-DISCONNECT ZCOM-OBJ-SU

GETVERSION ZCOM-CMD-GETVERSION ZCOM-OBJ-NULL

ZCOM-OBJ-PROC

6-2

COMMANDS AND RESPONSES

Table 6-1. Commands and Their Symbolic Names (Page 2 of 3)

SYMBOLIC NAME OF

COMMAND COMMAND AND OBJECT

INFO ZCOM-CMD-INFO ZCOM-OBJ-LINE

ZCOM-OBJ-SU

LISTOBJECTS ZCOM-CMD-LISTOBJECTS ZCOM-OBJ-LINE

ZCOM-OBJ-NULL ZCOM-OBJ-SU

LOAD ZCOM-CMD-LOAD ZCOM-OBJ-LINE

RESET ZCOM-CMD-RESET ZCOM-OBJ-LINE

RESETSTATS ZCOM-CMD-RESETSTATS ZCOM-OBJ-LINE

ZCOM-OBJ-SU

START ZCOM-CMD-START ZCOM-OBJ-LINE

ZCOM-OBJ-SU

STATISTICS ZCOM-CMD-STATISTICS ZCOM-OBJ-LINE

ZCOM-OBJ-SU

STATUS ZCOM-CMD-STATUS ZCOM-OBJ-LINE

ZCOM-OBJ-SU

6-3

COMMANDS AND RESPONSES Commands by Object Type

Table 6-1. Commands and Their Symbolic Names (Page 3 of 3)

SYMBOLIC NAME OF

COMMAND COMMAND AND OBJECT

STOP ZCOM-CMD-STOP ZCOM-OBJ-LINE

ZCOM-OBJ-SU

SWITCH ZCOM-CMD-SWITCH ZCOM-OBJ-LINE

ZCOM-OBJ-PROC

TRACE ZCOM-CMD-TRACE ZCOM-OBJ-LINE

* The LINE object can be specified, but it must be specified

with the subordinate modifier.

COMMANDS BY OBJECT TYPE

The TR3271 subsystem recognizes four object types in commands. One or more object types are valid for each command. Three of the object types have a hierarchical relationship. For TR3271 subsystems these three object types are PROC, LINE, and SU (subdevice), where SU is subordinate to LINE and LINE is subordinate to PROC. This subordinate arrangement means that the subordinate objects can, in some instances, be controlled or monitored by specifying the subordinate modifier.

NOTE

A process controls one line, but a line can control multiple subdevices.

The fourth object type recognized by the subsystem is the NULL object type. The NULL object type is not included in the objecttype hierarchy and is specified only when an object type is unnecessary, such as in the GETVERSION command.

6-4

COMMANDS AND RESPONSES

Commands by Object Type

The TR3271 subsystem accepts the PROC object type only in the following commands:

GETVERSION SWITCH

The TR3271 subsystem accepts the LINE object type only in the following commands:

ABORT RESETSTATS ALTER START DELETE STATISTICS INFO STATUS LISTOBJECTS STOP LOAD SWITCH RESET TRACE

The TR3271 subsystem accepts the SU object type only in the following commands:

ABORT LISTOBJECTS ADD RESETSTATS ALTER START CONNECT STATISTICS DELETE STATUS DISCONNECT STOP INFO

The TR3271 subsystem accepts the NULL object type only in the following commands:

GETVERSION LISTOBJECTS

6-5

COMMANDS AND RESPONSES Sensitive and Nonsensitive Commands

SENSITIVE AND NONSENSITIVE COMMANDS

Commands can be divided into two categories: sensitive and nonsensitive. Sensitive commands can change the state of the specified object; nonsensitive commands cannot change the state of the specified object. Because sensitive commands change the state of the specified object, sensitive commands can be issued only by users in the SUPER user group or users in the same group as the owner of the process with which the target object is associated. Nonsensitive commands can be issued by any valid user.

The sensitive commands available to a TR3271 subsystem user are as follows:

ABORT RESET ADD RESETSTATS ALTER START CONNECT STOP DELETE SWITCH DISCONNECT TRACE LOAD

The nonsensitive commands available to a TR3271 subsystem user are as follows:

GETVERSION STATISTICS INFO STATUS LISTOBJECTS

COMMAND DESCRIPTIONS

On the following pages, each command and its response is described in detail. The command descriptions appear in alphabetical order.

Within each command description, there is a box that contains the symbolic name of the command number, the symbolic names of all object types accepted by the command, a list of tokens that can be present in the command buffer, and a list of tokens that can be present in the response buffer.

6-6

COMMANDS AND RESPONSES

Command Descriptions

With the exception of the tokens ZSPI-TKN-DATALIST, ZSPI-TKNERRLIST, and ZSPI-TKN-ENDLIST, the order of the tokens in the lists of tokens in the command buffer and response buffer is not necessarily the order in which they will actually appear in a command or response.

• The token ZSPI-TKN-DATALIST, if present in a response, always

appears at the beginning of a response record.

• The token ZSPI-TKN-ERRLIST, if present in a response, always

appears at the beginning of an error list

• The token ZSPI-TKN-ENDLIST always appears at the end of a

response record started by the token ZSPI-TKN-DATALIST or of an error list started by the token ZSPI-TKN-ERRLIST.

The list of tokens in the response buffer, except for the context token ZSPI-TKN-CONTEXT, represents the tokens that can be present in one reply message that consists of a single response record or multiple response records. For more information on such responses, and for information on the context token, refer to the

Distributed Systems Management (DSM) Programming Manual

The notation used in the box for simple tokens is a shorthand version of the essential information given in the DDL TOKEN-CODE statement. Extensible structured tokens are defined by using DDL DEF statements.

For each token in the command and response buffers, and for each field of an extensible structured token in the command and response buffers, the box contains an indication of whether or not the token or field must be present in the command and of other dependencies. See "Notation Conventions" at the beginning of this manual for a description of the notation scheme used.

Error lists are indicated in the box by following the token ZSPI-TKN-ERRLIST by an ellipsis (...) and the ZSPI-TKN-ENDLIST. The tokens following the ZSPI-TKN-DATALIST, including the token ZSPI-TKN-ERRLIST, are indented to show that they are contained within the data list. The value of the token ZSPI-TKN-MAXRESP determines whether data lists are used in a response. For more information on data lists and error lists, refer to the

Distributed Systems Management (DSM) Programming Manual

Following the box, the tokens in the command buffer and the tokens in the response buffer are described in the same order as they appear in the box.

6-7

COMMANDS AND RESPONSES ABORT Command

ABORT Command

The ABORT command terminates the operation of the specified object and clears any existing connection to the object. When the subsystem finishes processing the command, the specified object is placed in the STOPPED summary state. You can abort a line or a subdevice, but not a process.

When you use the ABORT command, note that the termination is done without regard to processing currently in progress for the specified object. All activities being performed by the object are halted, and files and listings might be left in an inconsistent or incomplete state. If you issue this command while the line is in the DIAG summary state, the TR3271 subsystem returns an error.

When your management application issues the ABORT command for a line, the subsystem checks for the optional subordinate-modifier token.

• If the value of the modifier is ZCOM-VAL-SUB-ONLY, only the

subdevices attached to the specified line are aborted.

• If the value of the modifier is ZCOM-VAL-SUB-ALL, the subsys-

tem aborts all the associated subdevices and then aborts the line.

• If the value is ZCOM-VAL-SUB-NONE, or if the subordinate

modifier is not present, the subsystem checks the state of the subordinate subdevices. The subordinate subdevices must be in the STOPPED summary state. If any of the subdevices are in the STARTED summary state, the TR3271 subsystem rejects the command and returns an error.

When your management application issues the ABORT command for a subdevice, the subsystem aborts only the specified subdevice. The SU object has no subordinates. However, your management application can specify the subordinate modifier with the value ZCOM-VAL-SUB-NONE. This value causes the subsystem to abort only the specified subdevice. If your management application specifies the ZCOM-VAL-SUB-ONLY or ZCOM-VAL-SUB-ALL value, the TR3271 subsystem returns an error.

If your management application needs to abort a pass-through protocol (PTP) subdevice, it is recommended that you disconnect the subdevice first to avoid losing data.

6-8

COMMANDS AND RESPONSES

ABORT Command

Command

ZCOM-CMD-ABORT

Object Type

ZCOM-OBJ-LINE

ZCOM-OBJ-SU

Tokens in Command Buffer

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-MAP-REQID !MAP is optional, but if present,

!fields are required.

def ZCOM-DDL-REQID.

02 ZCRTPID type ZSPI-DDL-CRTPID. 02 ZPAID type ZSPI-DDL-INT.

end.

ZCOM-TKN-CMD-TIMEOUT token-type ZSPI-TYP-TIMESTAMP. ZCOM-TKN-SUB token-type ZSPI-TYP-ENUM.

ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{} ZSPI-TKN-MAXRESP token-type ZSPI-TYP-INT. ZSPI-TKN-CONTEXT token-type ZSPI-TYP-BYTESTRING. ZSPI-TKN-RESPONSE-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-ALLOW-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-COMMENT token-type ZSPI-TYP-STRING.

Tokens in Response Buffer

ZSPI-TKN-SERVER-VERSION token-type ZSPI-TYPE-INT. !{} ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{} ZSPI-TKN-DATALIST token-type ZSPI-TYP-LIST. !...

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-TKN-OBJTYPE token-type ZSPI-TYP-ENUM. !{} ZSPI-TKN-ERRLIST token-type ZSPI-TYP-LIST. !... ... ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL.

ZSPI-TKN-RETCODE token-type ZSPI-TYP-ENUM. !{} ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL. ZSPI-TKN-CONTEXT token-type ZSPI-TYP-BYTESTRING.

6-9

COMMANDS AND RESPONSES ABORT Command

Tokens in Command Buffer

ZCOM-TKN-OBJNAME specifies the name of a TR3271 line or subdevice that is to be terminated. Your application must provide this token in the command. This token is described in "DataCommunications Standard Definitions" in Section 5 and the

Communications Management Programming Manual

ZCOM-MAP-REQID and ZCOM-TKN-CMD-TIMEOUT are standard datacommunications tokens that your application can optionally provide. These tokens are described in "Data-Communications Standard Definitions" in Section 5 and the

Management Programming Manual

Communications

ZCOM-TKN-SUB specifies whether subordinates are to be affected by the ABORT command. For the ABORT command, the possible values of this token are as follows:

ZCOM-VAL-SUB-ALL If the object type is LINE, terminate the

named line and all its subordinate subdevices. If the object type is SU, terminate the named subdevice.

ZCOM-VAL-SUB-ONLY If the object type is LINE, terminate the

subdevices subordinate to the named line, but do not terminate the line. This value is not valid with the SU object type.

ZCOM-VAL-SUB-NONE If the object type is LINE, terminate the

named line only if the subordinate subdevices are currently in the STOPPED summary state. If the object type is SU, terminate the named subdevice.

If the subordinate modifier is not present, the subsystem treats the command as if the ZCOM-VAL-SUB-NONE value has been used. This token is also described in "Data-Communications Standard Definitions" in Section 5 and the

Programming Manual

Communications Management

(ZSPI-TKN-) MANAGER, SSID, MAXRESP, CONTEXT, RESPONSE-TYPE, ALLOW-TYPE, and COMMENT are standard SPI tokens. With the exception of the ZSPI-TKN-SSID token, which your management application must pass to SSINIT, these tokens are optional. These tokens are described in "SPI Standard Definitions" in Section 5 and the

Programming Manual

Distributed Systems Management (DSM)

6-10

COMMANDS AND RESPONSES

ABORT Command

Tokens in Response Buffer

ZSPI-TKN-DATALIST indicates the beginning of a data list. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

ZCOM-TKN-OBJNAME specifies the name of a TR3271 line or subdevice that was terminated by the command. Unless there is an error that prevents the ABORT command from being attempted at all, this token is present in every response record. ZCOM-TKN-OBJNAME is described in "Data-Communications Standard Definitions" in Section 5 and in the

Manual

Communications Management Programming

ZCOM-TKN-OBJTYPE specifies the type of object that was terminated. This token can have the value ZCOM-OBJ-LINE or ZCOMOBJ-SU. This token is described in "Data-Communications Standard Definitions" in Section 5 and the

Programming Manual

Communications Management

ZSPI-TKN-ERRLIST indicates the beginning of an error list. Within the error list, the object experiencing the error is listed. See "SPI Standard Definitions" in Section 5 for details.

ZSPI-TKN-RETCODE specifies the return code for the command. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

. For details on the data-communications error numbers and their associated error lists, see "Common Error Numbers and Error Lists" in the

Communications Management Programming Manual

The possible nonzero values of RETCODE in response to the ABORT command are as follows:

ZCOM-ERR-EMPT-RSP (-33) ZCOM-ERR-TKN-REQ (-29) ZCOM-ERR-TKN-DUP (-27) ZCOM-ERR-TKN-CODE-INV (-26) ZCOM-ERR-SUB-NOT-FOUND (-25) ZCOM-ERR-SSID-INV (-24) ZCOM-ERR-SECUR-VIOL (-22) ZCOM-ERR-OBJNAME-INV (-19) ZCOM-ERR-OBJ-NOT-SUPP (-18) ZCOM-ERR-OBJ-NOT-FOUND (-17) ZCOM-ERR-OBJ-ALRDY-IN-SUMSTATE (-16) ZCOM-ERR-FNAME-INV (-9) ZCOM-ERR-CMD-TIMED-OUT (-7) ZCOM-ERR-CMD-MISMATCH (-4) ZCOM-ERR-CMD-INV-IN-SUMSTATE (-3)

6-11

COMMANDS AND RESPONSES ABORT Command

ZCOM-ERR-TKN-VAL-INV (-30)

Your management application specified the SU object and the the SUB modifier with a value ZCOM-VAL-SUB-ONLY. The SU object accepts only the value ZCOM-VAL-SUB-NONE or ZCOM-VALSUB-ALL for the SUB modifier.

ZSPI-TKN-ENDLIST indicates the end of a data list or an error list. See "SPI Standard Definitions" in Section 5 for details.

ZSPI-TKN-CONTEXT specifies whether there are more reply messages to be received for a response. If this token is present, the response continues to the next reply message. If this token is not present, the reply message is the last to be received. See "SPI Standard Definitions" in Section 5 for details.

Operational Notes

• ABORT is a sensitive command.

• When the command is completed, the line and subdevices are

placed in the STOPPED summary state.

• The line must be in the STARTED summary state when this

command is issued.

• If you abort a pass-through protocol (PTP) SU, the SU is

disconnected from the AM3270 subdevice on the other end.

• For more controlled termination of lines and subdevices, use

the STOP command.

• To initiate the operation of lines and subdevices, use the

START command.

• Use the STATUS command to determine the summary states of the

objects.

6-12

COMMANDS AND RESPONSES

ADD Command

The ADD command adds a subdevice to the TR3271 subsystem. You can add only a subdevice; this command is not valid for the PROC or LINE object type. The line must be in the STARTED or STOPPED summary state when you attempt to add a subdevice. If the line is not in one of these summary states, the TR3271 subsystem returns an error. When the subsystem finishes processing the command (without errors), the subdevice is placed in the STOPPED summary state. To start the added subdevice, use the START command.

When your management application issues the ADD command for a subdevice, the subsystem checks the configurable attributes provided in the command. These attributes are defined in ZTR3-MAP-ADD-SU. If the attributes are valid, the subsystem verifies that the subdevice is not already defined and that the number of subdevices defined on the line is not greater than 253. If either of these checks fails, the subsystem returns an error.

Typically, a line can support 255 subdevices, but there are two subdevices reserved with the names #ZSPI and #DEBUG.

Command

ZCOM-CMD-ADD

Object Type

ZCOM-OBJ-SU

Tokens in Command Buffer

ZTR3-MAP-ADD-SU !{}

def ZTR3-DDL-ADD-SU.

02 ZADDR type ZSPI-DDL-INT-PAIR. !{} 02 ZPROTO type ZSPI-DDL-ENUM. !{} 02 ZRECSIZE type ZSPI-DDL-INT. !{} 02 ZXPARENT type ZSPI-DDL-BOOLEAN. 02 ZTYPE type ZSPI-DDL-INT-PAIR !{}

end. ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-MAP-REQID !MAP is optional, but if present,

!fields are required.

6-13

COMMANDS AND RESPONSES ADD Command

def ZCOM-DDL-REQID.

02 ZCRTPID type ZSPI-DDL-CRTPID. 02 ZPAID type ZSPI-DDL-INT.

end. ZCOM-TKN-CMD-TIMEOUT token-type ZSPI-TYP-TIMESTAMP.

ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{} ZSPI-TKN-MAXRESP token-type ZSPI-TYP-INT. ZSPI-TKN-RESPONSE-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-ALLOW-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-COMMENT token-type ZSPI-TYP-STRING.

Tokens in Response Buffer

ZSPI-TKN-SERVER-VERSION token-type ZSPI-TYP-INT. !{} ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{} ZSPI-TKN-DATALIST token-type ZSPI-TYP-LIST.

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{}

ZCOM-TKN-OBJTYPE token-type ZSPI-TYP-ENUM. !{}

ZSPI-TKN-ERRLIST token-type ZSPI-TYP-LIST. !...

...

ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL.

ZSPI-TKN-RETCODE token-type ZSPI-TYP-ENUM. !{} ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL.

Tokens in Command Buffer

ZTR3-MAP-ADD-SU is the extensible structured token that defines the configurable attributes for the subdevice that is to be added. It has the token number ZTR3-TNM-ADD-SU and the DDL definition ZTR3-DDL-ADD-SU. This token must be in the command, and duplicate occurrences are not allowed.

Each attribute is defined in a separate field. An optional field can use the default value provided by SSNULL, but your management application must assign values to the required fields. The only optional field is ZXPARENT. The fields in the ZTR3-MAP-ADD-SU token are as follows:

ZADDR is a pair of integers that specifies the address to be assigned to the subdevice. The first integer is the controller address. The second integer is the subdevice address. Both integers should be in the range 0 through 31. This is a required field.

6-14

COMMANDS AND RESPONSES

ADD Command

ZPROTO specifies the protocol to be used by the subdevice. This required field must be assigned one of the following values:

ZTR3-VAL-PROTO-CRT The CRT protocol will be used. ZTR3-VAL-PROTO-PTP The pass-through protocol (PTP) will be

used

Refer to the

Device-Specific Access Methods--AM3270/TR3271

manual for more information about these protocols. ZRECSIZE specifies the maximum number of bytes the subdevice

can send or receive in a record. This is a required field. The recommended record size depends on the protocol used and the type of subdevice as follows:

CRT terminal Use the defined screen size as the record

size. The record size is used for reference only.

PTP subdevice The TR3271 I/O process allocates the

buffer based on the value of this field. Use the defined screen size as follows:

Screen Size Record Size

480 512

960 1024 1920 2048 2560 3072 3440 4096 3564 4096

ZXPARENT is a Boolean value that controls transparent-text mode for the named subdevice. If the value is ZSPI-VAL-TRUE, transparent-text mode is enabled for the subdevice; if the value is ZSPI-VAL-FALSE, it is not. The default is ZSPIVAL-FALSE. Transparent-text mode can only be enabled if the TR3271 line is configured with the EBCDIC character set and transparent-text mode enabled.

When using pass-through mode, the TR3271 subdevice should have the same record size as the AM3270 subdevice that is on the other end of the connection.

6-15

COMMANDS AND RESPONSES ADD Command

ZTYPE is a pair of integers that specifies the device type and subtype of the subdevice to be added. The first integer is the device type, which depends on the protocol being used. The second integer is the subtype, which depends on the terminal being represented. The possible integer pairs are as follows:

(10,x) The subdevice uses the CRT protocol. The

value of x is an integer in the 1 through 5 range and is associated with the following screen sizes.

ZTYPE screen size (10,1) 12 x 40

(10,2) 24 x 80 (10,3) 32 x 80 (10,4) 43 x 80 (10,5) 12 x 80

(60,x) The subdevice is a pass-through protocol (PTP)

subdevice. The value of x can have the value of 1 or 2. Subtype 1 indicates a CRT subdevice, and subtype 2 indicates a printer.

ZCOM-TKN-OBJNAME specifies the subdevice that is to be added. Your application must provide this token in the command. This token is described in "Data-Communications Standard Definitions" in Section 5, "Common Definitions," and the

Management Programming Manual

Communications

Management Programming Manual

Communications

(ZSPI-TKN-) MANAGER, SSID, MAXRESP, RESPONSE-TYPE, ALLOW-TYPE, and COMMENT are standard SPI tokens. With the exception of the ZSPI-TKN-SSID token, which your management application must pass to SSINIT, these tokens are optional. These tokens are described in "SPI Standard Definitions" in Section 5 and the

Systems Management (DSM) Programming Manual

Distributed

6-16

COMMANDS AND RESPONSES

ADD Command

Tokens in Response Buffer

ZSPI-TKN-DATALIST indicates the beginning of a data list. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

ZCOM-TKN-OBJNAME specifies the name of the TR3271 subdevice that was added to the subsystem by the command. Unless there is an error that prevents the ADD command from being attempted at all, this token is present in every response record. ZCOM-TKN-OBJNAME is described in "Data-Communications Standard Definitions" in Section 5 and the

Communications Management Programming Manual

ZCOM-TKN-OBJTYPE specifies the type of object that was added. You can add only a subdevice; therefore, the value of this token must be ZCOM-OBJ-SU. This token is described in Section 5, "Common Definitions," and the

Programming Manual

Communications Management

ZSPI-TKN-ERRLIST indicates the beginning of an error list. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

ZSPI-TKN-RETCODE specifies the return code for the command. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management Programming Manual

. For details on the data-communications error numbers and their associated error lists, see "Common Error Numbers and Error Lists" in the

Communications Management Programming Manual

. For details on the TR3271 error numbers and associated error lists, see Appendix A in this manual.

The possible nonzero values of RETCODE in response to the ADD command are as follows:

ZCOM-ERR-EMPT-RSP (-33) ZCOM-ERR-VAL-REQ (-31) ZCOM-ERR-TKN-VAL-INV (-30) ZCOM-ERR-TKN-REQ (-29) ZCOM-ERR-TKN-LEN-INV (-28) ZCOM-ERR-TKN-DUP (-27) ZCOM-ERR-TKN-CODE-INV (-26) ZCOM-ERR-SSID-INV (-24) ZCOM-ERR-SECUR-VIOL (-22) ZCOM-ERR-OBJNAME-INV (-19) ZCOM-ERR-OBJ-NOT-SUPP (-18) ZCOM-ERR-OBJ-ALRDY-DEF (-15) ZCOM-ERR-NO-MEM-SPACE (-14) ZCOM-ERR-FNAME-INV (-9) ZCOM-ERR-CMD-TIMED-OUT (-7)

6-17

COMMANDS AND RESPONSES ADD Command

ZCOM-ERR-MAX-LIMIT-EXCEEDED (-12)

Your management application attempted to add more than 253 subdevices on a single line. Typically, you can define as many as 255 subdevices; however, two subdevices are reserved: #ZSPI and #DEBUG.

ZCOM-ERR-CMD-MISMATCH (-4)

Your management application tried to add a process or a line by using the object type ZCOM-OBJ-PROC or ZCOM-OBJ-LINE. The command is valid only for the object type ZCOM-OBJ-SU.

ZCOM-ERR-CMD-INV-IN-SUMSTATE (-3)

Your management application tried to add a subdevice while the line was in the DIAGNOSING summary state. The line must be in the STOPPED or STARTED summary state to process the ADD command.

ZTR3-ERR-ALRDY-USING-ADDR (6)

Your management application attempted to add a subdevice at an address already in use by another object. Reissue the command using a value for the ZADDR field that has not been previously assigned.

ZTR3-ERR-CLIP-PROB (2)

Your management application attempted to add a subdevice but the operation failed because of an internal CLIP problem. Check event messages 165 and 164 for CLIP information and contact your Tandem representative.

ZSPI-TKN-ENDLIST indicates the end of a data list or an error list. This token is described in "SPI Standard Definitions" in Section 5 and the

Programming Manual

Distributed Systems Management (DSM)

Operational Notes

• ADD is a sensitive command.

• When the command is successfully completed, the subdevice is

placed in the STOPPED summary state.

• The line must not be in the DIAG summary state when this

command is issued.

6-18

COMMANDS AND RESPONSES

ADD Command

• The name given to a subdevice must be unique on the line.

• You can add a maximum of 253 subdevices to a line.

• To remove a subdevice, stop the SU, then use the DELETE

command.

• To add a line or a process, use the Dynamic System

Configuration (DSC) facility.

6-19

COMMANDS AND RESPONSES ALTER Command

ALTER Command

The ALTER command changes attribute values associated with the specified object. You can change attributes for a line and a subdevice, but not a process.

Command

ZCOM-CMD-ALTER

Object Type

ZCOM-OBJ-LINE

ZCOM-OBJ-SU

Tokens in Command Buffer

ZTR3-MAP-ALTER-LINE !{A}

!OBJ-LINE

def ZTR3-DDL-ALTER-LINE. !Specify one or more fields.

02 ZBCCTYPE type ZSPI-DDL-ENUM. 02 ZCHARSET type ZSPI-DDL-ENUM.

!ZCTL-SET

!ZXLATE 02 ZCTL-RTS type ZSPI-DDL-BOOLEAN. 02 ZCTL-SET type ZSPI-DDL-ENUM. 02 ZDEBUG type ZSPI-DDL-BOOLEAN. 02 ZDROP-RTS type ZSPI-DDL-BOOLEAN. 02 ZINIT-STATUS type ZSPI-DDL-INT2. 02 ZMULTI-BLOCK type ZSPI-DDL-BOOLEAN. 02 ZOFFLINE-TIMER type ZSPI-DDL-TIMESTAMP. 02 ZPROG type ZSPI-DDL-FNAME. 02 ZREAD-CMD type ZSPI-DDL-ENUM. 02 ZRETRY type ZSPI-DDL-INT. 02 ZSYNCS type ZSPI-DDL-INT. 02 ZTEST-INTVL type ZSPI-DDL-TIMESTAMP. 02 ZTHRES type ZSPI-DDL-INT. 02 ZTIMEOUT type ZSPI-DDL-TIMESTAMP. 02 ZXLATE type ZSPI-DDL-BOOLEAN. 02 ZXPARENT type ZSPI-DDL-BOOLEAN. 02 ZWACK-DELAY type ZSPI-DDL-TIMESTAMP. 02 ZXLATE-IN type ZSPI-DDL-CHAR

occurs 256 times.

02 ZXLATE-OUT type ZSPI-DDL-CHAR

occurs 256 times.

end.

6-20

COMMANDS AND RESPONSES

ALTER Command

ZTR3-MAP-ALTER-SU !{A}

!OBJ-SU

def ZTR3-DDL-ALTER-SU. !Specify one or more fields.

02 ZADDR type ZSPI-DDL-INT-PAIR. 02 ZPROTO type ZSPI-DDL-ENUM. 02 ZRECSIZE type ZSPI-DDL-INT. 02 ZXPARENT type ZSPI-DDL-BOOLEAN. 02 ZTYPE type ZSPI-DDL-INT-PAIR.

end.

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-MAP-REQID !MAP is optional, but if present,

!fields are required.

def ZCOM-DDL-REQID.

02 ZCRTPID type ZSPI-DDL-CRTPID. 02 ZPAID type ZSPI-DDL-INT.

end.

ZCOM-TKN-CMD-TIMEOUT token-type ZSPI-TYP-TIMESTAMP. ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{}

ZSPI-TKN-MAXRESP token-type ZSPI-TYP-INT. ZSPI-TKN-RESPONSE-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-ALLOW-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-COMMENT token-type ZSPI-TYP-STRING.

Tokens in Response Buffer

ZSPI-TKN-SERVER-VERSION token-type ZSPI-TYP-INT. !{} ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{}

ZSPI-TKN-DATALIST token-type ZSPI-TYP-LIST.

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-TKN-OBJTYPE token-type ZSPI-TYP-ENUM. !{} ZSPI-TKN-ERRLIST token-type ZSPI-TYP-LIST. !... ... ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL. ZSPI-TKN-RETCODE token-type ZSPI-TYP-ENUM. !{}

ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL.

6-21

COMMANDS AND RESPONSES ALTER Command

Tokens in Command Buffer

ZTR3-MAP-ALTER-LINE is the extensible structured token that defines the configurable attributes that are to be altered for the line. It has the token number ZTR3-TNM-ALTER-LINE and the DDL definition ZTR3-DDL-ALTER-LINE. This token must be in the command when the specified object is ZCOM-OBJ-LINE. It cannot be in the command when the object is ZCOM-OBJ-SU. Duplicate occurrences of this token are not allowed.

Each attribute is defined in a separate field. At least one field must be specified. The fields in the ZTR3-MAP-ALTER-LINE extensible structured token are as follows:

ZBCCTYPE The block check character (BCC) type to be

used by the line. The value ZTR3-VAL-BCC-LRC8 indicates that the longitudinal redundancy check (LRC8) will be used. The value ZTR3-VAL-BCCCRC16 indicates that the cyclic redundancy check (CRC16) will be used. The value ZTR3-VAL-BCCCCITT indicates that the International Telegraph and Telephone Consultative Committee check will be used. The default value is ZTR3-VAL-BCCCRC16.

ZCHARSET The character set to be used. The value

ZTR3-VAL-CHAR-ASCII indicates the ASCII character set will be used. The value ZTR3-VAL-CHAR-EBCDIC indicates the EBCDIC character set will be used. The default value is ZTR3-VAL-CHAR-EBCDIC.

ZCTL-RTS A Boolean variable that specifies whether the

Carrier Detect (CD) signal is dropped before the Request To Send (RTS) signal is raised. If the value is ZSPI-VAL-TRUE, CD is dropped before RTS is raised. If the value is ZSPI-VAL-FALSE, CD is not dropped before RTS is raised. The default value is ZSPI-VAL-FALSE.

ZCTL-SET An enumerated value that specifies the bisyn-

chronous control set. The value ZTR3-VAL-CTLSET-ASCII indicates that the ASCII control set will be used. The value ZTR3-VAL-CTL-SET-EBCDIC indicates that the EBCDIC control set will be used. The default value is ZTR3-VAL-CTL-SETEBCDIC.

ZDEBUG A Boolean variable that enables the CLIP DEBUG

interface. If the value is ZSPI-VAL-TRUE, the interface is enabled. If the value is ZSPI-VALFALSE, the interface is not enabled. The default value is ZSPI-VAL-FALSE.

6-22

COMMANDS AND RESPONSES

ALTER Command

ZDROP-RTS A Boolean variable that specifies whether the

Request To Send (RTS) signal is dropped when the software switches from a write operation to a read operation. If the value is ZSPI-VALTRUE, the signal will be dropped when switching operations. If the value is ZSPI-VAL-FALSE, the RTS signal will not be dropped. The default value is ZSPI-VAL-FALSE.

ZINIT-STATUS A 32-bit integer that specifies the initial IBM

status that the TR3271 subsystem returns when it receives a SELECT for a subdevice that has not been OPENed or CONNECTed. The possible values are as follows:

0 The TR3271 subsystem responds with

a Wait for acknowledgement (WACK) indicating that the subdevice is busy. The subdevice remains busy until an application OPENs or CONNECTs the subdevice. Note that this can have a cyclic effect; the host front-end might resend a SELECT each time it receives a WACK from the TR3271 subsystem.

%177776 The TR3271 subsystem does not

respond to SELECTs. Consequently, the host times out the subdevice provided the subdevice has not been OPENed or CONNECTed before the timeout period elapses.

%177777 The TR3271 subsystem responds with

an ACK0 and acknowledges data from the host. Although acknowledged, the data is discarded because it was unsolicited. An event message 112 is sent to the EMS log indicating that data has been discarded (see the description of event message 112 in Section 7, "Event Management"). Data from the host continues to be discarded until an application OPENs or CONNECTs the subdevice.

6-23

COMMANDS AND RESPONSES ALTER Command

%value If the value of this field is any

16-bit octal value other than 0, %177776, or %177777, the TR3271 subsystem responds with a RVI. The value in this field is interpreted as IBM Status/Sense information. The TR3271 subsystem will send these bytes to the host when the host, after receiving the RVI, polls the subsystem. The value must be in the correct format. Refer to Appendix C in the

Methods--AM3270/TR3271

Device-Specific Access

for a list

of appropriate values.

ZMULTI-BLOCK A Boolean variable that specifies whether the

TR3271 subsystem supports multiple block transmissions. If the value is ZSPI-VAL-TRUE, the subsystem supports multiple block transmissions; if the value is ZSPI-VAL-FALSE, it does not. The default is ZSPI-VAL-FALSE.

ZOFFLINE-TIMER A timestamp that specifies the period of time,

in .01 seconds, that the TR3271 subsystem waits to receive a signal from the host. If the TR3271 subsystem does not receive anything within this interval, the host is considered down and a timeout error is reported. The value must be in the 0 through 5:27:67 range. The default is 0, wait forever.

ZPROG A 32-byte file name that identifies the program

file that is to be downloaded to the CLIP. The default is $SYSTEM.CSS00.C9315P00.

ZREAD-CMD An enumerated value that specifies whether the

TR3271 subsystem accepts the Read Buffer and Read Modified command from the host. The value ZTR3-VAL-READ-NONE causes the subsystem to reject the Read Buffer and Read Modified commands. The value ZTR3-VAL-READ-ALL causes the subsystem to accept both the Read Buffer and Read Modified commands. ZTR3-VAL-READ-RDMOD causes the subsystem to accept the Read Modified command, but reject the Read Buffer command.

The Read Buffer command is supported only for CRT subdevices. If your management application specifies the ZTR3-VAL-READ-ALL for PTP subdevices, Read Buffer commands are rejected. This restriction is imposed by the protocol used by PTP subdevices. The default value for this field is ZTR3-VAL-READ-NONE.

6-24

COMMANDS AND RESPONSES

ALTER Command

ZRETRY An integer that specifies the number of times the

TR3271 retransmits data as a result of data link errors before returning an error. The value must be in the 1 through 14 range. The default is 3.

ZSYNCS An integer that specifies the number of SYN

characters that precede each frame. The value must be in the 1 through 14 range. The default is 3.

ZTEST-INTVL A timestamp that specifies the interval, in .01

seconds, at which the status probe is issued to the CLIP. The value must be in the range 0 through 5:27:67. If the value is 0, no status probe will be issued. The default is :10 (10 seconds).

ZTHRES An integer that specifies the statistics thresh-

old values. This value defines the number of frames to be transmitted and received before line quality is checked. The value must be in the 0 through 32767 range. If the value is 0, the threshold is ignored. The default is 0.

ZTIMEOUT A timestamp that specifies the line I/O timeout

value, in .01 seconds. This value defines how long the I/O process waits before retrying when a data link error occurs. The value must be in the range 00:00.6 through 00:10. The default is 00:02.7.

ZXLATE A Boolean variable that specifies whether the

TR3271 subsystem translates inbound and outbound data. If the value is ZSPI-VAL-TRUE, the TR3271 subsystem translates inbound data (from the line) from EBCDIC to ASCII, and translates outbound data (to the line) from ASCII to EBCDIC. If the value is ZSPI-VAL-FALSE, the TR3271 subsystem does not translate characters. The default is ZSPI-VAL-TRUE. The value of ZXLATE must be TRUE if ZXLATE-IN and ZXLATE-OUT, as well as ZCHAR-SET (value EBCDIC) and ZCTL-SET (value EBCDIC), are used.

ZXPARENT A Boolean variable that controls transparent-

text mode for the named line. If the value is ZSPI-VAL-TRUE, transparent-text mode is enabled for the line; if the value is ZSPI-VAL-FALSE, it is not. The default is ZSPI-VAL-FALSE. Transparent-text mode can only be enabled if the line is configured with the EBCDIC character set.

6-25

COMMANDS AND RESPONSES ALTER Command

ZWACK-DELAY A timestamp that specifies the period of time,

in .01 seconds, that the TR3271 subsystem waits before sending a wait for acknowledgement (WACK) to the host in response to a SELECT. The value must be in the 0 through 32767 range. The default is 0.

ZXLATE-IN A character value that must occur 256 times, once

for each ASCII character. The character values together make up the translation table used for inbound data. Note that the ZXLATE field must have the value ZSPI-VAL-TRUE for this translation table to be in effect.

ZXLATE-OUT A character value that must occur 256 times, once

for each ASCII character. The character values together make up the translation table used for outbound data. Note that the ZXLATE field must have the value ZSPI-VAL-TRUE for this translation table to be in effect.

ZTR3-MAP-ALTER-SU is the extensible structured token that defines the configurable attributes that are to be altered for a subdevice. It has the token number ZTR3-TNM-ALTER-SU and the DDL definition ZTR3-DDL-ALTER-SU. This extensible structured token must be in the command when the specified object is ZCOM-OBJ-SU. It cannot be in the command when the object is ZCOM-OBJ-LINE. Duplicate occurrences of the token are not allowed.

Each attribute is defined in a separate field. At least one field must be specified. The fields in the ZTR3-MAP-ALTER-SU token are as follows:

ZADDR A pair of integers that specifies the address to be

assigned to the subdevice. The first integer is the address of the control unit. The second integer is the address of the subdevice. Both integers should be in the range 0 through 31.

ZPROTO An enumerated value that specifies the protocol to be

used by the subdevice. There is no default value. You can assign one of the following values:

ZTR3-VAL-PROTO-CRT The CRT protocol will be

used.

ZTR3-VAL-PROTO-PTP The pass-through protocol

6-26

(PTP) will be used.

COMMANDS AND RESPONSES

ALTER Command

ZRECSIZE An integer that specifies the maximum number of bytes

the subdevice can send or receive in a record. The recommended record size depends on the protocol used and the type of subdevice as follows:

CRT terminal Use the defined screen size as

the record size.

PTP subdevice Use the defined screen size as

follows:

Screen Size Record Size

480 512

960 1024 1920 2048 2560 3072 3440 4096 3564 4096

ZXPARENT A Boolean variable that controls transparent-text mode

for the named subdevice. If the value is ZSPIVAL-TRUE, transparent-text mode is enabled for the subdevice; if the value is ZSPI-VAL-FALSE, it is not. The default is ZSPI-VAL-FALSE.

Transparent-text mode can only be enabled if the TR3271 line is configured with the EBCDIC character set and control set, and transparent-text mode is enabled for the line.

ZTYPE A pair of integers that specifies the device type

and subtype of the subdevice to be altered. The first integer is the device type, which depends on the protocol being used. The second integer is the subtype, which depends on the terminal being represented. The possible integer pairs are as follows:

(10,x) The subdevice uses the CRT protocol.

The value of x is an integer in the range 1 through 5 and is associated with the following screen sizes:

ZTYPE Screen Size (10,1) 12 x 40

(10,2) 24 x 80 (10,3) 32 x 80 (10,4) 43 x 80 (10,5) 12 x 80

6-27

COMMANDS AND RESPONSES ALTER Command

(60,x) The subdevice is a pass-through

protocol (PTP) subdevice. The value of x can have the value of 1 or 2. Subtype 1 indicates a CRT subdevice, and subtype 2 indicates a printer.

ZCOM-TKN-OBJNAME specifies the line or subdevice whose attribute values are to be altered. Your application must provide this token in the command. This token is described in "DataCommunications Standard Definitions" in Section 5, "Common Definitions," and the

Communications Management Programming

Manual

Management Programming Manual

Communications

Systems Management (DSM) Programming Manual

Distributed

Tokens in Response Buffer

ZSPI-TKN-DATALIST indicates the beginning of a data list. This token is described in "SPI Standard Definitions" in Section 5, "Common Definitions," and the

(DSM) Programming Manual

Distributed Systems Management

ZCOM-TKN-OBJNAME specifies the name of a TR3271 line or subdevice that was altered by the command. Unless there is an error that prevents the ALTER command from being attempted at all, this token is present in every response record. ZCOM-TKN-OBJNAME is described in "Data-Communications Standard Definitions" in Section 5 and the

Communications Management Programming Manual

ZCOM-TKN-OBJTYPE specifies the type of object that was altered. This token has the value ZCOM-OBJ-LINE or ZCOM-OBJ-SU. This token is described in Section 5, "Common Definitions," and the

Communications Management Programming Manual

ZSPI-TKN-ERRLIST indicates the beginning of an error list. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

6-28

COMMANDS AND RESPONSES

ALTER Command

ZSPI-TKN-RETCODE specifies the return code for the command. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

. For details on the data-communications error numbers and their associated error lists, see "Common Error Numbers and Error Lists" in the

Communications Management Programming Manual

. For details on the TR3271 error number and their associated error lists, see Appendix A in this manual.

The possible nonzero values of RETCODE in response to the ALTER command are as follows:

ZCOM-ERR-VAL-REQ (-31) ZCOM-ERR-TKN-VAL-INV (-30) ZCOM-ERR-TKN-LEN-INV (-28) ZCOM-ERR-TKN-DUP (-27) ZCOM-ERR-TKN-CODE-INV (-26) ZCOM-ERR-SSID-INV (-24) ZCOM-ERR-SECUR-VIOL (-22) ZCOM-ERR-OBJNAME-INV (-19) ZCOM-ERR-OBJ-NOT-FOUND (-17) ZCOM-ERR-FNAME-INV (-9) ZCOM-ERR-CMD-TIMED-OUT (-7)

ZCOM-ERR-OBJ-NOT-SUPP (-18)

Your management application has tried to alter an object that is not supported by the TR3271 subsystem. The supported objects are PROC, LINE and SU. For the ALTER command, you must specify the value ZCOM-OBJ-LINE or ZCOM-OBJ-SU.

ZCOM-ERR-NO-MEM-SPACE (-14)

The subsystem cannot alter the subdevice at this time because the necessary memory for the line or subdevice control block cannot be allocated.

ZCOM-ERR-CMD-MISMATCH (-4)

Your management application tried to alter a process by using the value ZCOM-OBJ-PROC. The command is valid only for the value ZCOM-OBJ-LINE or ZCOM-OBJ-SU.

ZCOM-ERR-CMD-INV-IN-SUMSTATE (-3)

Your management application tried to alter a line or subdevice while the line was in the DIAG summary state. This summary state prevents processing of the ALTER command.

6-29

COMMANDS AND RESPONSES ALTER Command

ZTR3-ERR-ALRDY-USING-ADDR (6)

Your management application attempted to alter the address of a subdevice, but the address specified in ZADDR is already in use by another subdevice. The ZADDR field must have a value not previously assigned.

ZTR3-ERR-ATTR-CONFL-SU (4)

An SU attribute conflicts with a LINE attribute. The ZXPARENT field for an SU is defined as ZSPI-VAL-TRUE, but the LINE attributes defined by the ZCHARSET, ZCTL-SET, ZXLATE, and ZXPARENT fields are not properly specified.

ZSPI-TKN-ENDLIST indicates the end of a data list or an error list. This token is described in "SPI Standard Definitions" in Section 5 and the

Programming Manual

Distributed Systems Management (DSM)

Operational Notes

• ALTER is a sensitive command.

• When the command is completed, the line and subdevice remain

in the same state as they were before the command was executed.

• The LINE and SU objects must be in the STOPPED summary state

before their attributes can be altered, except when changing the DEBUG attribute in the token ZTR3-MAP-ALTER-LINE.

• To obtain attributes values of a line or subdevice, use the

INFO command.

6-30

COMMANDS AND RESPONSES

CONNECT Command

The CONNECT command creates a link between a TR3271 subdevice and a TR3271 subdevice. Only subdevices can be connected. Once this command is successfully completed, data can pass between TR3271 terminals and an IBM host through the TR3271 subsystem.

When you use the CONNECT command, the subsystem checks that both the TR3271 subdevice and the target AM3270 subdevice are in the STARTED summary state. In addition, they must both be defined as PTP subdevices. If the TR3271 subdevice is not already defined as a PTP subdevice, you can redefine it using either the ZPROTO field in the ALTER command described in this manual, or the ALTER command described in the

Reference Manual

. If the AM3270 subsystem is not supported by

Subsystem Control Facility (SCF)

DSM, you can use the CMI ALTER SUBDEVICE command. Refer to the

Communications Management (CMI) Operator’s Guide

for more

information. The lines for the TR3271 and targeted AM3270 subdevice must be in

the STARTED summary state.

Command

ZCOM-CMD-CONNECT

Object Type

ZCOM-OBJ-SU

Tokens in Command Buffer

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-TKN-TARGET-MGR token-type ZSPI-TYP-FNAME32. ZCOM-TKN-TARGET-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-TKN-TARGET-OBJTYPE token-type ZSPI-TYP-ENUM. !{}

ZCOM-MAP-REQID !MAP is optional, but if present,

!fields are required.

def ZCOM-DDL-REQID.

02 ZCRTPID type ZSPI-DDL-CRTPID. 02 ZPAID type ZSPI-DDL-INT.

end.

ZCOM-TKN-CMD-TIMEOUT token-type ZSPI-TYP-TIMESTAMP. ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{}

6-31

COMMANDS AND RESPONSES CONNECT Command

ZSPI-TKN-MAXRESP token-type ZSPI-TYP-INT. ZSPI-TKN-RESPONSE-TYPE token-type ZSPI-TYP-ENUM.

ZSPI-TKN-ALLOW-TYPE token-type ZSPI-TYP-ENUM. ZSPI-TKN-COMMENT token-type ZSPI-TYP-STRING.

Tokens in Response Buffer

ZSPI-TKN-SERVER-VERSION token-type ZSPI-TYP-INT. !{} ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{}

ZSPI-TKN-DATALIST token-type ZSPI-TYP-LIST.

ZSPI-TKN-ENDLIST token-type ZSPI-TYP-SSCTL.

Tokens in Command Buffer

ZCOM-TKN-OBJNAME specifies the TR3271 subdevice that is to be connected to the target subdevice. Your application must provide this token in the command. This token is described in "Data-Communications Standard Definitions" in Section 5 and the

Communications Management Programming Manual

ZCOM-TKN-TARGET-MGR specifies the name of the manager controlling the AM3270 subdevice to which you want to establish a link. If your management application does not provide a value, the TR3271 subsystem derives the line name from the ZCOM-TKN-TARGETOBJNAME token. The value of the ZCOM-TKN-TARGET-MGR token, if specified, should always be the line name associated with the AM3270 subsystem to which you want to establish a connection.

ZCOM-TKN-TARGET-OBJNAME specifies the name of the AM3270 subdevice to which you want to build a link. This token is required.

ZCOM-TKN-TARGET-OBJTYPE specifies the type of object to which you want to build a link. This token is required and must have the value ZCOM-OBJ-SU.

6-32

COMMANDS AND RESPONSES

CONNECT Command

Management Programming Manual

Communications

Programming Manual

Distributed Systems Management (DSM)

Tokens in Response Buffer

ZSPI-TKN-DATALIST indicates the beginning of a data list. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

ZCOM-TKN-OBJNAME specifies the name of the TR3271 subdevice that was trying to build a link to the AM3270 subdevice. Unless there is an error that prevents the CONNECT command from being attempted at all, this token is present in every response record. ZCOM-TKN-OBJNAME is described in "Data-Communications Standard Definitions" in Section 5 and the

Programming Manual

Communications Management

ZCOM-TKN-OBJTYPE specifies the type of TR3271 object that attempted to build a link. The only valid value for this token is ZCOM-OBJ-SU. This token is described in "Data-Communications Standard Definitions" in Section 5, "Common Definitions," and the

Communications Management Programming Manual

ZSPI-TKN-ERRLIST indicates the beginning of an error list. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

ZSPI-TKN-RETCODE specifies the return code for the command. This token is described in "SPI Standard Definitions" in Section 5 and the

Distributed Systems Management (DSM) Programming Manual

. For details on the data-communications error numbers and their associated error lists, see "Common Error Numbers and Error Lists" in the

Communications Management Programming Manual

. For details on the TR3271 error numbers and their associated error lists, see Appendix A in this manual.

6-33

COMMANDS AND RESPONSES CONNECT Command

The possible nonzero values of RETCODE in response to the CONNECT command are as follows:

ZCOM-ERR-EMPT-RSP (-33) ZCOM-ERR-TKN-VAL-INV (-30) ZCOM-ERR-TKN-REQ (-29) ZCOM-ERR-TKN-DUP (-27) ZCOM-ERR-TKN-CODE-INV (-26) ZCOM-ERR-SSID-INV (-24) ZCOM-ERR-SECUR-VIOL (-22) ZCOM-ERR-OBJNAME-INV (-19) ZCOM-ERR-FNAME-INV (-9) ZCOM-ERR-CMD-TIMED-OUT (-7)

ZCOM-ERR-PATH-DOWN (-20)

There has been an unexpected loss of the link between the AM3270 and TR3271 subdevice.

ZCOM-ERR-OBJ-NOT-SUPP (-18)

Your management application has tried to build a link either from an object that is not supported by the TR3271 subsystem, or to an object not supported by the AM3270 subsystem. The CONNECT command is valid only for the object type ZCOM-OBJ-SU.

ZCOM-ERR-OBJ-NOT-FOUND (-17)

Your application has tried to build a link from a TR3271 subdevice that does not exist. Issue the LISTOBJECTS command to determine the subdevices that exist and reissue the CONNECT command with an appropriate subdevice.

ZCOM-ERR-CMD-MISMATCH (-4)

Your management application tried to build a link from a process or line by using the object type ZCOM-OBJ-PROC or ZCOM-OBJ-LINE, respectively. The command is valid only for the object type ZCOM-OBJ-SU.

ZCOM-ERR-CMD-INV-IN-SUMSTATE (-3)

Your management application tried to connect a subdevice while the target AM3270 subdevice or the TR3271 subdevice was not in the STARTED summary state. Or, the line associated with one of the subdevices is in the DIAGNOSING or STOPPED summary state.

ZTR3-ERR-TARGET-OBJ-NOT-FOUND (3)

Your management application tried to build a link to an AM3270 subdevice that does not exist.

6-34

COMMANDS AND RESPONSES

CONNECT Command

ZTR3-ERR-NOT-PTP-SU (5)

Your management application tried to build a link from or to a subdevice that is not a PTP subdevice. The subdevices that you connect must both be capable of using the pass-through protocol.

ZTR3-ERR-TARGET-OBJNAME-INV (10)

The object name for the target AM3270 subdevice does not comply with the valid format.

ZSPI-TKN-ENDLIST indicates the end of a data list or an error list. This token is described in "SPI Standard Definitions" in Section 5 and the

Programming Manual

Distributed Systems Management (DSM)

Operational Notes

• CONNECT is a sensitive command.

• The line and subdevice must be in the STARTED summary state

when this command is issued.

• When the command is completed, the lines and subdevices remain

in the STARTED summary state.

• To disconnect the link between the AM3270 and TR3271

subdevices, use the DISCONNECT command.

6-35

COMMANDS AND RESPONSES DELETE Command

DELETE Command

The DELETE command removes subdevices from the TR3271 subsystem. You can delete subdevices, but not a process or line.

When you use the DELETE command, the subdevices to be deleted must be in the STOPPED summary state. In addition, when your management application issues the DELETE command using the LINE object, the subsystem checks for the subordinate-modifier token. This token must be present and its value must be ZCOM-VAL-SUBONLY. If the token is not present, the subsystem returns an error.

When your management application issues the DELETE command using the SU object, the subsystem deletes only the specified subdevice. Although the subordinate modifier can be present for the SU object, the only valid values are ZCOM-VAL-SUB-NONE and ZCOM-VAL-SUB-ALL. If your management application specifies the subordinate modifier with the value ZCOM-VAL-SUB-ONLY value for a subdevice, the subsystem returns an error.

Command

ZCOM-CMD-DELETE

Object Type

ZCOM-OBJ-LINE

ZCOM-OBJ-SU

Tokens in Command Buffer

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !{} ZCOM-MAP-REQID !MAP is optional, but if present,

!fields are required.

def ZCOM-DDL-REQID.

02 ZCRTPID type ZSPI-DDL-CRTPID. 02 ZPAID type ZSPI-DDL-INT.

end.

ZCOM-TKN-CMD-TIMEOUT token-type ZSPI-TYP-TIMESTAMP. ZCOM-TKN-SUB token-type ZSPI-TYP-ENUM.

ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. ZSPI-TKN-SSID token-type ZSPI-TYP-SSID. !{}

6-36

HP TR3271 Programming Manual

Specifications and Main Features

Frequently Asked Questions

User Manual