HP NonStop Pathway/iTS Programming Manual

NonStop Pathway/iT S
Management
Programming Manual

Abstract

This manual describes the Subsystem Programmatic Interface (SPI) interface to
Pathway/iTS product; it is intended for programmers writing applications that manage
Pathway/iTS. It describes the SPI commands and messages for Pathway/iTS
objects—those related to terminal control processes (TCPs), terminals, and intelligent
devices.

Product Version

Pathway/iTS 1.0

Supported Release Version Updates (RVUs)

This publication supports D42.00 and all subsequent D4x.00 releases, G02.00 and all
subsequent G-series RVUs, and H06.03 and all subsequent H-series RVUs until
otherwise indicated by its replacement publications.

Part Number Published

426749-002 February 2006

Document History

Part Number Product Version Published

120042 Pathway/TS D42 August 1996
42674 9-001 Pathw ay/iTS 1. 0 Octo ber 2000
426749-002 Pathway/iTS 1.0 February 2006

Hewlett-Packard Company—426749-002

i

NonStop Pathway/iTS
Management Programming
Manual

Index Examples Figures Tables

What’s New in This Manual ix

Manual Information ix
New and Changed Information ix

About This Manual xi

Who Should Read This Manual xi
Related Documentation xii
Notation Conventions xiii

1. Introduction

Which Sections Do You Need? 1-1
Architecture and Components 1-2
Distributed Systems Management 1-4
Management Interfaces 1-5

PATHCOM Interface 1-6
SPI Interface 1-6

2. Pathway/iTS Management Programming

Comparison of PATHCOM and SPI Commands 2-1
Pathway Management Programming Interface 2-4

Control and Inquiry

2-5

Sending Commands and Receiving Replies

2-5

3. SPI Programming Considerations

Definition Files 3-1

Naming Conventions 3-2
Contents 3-2
Location 3-3
Which Files Do You Need?

3-3

Message Elements for the Pathway Subsystem

3-4

Commands 3-4
Object Types 3-6
Object Names 3-8

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

ii

3. SPI Programming Considerations (continued)

3. SPI Programming Considerations (continued)

Object-Select or Tokens 3-8
Event Numbers 3-9
Other Tokens 3-9
Extensible Structured Tokens 3-10
Types for Fields in Structured Tokens 3-17
Data Lists and Error Lists 3-18

Building and Sending a Command Message 3-19

Summary of Steps 3-19
Considerations for SSINIT 3-20
Considerations for SSPUT 3-21
Considerations for SSNULL and Extensible Structured Tokens 3-21
Specifying Continuation 3-21
Required Object States for Continuation 3-23
Continuation Example 3-24
32-Byte File Names 3-25
Resetting Values in Fields 3-26

Receiving and Decoding Response Messages 3-27

Summary of Steps 3-27
Considerations 3-27

Event and Error Handling 3-28

Event Message Subject Tokens 3-28
Event-Specific Tokens 3-29
Error Messages 3-29
Message Numbers 3-30

Security 3-31
Naming Guidelines for Applications 3-31
Programming Considerations for Specific Object Types 3-32

TCP Objects 3-32
TERM Objects 3-33
PROG Objects 3-33
Tell Messages 3-33

Writing C Programs 3-34
Command Presentation 3-35

Unlisted Tokens 3-36
Required Tokens and Fields 3-36

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

iii

4. SPI and EMS Standard Definitions

4. SPI and EM S Standard Defi ni ti on s

SPI Standard Definitions 4-1
EMS Standard Definitions 4-1

5. ZPWY -DDL- Definitions

Pathway Subsystem Definitions 5-1
Buffer Declarations 5-3
Object Names 5-3

Token Codes for Object Names 5-4
ZPWY-DDL-PROGNAME 5-4
ZPWY-DDL-PROGTERMNAME 5-4
ZPWY-DDL-SCOBOL-PUNAME 5-5
ZPWY-DDL-SCTCPNAME 5-5
ZPWY-DDL-SCTERMNAME 5-5
ZPWY-DDL-TCPLINKNAME 5-6
ZPWY-DDL-TCPNAME 5-6
ZPWY-DDL-TCPSCNAME 5-6
ZPWY-DDL-TCPTERMNAME 5-7
ZPWY-DDL-TELLNAME 5-7
ZPWY-DDL-TERMNAME 5-7
ZPWY-DDL-UNKNOWNNAME 5-8

Private Token and Field Types 5-8

ZPWY-DDL-AUTO-RESTART 5-8
ZPWY-DDL-CHAR15 5-8
ZPWY-DDL-CHAR30 5-9
ZPWY-DDL-CHAR132 5-9
ZPWY-DDL-CPU 5-9
ZPWY-DDL-DUMP-INFO 5-9
ZPWY-DDL-ERRINFO2 5-11
ZPWY-DDL-ERROR-INFO 5-12
ZPWY-DDL-FILLER 5-12
ZPWY-DDL-INSPECT-INFO 5-12
ZPWY-DDL-IO-PROTOCOL 5-13
ZPWY-DDL-OBJECT-NAME 5-13
ZPWY-DDL-ON-OFF 5-14
ZPWY-DDL-ON-OFF-CURRENT 5-14
ZPWY-DDL-OWNER-ID 5-14
ZPWY-DDL-PRINTER-INFO 5-15
ZPWY-DDL-TERM-TYPE 5-16

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

iv

5. ZPWY-DDL- Definitions (continued)

5. ZPWY -DDL- Definitions (continued)

ZPWY-DDL-TERMTYPE-INFO 5-17
ZPWY-DDL-TMF-RESTARTS 5-20
ZPWY-DDL-YES-NO 5-20
ZPWY-DDL-0-2045 5-20
ZPWY-DDL-0-2250 5-20
ZPWY-DDL-0-4095 5-21
ZPWY-DDL-1-199 5-21
ZPWY-DDL-1-255 5-21

Predefined Token and Field Values 5-21
Private Field Types for Predefined Values 5-22

ZPWY-DDL-CHARSET-VALUE 5-22
ZPWY-DDL-FRZSTATETERM-VALUE 5-23
ZPWY-DDL-NONSTOP-VALUE 5-23
ZPWY-DDL-OBJSTATE-VALUE 5-23
ZPWY-DDL-POP-V ALUE 5-23
ZPWY-DDL-SECURITY-VALUE 5-24
ZPWY-DDL-TCPQUALST ATE-VALUE 5-24
ZPWY-DDL-TERMPEND-VALUE 5-24
ZPWY-DDL-TERMWAIT-VALUE 5-25
ZPWY-DDL-TRMQUALSTATE-VALUE 5-25

Simple Tokens 5-25

6. ZPWY-MAP- Definitions

Extensible Structured Tokens 6-1
ZPWY-MAP-DEF-PATHWAY 6-3
ZPWY - MAP-DEF-PROG 6-6
ZPWY-MAP-DEF-PROGTERM 6-8
ZPWY-MAP-DEF-TCP 6-13
ZPWY-MAP-DEF-TELL 6-25
ZPWY-MAP-DEF-TERM 6-26
ZPWY-MAP-PAR-CONTROL-TCP 6-33
ZPWY-MAP-PAR-INFO 6-35
ZPWY-MAP-PAR-INSPECT-TERM 6-36
ZPWY-MAP-PAR-START-PROG 6-37
ZPWY - MAP-PAR-START-TERM 6-38
ZPWY - MAP-PAR-STATS-SCTCP 6-38
ZPWY - MAP-PAR-STATS-TCP 6-40
ZPWY - MAP-PAR-STATS-TCPSC 6-40

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

v

6. ZPWY-MAP- Definitions (continued)

6. ZPWY-MAP- Definitions (continued)

ZPWY-MAP-PAR-STATS-TCPTERM 6-41
ZPWY-MAP-PAR-STATS-TERM 6-41
ZPWY-MAP-PAR-SUSPEND-TERM 6-42
ZPWY-MAP-PAR-TELL-TERM 6-42
ZPWY -MAP-QUAL-TCP 6-43
ZPWY - MAP-QUAL-TERM 6-44
ZPWY - MAP-SEL-PROG 6-44
ZPWY - MAP-SEL-PROGTERM 6-45
ZPWY - MAP-SEL-SCTCP 6-45
ZPWY - MAP-SEL-SCTERM 6-45
ZPWY - MAP-SEL-TCP 6-46
ZPWY - MAP-SEL-TCPLINK 6-46
ZPWY - MAP-SEL-TCPSC 6-46
ZPWY - MAP-SEL-TCPTERM 6-47
ZPWY - MAP-SEL-TELL 6-47
ZPWY -MAP-SEL-TERM 6-47
ZPWY - MAP-STARTPROG 6-48
ZPWY - MAP-STATS-SC 6-49
ZPWY - MAP-STATS-TCP1 6-50
ZPWY - MAP-STATS-TCP2 6-53
ZPWY -MAP-STATS-TERM1 6-60
ZPWY -MAP-STATS-TERM2 6-62
ZPWY -MAP-STATUS-TCP 6-70
ZPWY-MAP-STATUS-TCPLINK 6-72
ZPWY - MAP-STATUS-TERMDETAIL 6-73
ZPWY - MAP-STATUS-TERMFREEZE 6-79
ZPWY-MAP-TELLNUM 6-79

7. Terminal Control Process (TCP) Commands

ADD TCP 7-2
ALTER TCP 7-4
CONTROL TCP 7-6
DELETE TCP 7-8
GETVERSION TCP 7-9
INFO TCP 7-11
REFRESHCODE TCP 7-13
START TCP 7-15
STATS SCTCP 7-17

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

vi

7. Term inal Control Process (TCP)
Commands (continued)

7. Terminal Control Process (TCP) Commands ( continued)

STATS TCP 7-19
STATS TCPSC 7-21
ST ATUS TCP 7-23
ST ATUS TCPLINK 7-25
STOP TCP 7-27
SWITCH TCP 7-29

8. TERM Commands

ABORT TCPTERM 8-2
ABORT TERM 8-3
ADD TERM 8-4
ALTER TERM 8-6
DELETE TCPTERM 8-8
DELETE TERM 8-9
FREEZESTATUS SCTERM 8-10
INFO TCPTERM 8-12
INFO TERM 8-14
INSPECT TERM 8-16
RESUME TCPTERM 8-17
RESUME TERM 8-19
START TCPTERM 8-21
START TERM 8-23
STATS TCPTERM 8-25
STATS TERM 8-27
ST ATUS TCPTERM 8-29
ST ATUS TERM 8-31
STOP TCPTERM 8-33
STOP TERM 8-35
SUSPEND TCPTERM 8-37
SUSPEND TERM 8-39

9. PROG Commands

ADD PROG 9-1
ADD PROGTERM 9-4
ALTER PROG 9-6
ALTER PROGTERM 9-8
DELETE PROG 9-10
DELETE PROGTERM 9-11

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

vii

9. PROG Commands (continued)

9. PROG Commands (continued)

INFO PROG 9-13
INFO PROGTERM 9-15
START PROG 9-17

10. Tell Message Commands

ADD TELL 10-1
DELETE TELL 10-3
INFO TELL 10-4
START TELL 10-5
TELL TE RM 10-6
TELL TCPTERM 10-7

11. TCP Event Messages

Message Numbers 11-1
Event-Message Format 11-1

Unlisted Tokens 11-2
Listed Tokens 11-2
Subject Tokens 11-2
Event-Message Text 11-3
Additional Information for Terminal Errors 11-3
Simple Tokens 11-3
Error Recovery 11-4

Event-Message Range 3000 Through 3999 11-4

12. TCP Error Messages

Message Numbers 12-1
Error Presentation

12-1

Errors in STATUS TCP and STATUS TERM Command Responses

12-2

Errors in Error Lists 12-2
Object Types in Error Lists 12-2
Additional Information for Terminal Errors 12-3
Error Recovery 12-3

Error-Message Range 3000 Through 3999 12-3

13. Managem ent Progra m ming Example s

Configuring Pathway/iTS 13-1
Obtaining PROG Information 13-15

Contents

NonStop Pathway/iTS Management Programming Manual —426749-002

viii

14. Error Handling Example Program

14. Error Handling Example Program
Index

Examples

Example 3-1. Format for 32-Byte File Names 3-25
Example 13-1. Pathway/iTS Configuration Program 13-2
Example 13-2. Obtaining PROG Information 13-15
Example 14-1. Handling Errors 14-2

Figures

Figure 1-1. A NonStop TS/MP Application With Pathway/iTS 1-3
Figure 1-2. Pathway/iTS and DSM 1-5
Figure 1-3. Pathway/iTS Management Interfaces 1-6
Figure 1-4. Management Programming Environment 1-7
Figure 2-1. Sending Commands and Receiving Responses 2-6

Tables

Table 1-1. Configuration and Manual Correspondences 1-1
Table 2-1. PATHCOM and SPI Commands for Pathway/iTS 2-2
Table 3-1. Pathway/iTS Programmatic Commands 3-4
Table 3-2. TS/MP Commands Affecting Pathway/iTS Objects 3-6
Table 3-3. Pathway/iTS Object Types 3-6
Table 3-4. Commands and Objects 3-8
Table 3-5. Required Object States for Continuation 3-23
Table 3-6. Reset Constants 3-26
Table 3-7. Event Message Subject Tokens 3-28
Table 3-8. Event-Specific Pathway EMS Tokens 3-29
Table 3-9.

Restricted Commands and Objects for Pathway/iTS 3-31

Table 4-1.

EMS Standard Definitions for Header Tokens 4-1
Table 4-2. EMS Standard Definition for Data-Portion Tokens 4-1
Table 5-1. Pathway Buffer Declarations 5-1
Table 5-2. Pathway/iTS Object Names 5-1
Table 5-3. Pathway/iTS Private Token and Field Types 5-2
Table 5-4. Pathway Predefined Token and Field Values 5-2
Table 5-5. Pathway/iTS Field Types for Predefined Values 5-2
Table 6-1. Categories of Extensible Structured Tokens 6-1
Table 6-2. Pathway/iTS Extensible Structured Tokens 6-2

NonStop Pathway/iTS Management Programming Manual —426749-002

ix

What’s New in This Manual

Manua l In forma tion

NonStop Pathway/iTS Management Programming Manual

Abstract

This manual describes the Subsystem Programmatic Interface (SPI) interface to
Pathway/iTS product; it is intended for programmers writing applications that manage
Pathway/iTS. It describes the SPI commands and messages for Pathway/iTS
objects—those related to terminal control processes (TCPs), terminals, and intelligent
devices.

Product Version

Pathway/iTS 1.0

Supported Release Version Updates (RVUs)

This publication supports D42.00 and all subsequent D4x.00 releases, G02.00 and all
subsequent G-series RVUs, and H06.05 and all subsequent H-series RVUs until
otherwise indicated by its replacement publications.

Document History

New and Changed Information

Change in the G06.28 manual:
Changed the maximum number of concurrently running requester processes from 150

to 800 under Considerations on page 6-5.

Changes in the G06.27 Manual

Pathway/iTS was formerly called Pathway/TS. For the Pathway/iTS 1.0 independent
product release, the product was renamed to conform to current HP product naming
standards and to reflect the new Internet (web client) capabilities of the product. After
the first reference to the product name in each section of this manual, subsequent
references use the shortened form of the name, Pathway/iTS.

Part Numb er Pub l i sh ed

426749- 002 February 2006

Part Number Product Version Published

120042 Pathway/TS D42 August 1996
426749-001 Pathway/iTS 1.0 October 2000
426749-002 Pathway/iTS 1.0 February 2006

What’s New in This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

x

Product Changes

Product Changes

This manual editi o n docu ment s the follow ing ch anges in the P athwa y/i TS man agem ent
programming interface:

•

A new gateway program has been provided to support web clients. Information
specific to configuring the TCP for the web gateway has been added to the
descriptions of the following token fields of ZPWY-MAP-DEF-TCP: ZMAXREPLY
on page 6-19, ZMAXTERMDAT A on page 6-19, ZSERVERPOOL on page 6-20,

ZTERMBUF on page 6-22, and ZTERMPOOL on page 6-23.

•

A new token field, ZERRORFILTER, has been added to ZPWY-DDL-DEF-TCP to
support filtering of 3161 timeout error messages when the ON ERROR clause is
used with a SEND MESSAGE statement. ZPWY-MAP-DEF-TCP on page 6-13
describes this new attribute, and the syntax descriptions of the other TCP
configuration commands include the attribute.

•

Eleven new TCP event messages, 3140: ZPWY-EVT-TCP-ROUTIO through 3150:

ZPWY-EVT-TCP-NWRECVERROR, have been added.

•

Eleven new TCP errors, 3140: ZPWY-ERR-TCP-ROUTIO through 3150: ZPWY-

ERR-TCP-NWRECVERROR, have been added.

Correct ions and Enhancements to the Manual

The following organizational changes and enhancements have been made to the
material in this manual:

•

Appendix A, “Configuration Limits and Defaults,” has been deleted because it is
redundant. This appendix is an exact copy of Appendix C in the Pathway/iTS
System Management Manual.

•

References to Compaq trademarks have been updated.

•

References to obsolete products have been removed.

•

Miscellaneous terminology changes and editorial corrections have been made.

NonStop Pathway/iTS Management Programming Manual —426749-002

xi

About This Manual

This is a reference manual for the token-oriented management programming interface
to Pathway/iTS, which, together with TS/MP, is called the Pathway subsystem in HP
Distributed Systems Management (DSM) terminology. It describes Subsystem
Programmatic Interface (SPI) commands used to configure and control Pathway/iTS
objects in a PATHMON environment and to monitor the status and performance of
those objects. This manual also provides syntax and complete descriptions of event,
error, and warning messages issued by TCPs using the Event Management Service
(EMS).

The TS/MP Management Programming Manual is a prerequisite to this manual. For
information about management of the PATHMON environment as a whole and the
management programming interface to TS/MP objects, see the TS/MP Management
Programming Manual.

This manual is also intended to be used in conjunction with the Pathway/iTS System
Management Manual, which discusses how to manage Pathway/iTS objects and
provides strategies for system management.

Who Should Read This Manual

This manual is intended for individuals writing applications that manage Pathway/iTS
objects in a PATHMON environment. Such programmers also need the reference
information in the TS/MP Management Programming Manual and the task-oriented
information in the Pathway/iTS System Management Manual. It is also assumed that
readers have a general knowledge of HP NonStop™ server programming concepts.

To use this manual effectively, you should be familiar with the following subjects:

•

Basic NonStop server architecture

•

Programming for the HP NonStop operating system

•

Programming using the Transaction Application Language (TAL), the HP Tandem
Advanced Command Language (TACL), C, or COBOL

•

Reading declarations written in the Data Definition Language (DDL), as described
in the SPI Programming Manual

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xii

Related Documentation

Related Documentation

In addition to this manual, information about Pathway/iTS appears in the following
publications:

For additional information on informational, warning, and error messages, see the
following manual:

Pathway SCREEN
COBOL Reference Manual

Describes the SCREEN COBOL programming language which
is used for w rit ing programs th at define and co nt rol terminal
displays or int elligent devi ce s for online transact ion processin g
applicat ions running in a PATHMON environme nt .

Pathway/iTS SCUP
Reference Manual

Describes m anaging a SCREEN CO BOL library w it h t he
SCREEN COBOL Utility Program (SCUP).

Pathw ay/iTS W eb Client
Programm ing Manu al

Describes how to convert SCREEN COBOL requesters to web
clients, explains how to build and deploy those cli ent s, and
also provides the information Java developers and web
designers need to modi fy and enhance the Java and H T M L
portions of the converted cl ients.

Pathway/iTS TCP and
Terminal Programming
Guide

A guide for programmers who are writing SCREEN COBOL
requesters to be used in Pathway applications.

Pathway/iTS System
Management Manual

Describes how to start, configure, and manage Pathway/iTS
objects within a PATHMO N environment using the PATHCOM
interactive management interface. This manual also includes
information on monito ring and adju sting your PAT H M ON
environment to optimize performance and on diagnosing and
fixing problems, as well as manageability guidelines on topics
such as how to start PATHMON-controlled objects in parallel
to help perf ormance.

Pathway Products
Glossary

Defines technical terms used in this manual and in other
manuals for the Pathway products: Pathway/iTS, TS/MP, and
Pathway/XM.

Operator M essages
Manual

Describes all messages t hat are distribut ed by the Event
Management Service (EMS), including those generated by
NonStop TS/MP and Pathway/iTS processes.

Guardian Procedure Errors
and Messages Manu al

Describes the Guardian messages for NonStop systems that
use the NonStop operating system. The manual covers error
codes and error lists associated with Guardian procedure calls,
the interprocess messages sent to application programs by the
operating system and the command interpreter.

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xiii

Notation Conventions

For information about other HP products associated with Pathway/iTS management
programming, see the following publications:

Notation Conventions

General Sy ntax Notation

The following list summarizes the notation conventions for syntax presentation in this
manual.

UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter

these items exactly as shown. Items not enclosed in brackets are required. For
example:

MAXATTACH

lowercase italic letters. Lowercase italic letters indicate variable items that you supply.

Items not enclosed in brackets are required. For example:

file-name

computer type. Computer type letters within text indicate C and Open System Services

(OSS) keywords and reserved words. Type these items exactly as shown. Items not
enclosed in brackets are required. For example:

myfile.c

italic computer type. Italic computer type letters within text indicate C and Open

System Services (OSS) variable items that you supply. Items not enclosed in brackets
are required. For example:

pathname

[ ] Brackets. Brackets enclose optional syntax items. For example:

TERM [\system-name.]$terminal-name
INT[ERRUPTS]

A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list may be arranged either vertically, with aligned brackets on

SPI Programmi ng Manual Describes the Subsystem Prog r ammatic Int erfa ce (S PI), wh i ch

is used for wr i ti ng a ppl i cations that manage HP su bs yste ms fo r
NonStop systems. SPI provides a set of procedure calls and a
set of definit ion fi les to be used in manag ement pro grams.

EMS Manual Describes how to write event-message filters to select

messages of particular interest and how to distribute event
messages to various destinations.

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xiv

General Syntax Notation

each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:

LIGHTS [ ON ]
[ OFF ]
[ SMOOTH [ num ] ]

K [ X | D ] address-1

{ } Braces. A group of items enclosed in braces is a list from which you are required to

choose one item. The items in the list may be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and
separated by vertical lines. For example:

LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }

ALLOWSU { ON | OFF }

| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in

brackets or braces. For example:

INSPECT { OFF | ON | SAVEABEND }

% Percent Sign. A percent sign precedes a number that is not in decimal notation. The

% notation precedes an octal number. The %B notation precedes a binary number.
The %H notation precedes a hexadecimal number. For example:

%005400
%B101111
%H2F
P=%p-register E=%e-register

… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you

can repeat the enclosed sequence of syntax items any number of times. For example:

M address [ , new-value ]…
[ - ] {0|1|2|3|4|5|6|7|8|9}…

An ellipsis imme diately fol lowing a single syntax item indi cates that you can repeat that
syntax item any number of times. For example:

"s-char…"

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xv

Notation for Messages

… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you

can repeat the enclosed sequence of syntax items any number of times. For example:

M address-1 [ , new-value ]...
[ - ] {0|1|2|3|4|5|6|7|8|9}...

An ellipsis imme diately fol lowing a single syntax item indi cates that you can repeat that
syntax item any number of times. For example:

"s-char..."

Punctuation. Parentheses, commas, semicolons, and other symbols not previously

described must be entered as shown. For example:

error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name

Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must enter as shown. For example:

"[" repetition-constant-list "]"

Item Spacing. Spaces shown between items are required unless one of the items is a

punctuation symbol such as a parenthesis or a comma. For example:

CALL STEPMOM ( process-id ) ;

If there is no space between two items, spaces are not permitted. In the following
example, there are no spaces permitted between the period and any other items:

$process-name.#su-name

Line Spacing. If the syntax of a command is too long to fit on a single line, each

continuation line is indented three spaces and is separated from the preceding line by
a blank line. This spacing distinguishes items in a continuation line from items in a
vertical list of selections. For example:

ALTER [ / OUT file-spec / ] CONTROLLER
[ , attribute-spec ]...

Notation for Messages

The following list summarizes the notation conventions for the presentation of
displayed messages in this manual.

Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or

returned exactly as shown. For example:

Backup Up.

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xvi

Notation for Management Programming Interfaces

lowercase italic letters. Lowercase italic letters indicate variable items whose values are

displayed or returned. For example:

p-register
process-name

[ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For

example:

Event number = number [ Subject = first-subject-value ]

A group of items enclosed in brackets is a list of all possible items that can be
displayed, of which one or none mi ght actu ally be displaye d. The items in the list might
be arranged either vertically, with aligned brackets on each side of the list, or
horizontally, enclosed in a pair of brackets and separated by vertical lines. For
example:

LDEV ldev [ CU %ccu | CU %... ] UP [ (cpu,chan,%ctlr,%unit) ]

{ } Braces. A group of items enclosed in braces is a list of all possible items that can be

displayed, of which one is actually displayed. The items in the list might be arranged
either vertically, with aligned braces on each side of the list, or horizontally, enclosed in
a pair of braces and separated by vertical lines. For example:

LBU { X | Y } POWER FAIL
process-name State changed from old-objstate to objstate

{ Operator Request. }
{ Unknown. }

| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in

brackets or braces. For example:

Transfer status: { OK | Failed }

% Percent Sign. A percent sign precedes a number that is not in decimal notation. The

%þnotation precedes an octal number. The %Bþnotation precedes a binary number.
The %Hþnotation precedes a hexadecimal number. For example:

%005400
P=%p-register E=%e-register

Notation for Management Programming Interfaces

The following list summarizes the notation conventions used in the boxed descriptions
of programmatic commands, event messages, and error lists in this manual.

UPPERCASE LETTERS. Uppercase letters indicate nam es from defini tion files; enter these

names exactly as shown. For example:

ZCOM-TKN-SUBJ-SERV

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xvii

Change Bar Notation

lowercase letters. Words in lowercase letters are words that are part of the notation,

including Data Definition Language (DDL) keywords. For example:

token-type

!r. The !r notation following a token or field name indicates that the token or field is

required. For example:

ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !r

Change Bar Notation

Change bars are used to indicate substantive differences between this manual and its
preceding version. Change bars are vertical rules placed in the right margin of
changed portions of text, figures, tables, examples, and so on. Change bars highlight
new or revised information. For example:

The message types specified in the REPORT clause are different in the COBOL
environment and the Common Run-Time Environment (CRE).

The CRE has many new message types and some new message type codes for
old message types. In the CRE, the message type SYSTEM includes all
messages except LOGICAL-CLOSE and LOGICAL-OPEN.

About This Manual

NonStop Pathway/iTS Management Programming Manual —426749-002

xviii

Change Bar Notation

NonStop Pathway/iTS Management Programming Manual —426749-002

1-1

1 Introduction

This manual describes the management programming interface to the PATHMON
environment provided by Pathway/iTS. It describes how to use programmatic
commands in a management application to configure Pathway/iTS objects that support
transaction-pr ocessing requ esters, how to m oni tor the st at us and p erfo rma nce of th ese
objects, and how to handle error and event messages returned by the Pathway
subsystem.

Which Sections Do You Need?

This manual is organized into logical groups of information for easy reference.

Table 1-1 is a descriptive map indicating which sections are relevant to particular

operating environments.

Note. This ma nual describ es th e objects created and con tr olled by the Pathway/iTS produc t to
support reques t ers in a Pathway environment. Objects created and contro lled by the TS / M P
product, w hich support servers in a Pathway environment , a r e describe d in a separate manual
set. For mor e i nformation about those objects, see t he TS/MP Manageme nt Pr ogram m ing
Manual.

Table 1-1. Configuration and Manual Correspondences

If Y our Configuration
Includes… You Need… To Perform the Following…

SPI management
interface

Section 2
Section 3

Sections 4-6

Sections 11­12

Section 13
Section 14

Learn how to do management programming
Learn Pathway/iTS-specific programming

information
Look up definitions of command and response

tokens
Look up event and error messages
See management pr ogramming examp les
See error-handling examples

Internal TCPs Section 7

Section 10
Section 11
Section 12

Defin e and contr ol TCPs
Control messages from TCPs to terminals
Handle event messages from TCPs
Handle error messages from TCPs

Terminals Section 8 Define and control configured TERM objects;

contr ol and obtain inf ormati on about
temporary TERM objects

Templates for terminals
running other than
SCREEN COBOL
programs

Section 9 Define and control PROGRAM objects

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-2

Architecture and Components

TS/MP is described in a separate manual set. For more information about that product,
see the TS/MP Management Programming Manual.

Architecture and Components

The Pathway subsystem includes a group of related software tools that enable your
organization to develop, install, and manage online transaction processing
applications.

Transaction processing applications consist of two types of programs: requester
programs (called clients in other environments) and server programs. Among other
benefits, the requester/server design allows application logic to be distributed near the
resources it manages. For example, presentation services are located in requester
programs near the I/O devices; database logic resides in server programs near the
database. Requesters and servers communicate using the message system provided
by the NonStop operating environment.

Link managers (such as terminal control processes (TCPs) and TS/MP LINKMON
processes) coordinate the sharing of links between requesters and server processes.
The PATHMON process, in addition to creating, configuring, and globally managing
server classes, grants links to link managers that request access to server processes.

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-3

Architecture and Components

Figure 1-1 shows a simple TS/MP application that uses Pathway/iTS. This example

shows the TCP and the PATHMON process managing communications between
requesters and servers in the Guardian operating environment.

Figure 1-1. A NonStop TS/MP Application With Pathway/iTS

Guardia n Operat ing E n v iro nment

No n Stop T S /MP

PA T H MON

En vi ro n ment

(PA T HWAY

Ob je c t)

P a th way/iTS

Pathsend

Requesters

Managem ent

Application

Process

PATHCO M

LINKMON

PATHCOM

PATHMON

SERVER

(Server Class)

Server

Processes

TERM (Tem porary,

from RU N

PROGRAM)

TERM

(Configured)

TERM

(Configured)

Ap plic atio n

Database

Ap plic atio n

Database

TCP

Screen

Program

Remote
System

Comm a n d

Te rminal

Application

Terminal

Application

Terminal

Application

Terminal

VST002.vsd

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-4

Distributed Systems Management

Distributed Systems Management

Distributed Systems Management (DSM) is a group of software tools that enables you
to construct an integrated view of a system or network. DSM tools allow you to:

•

Manage your system from a single control point.

•

Distribute control of transaction processing among systems.

•

Retain a session with one subsystem (such as the Pathway subsystem, the FUP
subsystem or the HP Non Stop Transaction Managem ent Facility (TMF) sub system)
while interacting with another subsystem.

•

Control different types of objects uniformly (objects can be of varying types,
including files, devices, and transactions).

•

Handle events (such as errors or changes in state) through a single mechanism,
regardless of which subsystem originated the event.

•

Build an integrated and uniform approach to problem determination, including
uniform reporting of events that call for operator action (for instance, a request that
an operator mount a tape); ways to tailor event reporting to your own needs; and
means for responding to events programmatically, without operator intervention.
For example, your progr am mi gh t receive no ti ce of an error and respond by issuing
a command that corrects the error.

DSM consists of num ero us compo nent s desi gn ed to han dle varied f unctions. The p ar ts
of DSM you can use with a Pathway subsystem follow:

•

The Subsystem Programmatic Interface (SPI)—a set of proced ures that provides a
token-oriented interf ace between a managemen t application and the centra l control
process within a subsystem (for example, a PATHMON process).

•

The Event Management Service (EMS)—a set of tools that collects and reports
events. In the Pathway subsystem environment, PATHMON reports errors and
status changes to EMS ; the man agem ent ap plicati on retr ieves the event messa ges
from EMS.

EMS also includes a filter language, which allows users to describe the subset of
messages an application wants to see. For more information about EMS, see the
EMS Manual.

•

The ViewPoint console application—a management application that allows
interactive communication with multiple HP products on HP NonStop Server
systems. Through a screen display, you can summon PATHCOM, as well as other
interfaces such as TMFCOM.

Using the ViewPoint application with the Pathway subsystem management
programming interface, you can control an integrated NonStop system, including
many subsystems, from one terminal. For more information about the ViewPoint
application, see the ViewPoint Manual.

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-5

Management Interfaces

•

The Distributed Name Service (DNS)—a subsystem that manages a distributed
database of names for network objects, facts about object relationships, and
instructions for replicating name definitions on remote nodes.

Figure 1-2 illustrates a Pathway subsystem that uses the SPI and EMS procedures for

subsystem control and event management.

Management Interfaces

There are two ways to configure and control Pathway/iTS: either interactively, by
entering PATHCOM commands at a terminal, or programmatically, by writing a
management application program. Both of these methods allow you to send
commands and instructions to PATHMON, the process that monitors your subsystem
and directs its activities. Figure 1-3 on page 1-6 illustrates these two interfaces and
their relationship to a PATHMON process.

Figure 1-2. Pathway/iTS and DSM

PATHMON

Managem ent

Application

Event

Collector

Event

Distributor

Event

Log

Command Message

Response

Message

GETEVENT

Comm and M essage

GETEVENT

Response

Message

VST003.vsd

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-6

PATHCOM Interface

PATHCOM Inter face

PATHCOM is a command language interpreter and interactive command interface to
the PATHMON process, the central control process for your Pathway subsystem. By
using PATHCOM, which consists of sets of object-related commands, you can
interactively define and manage all PATHMON-controlled objects.

For more information on PATHCOM, see the TS/MP System Management Manual and
the Pathway/iTS System Management Manual.

You can reduce the number of PATHCOM commands you have to enter to perform
various management activities by creating either OBEY command files or TACL
scripts. The command files or TACL scripts contain command sequences that are
automatically executed by PATHCOM.

SPI Inte r fa c e

You can also manage Pathway/iTS by using the management programming interface.
This interface supports management applications that automate configuration and
control tasks, allowing you to avoid entering many PATHCOM commands interactively
at a terminal.

The interface is a token-oriented interface based on the following:

•

Subsystem Programmatic Interface (SPI) commands and definition files

•

Event Management Service (EMS) error and event messages

Figure 1-3. Pathway/iTS Management Interfaces

Management

Application

Process

PATHCOM

PATHMO N

Process

Devices

Managem ent

Inte rfa c es

Comm and

Terminal

VST004.vsd

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-7

SPI Interface

Figure 1-4 shows the management programming environment.

Figure 1-4. Management Programming Environment

Management

Application

SPI

EMS

Pathway

Subsystem

TMF

Subsystem

Operations Environment

Managem ent

Programm ing Interface

No nS top TS /MP

Env ironm en t

Comm ands,

Inquiries

Responses,

Messages

VST005.vsd

Introduction

NonStop Pathway/iTS Management Programming Manual —426749-002

1-8

SPI Interface

NonStop Pathway/iTS Management Programming Manual —426749-002

2-1

2

Pathway/iTS Management
Programming

This section summarizes the SPI interface to the Pathway subsystem and the
commands and object types defined for the subsystem.

Comparison of PATHCOM and SPI Commands

Like PATHCOM, the SPI management programming interface to the Pathway
subsystem uses commands that operate on objects. A combination of a command and
an object type determines what action the PATHMON process should take, as well as
what additional information you must specify.

The object types used with the management programming interface are not always the
same as the object types used in PATHCOM. In some cases, they correspond exactly,
but in other cases a single PATHCOM object type is represented in the management
programming interface by a small group of object types, each of which handles a
portion of the PATHCOM object description.

The object name and additional command parameters are represented in the
management programming interface by tokens in the message buffer.

Not all PATHCOM commands are needed in the management programming interface.
Applications must indep enden tl y implemen t the basi c comm ands, which are CM DVOL,
EXIT, FC, HELP, OBEY, OBEYVOL, and OPEN. Other commands, such as SET, SET
LIKE, RESET, ALTER RESET, and SHOW, must also be implemented independently.

Some PATHCOM functions require more than one SPI command for implementation.
For example, the PATHCOM ADD TERM command becomes a request to add a
program, followed by a variable number of requests to add TERM types, one request
for each TERM type supported.

Some PATHCOM functions are implemented by new commands in the programmatic
interface. For example, to send a tell message to a TERM object, you:

1. Send a request with the ADD command, the TELL object type, and the text of the

tell message.

2. Receive ZPWY-DDL-TELLNUM from PATHMON.

3. Specify a particular TERM object by assigning the TERM name to a field in the

ZPWY-DDL-SEL-TERM token.

4. Send a request with the TELL command and the TERM object type, including both

ZPWY-DDL-SEL-TERM and ZPWY-DDL-TELLNUM.

5. Send a request with the START command and the TELL object type, again using

the number you received in Step 2.

Pathway/iTS Management Programming

NonStop Pathway/iTS Management Programming Manual —426749-002

2-2

Comparison of PA THCOM and SPI Commands

Some PATHCOM functions are implemented with a new or different command name.
For example, the PRIMARY TCP command is no longer a separate command, but
instead is implemented as part of the SWITCH TCP command.

Table 2-1 compares the PATHCOM commands with the equivalent SPI command for

the objects supported by Pathway/iTS. All SPI commands begin with the prefix ZPWY­CMD-, and all SPI object types begin with the prefix ZPWY-OBJ-.

Table 2-1. PATHCOM and SPI Commands for Pathway/iTS (page 1 of 3)

PATHCOM Commands
and Object Types

Equivalent SPI Commands (ZPWY-CM D- )
and Object Types (ZPWY-OBJ- )

Comma n d s fo r TCPs

ADD TCP ADD TCP
ALTER TCP ALTER TCP
CONTROL TCP CONTROL TCP
DELETE TCP DELETE TCP
No equiva lent GETVERSION TCP
INFO TCP INFO TCP
REFRESH-CODE TCP REFRESHCODE TCP
RESET TCP No equivalent
SET TCP No equivalent
SHOW TC P No equiv alent
START TCP START TCP
STATS SERVER STATS SCLM + STATS SCTCP
STATS TCP STATS TCP
STATS TCP, DETAIL STAT S T C P + STATS TC PSC +

STAT S T C PT ER M
STATUS TCP STATUS TCP
STATUS TCP, DETAIL STATUS TCP + STATUS TCPTERM
STOP TCP STOP TCP
PRIMARY TCP SWITCH TCP
SWITCH TCP SWITCH TCP

Commands for TERM Objects

ABORT TERM ABORT TERM
ABORT TERM *, TCP ABORT TCPTERM
ADD TERM ADD TERM
ALTER TERM ALTER TERM
DELETE TERM DELETE TERM + DELETE TCPTERM