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

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

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

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

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

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)

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

What’s New in This Manual

Manua l In forma tion

NonStop Pathway/iTS Management Programming Manual

Abstract

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

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

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

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

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 1112

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 (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

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 ZPWYCMD-, 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

Pathway/iTS Management Programming

NonStop Pathway/iTS Management Programming Manual —426749-002

2-3

Comparison of PA THCOM and SPI Commands

INFO TERM INFO TERM INFO TERM *, TCP INFO TCPTERM INSPECT TERM INS PECT TERM RESET TERM No equivalent RESUME TERM RESUME TERM RESUME TERM *, TCP RESUME TCPTERM SET TERM No equivalent SHOW TERM No equivalent START TERM START TERM START TERM *, TCP START TCPTERM STATS TER M STATS TERM STATS TERM *, TCP STATS TCPTERM STATUS SERVER, FREEZE STATUS SC + FREEZESTATUS SCTERM STATUS SERVER, PROCESSES STATUS SC + STATUS SCPROCESS +

STATUS TCPLINK STATUS TERM STATUS TERM STATUS TERM *, TCP STATUS TCPTERM STOP T ER M STOP TERM STOP TERM * , TC P STOP TCPT ER M SUSPEND TERM SUSPEND TERM SUSPEND TERM *, TCP SUSPEND TCPTERM

Commands for PROG[RAM] Objects

ADD PROGRAM ADD PROG + ADD PROGTERM ALTER PROGRAM ALTER PROG + ALTER PROGTERM +

DELETE PROGTERM DELETE PROGRAM DELETE PROG INFO PRO GRAM IN F O PROG + INF O PROGTERM RUN PROGRAM START PROG RESET PROGRAM No equivalent SET PRO GR AM No equivalent SHOW PROGRAM No equiv alent

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

PATHCOM Commands and Object Types

Equivalent SPI Commands (ZPWY-CM D- )

and Object Types (ZPWY-OBJ- )

Pathway/iTS Management Programming

NonStop Pathway/iTS Management Programming Manual —426749-002

2-4

Pathway Management Programming Interface

The Pathway management programming interface is a token-oriented interface based on the SPI message format, procedures, and definition files. The inter face consi st s of a set of programmatic commands that allow a management application to communicate directly with the PATHMON process.

Some sample management applications that might communicate with Pathway/iTS are:

•

A program that starts TERM objects automatically at a specified time at the beginning of the day. (This program would communicate with Pathway/iTS only.)

•

A program that monitors status on TERM objects and, if a device is not running, contacts data communications subsystems to obtain information on the communications line to which the device is connected. (This program would communicate with the Pathway subsystem and with data communications subsystems.)

•

A program that saves event messages for the Pathway subsystem objects and issues STATUS and INFO commands to find out more about why the event is being reported. (This program would communicate with EMS and Pathway subsystems.)

•

A program that monitors events in a PATHMON environment containing TERM objects connected through a SNAX product. When the program detects an event that reports a stopped terminal, the program responds by sending a STOP command to the SNAX software to stop the subdevice; sending a START command to the SNAX software to restart the subdevice; and sending a START command to the PATHMON process to restart the TERM object. (This program would communicate with the SNAX software and with the Pathway subsystem.)

The following paragraphs give an overview of the tasks involved in setting up and managing a Pathway subsystem. For more information on the strategy for performing specific system management tasks, see the TS/MP System Management Manual and the Pathway/iTS System Management Manual.

Commands for TELL Objects

DELETE TELL DELETE TELL INFO TELL INFO TELL TELL TERM ADD TELL + START TELL TELL TERM *, TCP TELL TERM + TELL TCPTERM

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

PATHCOM Commands and Object Types

Equivalent SPI Commands (ZPWY-CM D- )

and Object Types (ZPWY-OBJ- )

Pathway/iTS Management Programming

NonStop Pathway/iTS Management Programming Manual —426749-002

2-5

Control and Inquiry

To communicate with the PATHMON process through the Pathway management programming interface, a management application must follow these steps:

1. Start a PATHMON process if one is not already running.

2. Open the PATHMON process.

3. Build a message to send to PATHMON.

4. Send the message to PATHMON.

5. Receive a response from PATHMON.

6. Decode the response.

7. Handle errors.

8. Take any appropriate actions.

9. Close PATHMON. Information about starting, opening, and closing a PATHMON process appears in

TS/MP Management Programming Manual. Information on building and sending messages, and receiving responses to them, appears in the following paragraphs.

Sending Commands and Receiving Replies

A management application uses the SPI procedures SSINIT, SSNULL, SSPUT, SSPUTTKN, SSGET, SSGETTKN, SSMOVE, and SSMOVETKN to build a message for the PATHMON process and to retrieve values from PATHMON’s response. (For corresponding TACL procedures, see the SPI Programming Manual.)

The method you use to send and receive messages depends on the programming language in which you write your management application. Message transport is part of the language you use to program your requester; it is not part of SPI.

The management application also uses SPI to obtain event messages. The EMSGET procedure extracts the elements (that is, tokens) of the messages, and the EMSTEXT procedure obtains the text versions of the messages. For more information on event management, see Section 9, PROG Commands and Section 10, Tell Message

Commands in this manual and see the EMS Manual. Figure 2-1 on page 2-6 illustrates the commands sent and the responses received

when configuring a Pathway subsystem.

Pathway/iTS Management Programming

NonStop Pathway/iTS Management Programming Manual —426749-002

2-6

Sending Commands and Receiving Replies

For more information about how to build command messages and decode responses, see Section 3, SPI Programming Considerations. Details on the SPI procedures and their use with various languages are available in the SPI Programming Manual.

For information about points to consider when designing, configuring, and securing a management applicati o n that se nds com mands to and receives replies from a Pa thway subsystem, see the TS/MP Management Programming Manual.

Figure 2-1. Sending Commands and Receiving Responses

Management

Application

START PATHWAY

DEF PATHWAY

PATHMO N

RESPONS E

PATHMON

Config

File

SSINIT

SSPUT

WRITEREAD

SSGET

Me s sa ge Buffer

VST006.vsd

NonStop Pathway/iTS Management Programming Manual —426749-002

3-1

SPI Programming Considerations

After your subsystem and EMS processes are running and your management application has established communication with the Pathway subsystem, the main business of your management application is to format and send commands, decode responses and act on the results, and interpret event messages and act on their information.

This section provides summa ry in formati on abo ut SPI progr ammi ng and discusse s SPI programming considerations specific to the Pathway subsystem. Topics included are:

•

Definition Files

•

Message Elements for the Pathway Subsystem on page 3-4

•

Building and Sending a Command Message on page 3-19

•

Receiving and Decoding Response Messages on page 3-27

•

Event and Error Handling on page 3-28

•

Security on page 3-31

•

Retrieving and decoding event messages

•

Templates

•

Naming Guidelines for Applications on page 3-31

•

Programming Considerations for Specific Object Types on page 3-32

•

Writing C Programs on page 3-34

•

Command Presentation on page 3-35

For a complete list of all token codes and token maps specific to the Pathway subsystem, see the ZSPIDEF.ZPWYDDL file.

Definition Files

The commands, responses, and event messages sent to and received from the Pathway subsystem are made up of items called “tokens.” Each token contains a particular p i ece of info rma ti on, such as a com mand pa ram eter or an item of inform ation about an event. Tokens can be single values or structures consisting of several values. Some tokens, called “header tokens,” are present in every command and response and in every event message.

Tokens and related data items for commands, responses, and event messages must be declared in your management applications. HP provides these declarations for you in definition files. A set of definition files is provided as part of each HP NonStop subsystem that supports DSM. A few other NonStop software components (such as

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-2

Naming Conventions

SPI and EMS) also provide definition files. Each software component includes definition files for the TAL, COBOL, TACL, C, PASCAL, and DDL languages.

To use the data declarations defined by a particular NonStop software component, your application must incorporate the appropriate programming-language definition file associated with that software component. The declarations in a COBOL definition file are grouped into sections to enable COBOL programs to declare multiple copies of structures in the definition file. TAL programs can use as a source either the entire definition file or just the sections they require. The TACL command interpreter always loads the entire defini tion fil e. For fur ther infor mation about how definition fi les are u sed by an application, see the SPI Programming Manual.

Naming Conventions

Definition files are named according to the following convention:

subsys

is a three-character code identifying the subsystem or other software compon ent to which these definitions belong. The code for the Pathway subsystem is PWY.

The last characters of each file name denote the language in which the definitions in this file are coded.

Contents

The Pathway definition files contain the following definitions:

•

Object names for use in error tokens and object-selector tokens

•

Error tokens

•

Attribute (DEF-) tokens

•

Command-modifier (PAR-) tokens

•

Object-selector (SEL-) tokens

•

Qualifier (QUAL-) tokens

•

Commands

•

Object types

•

Token types, used in defining simple tokens

ZSPIDEF.ZsubsysC ZSPIDEF.ZsubsysCOB ZSPIDEF.ZsubsysDDL ZSPIDEF.ZsubsysPAS ZSPIDEF.ZsubsysTACL ZSPIDEF.ZsubsysTAL

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-3

Location

•

Token numbers, which uniquely identify each token

•

Token codes, used in defining simple tokens

•

Predefined values

•

Token maps, used to reference extensible structured tokens

•

Error numbers

•

Subsystem ID definition

•

Message buffer declaration

•

Event tokens

•

Building blocks, which are definitions that appear at the beginning of a definition file and are referenced by TYPE clauses that appear later in the file. Building blocks are present in ZPWYDDL, but are not generated for ZPWYC, ZPWYTAL, ZPWYCOB, or ZPWYTACL.

Location

The files are located on the disk volume chosen by your site. The default disk volume used by the Install program or the Distributed Systems Management/Software Configuration Manager (DSM/SCM) utility is $SYSTEM.

Which Files Do You Need?

An application that sends DSM commands to and receives responses from the Pathway subsystem needs the following definition files in the appropriate programming language:

SPI (ZSPI) definition file PWY (ZPWY) definition file

An application that retrieves event messages issued by the Pathway subsystem needs the following definition files:

SPI (ZSPI) definition file PWY (ZPWY) definition file EMS (ZEMS) definition file

For example, a management application written in COBOL that sends commands to and retrieves event messages issued by the Pathway subsystem would copy or load the following definition files:

ZSPIDEF.ZSPICOB ZSPIDEF.ZPWYCOB ZSPIDEF.ZEMSCOB

If your application manages subsystems other than Pathway, it also needs the definition files required by those subsystems. For instance, you might want your Pathway management application to manage an associated TMF subsystem as well. If

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-4

Message Elements for the Pathway Subsystem

you were writing the COBOL management application mentioned previously and also wanted to manage a TMF subsystem, you would need the following additional definition file:

ZSPIDEF.ZTMFCOB

For information about the SPI, EMS, extended SPI definitions, operating system, and file-system definitions, see the SPI Programming Manual, the EMS Manual, and the Guardian Procedure Errors and Messages Manual, respectively. The NonStop Pathway/iTS definitions are described in this manual.

Message Elements for the Pathway Subsystem

The following subsections provide subsystem-specific information about elements of Pathway/iTS commands, responses, and event messages. For general information about these elements, and for descriptions of elements whose meaning is not subsystem-specific (such as the subsystem ID), see the SPI Programming Manual.

Commands

Programmatic commands for the Pathway subsystem are identified by command numbers with symbolic names of the form ZPWY-CMD-name, where name identifies the command. For example, the name used by management application programs for the ALTER command is ZPWY-CMD-ALTER. These names represent the values that can be assigned to the command number header token, ZSPI-TKN-COMMAND.

The Pathway subsystem has its own set of command numbers, which are 16-bit integers represented in DDL by constants and in programs by TAL literals, COBOL level-01 variables, C pragmas, or TACL text variables. The command number is one of the tokens in the message header, which is a component of both command and response buffers.

For Pathway/iTS objects, the Pathway subsystem supports the programmatic commands listed in Table 3-1.

Note. Symbolic names are given in the DDL format, which is identical to th e C OBOL forma t. To des c ribe an obj ec t in TAL or TACL, replace hyph ens w it h c ircumflex characters (^).

Table 3-1. Pathway/iTS Programmatic Commands (page 1 of 2)

Command Meaning

ZPWY-CMD-ABORT Stops a suspended or running TERM object ZPWY-CMD-AD D Adds an object descri ption t o t he PATHMON confi guration

file

ZPWY-CMD-ALTER Changes an object’s configuration when the object is not

active

ZPWY-CMD-CONTROL Changes an object’s configuration while the objec t is

active

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-5

Commands

These commands and the Pathway subsystem’s responses to them are described in

Section 7, Terminal Control Process (TCP) Commands

; Section 8, TERM Commands;

Section 9, PROG Commands

; and Section 10, Tell Message Commands.

Table 3-2 on page 3-6 lists the TS/MP commands that also affect Pathway/iTS objects.

These commands are documented in the TS/MP Management Programming Manual.

ZPWY-CMD-DELETE Removes an object description from the PATHMON

configuration file if the object is not active ZPWY-CMD-GETVERSION Obtains the version of an object ZPWY-CMD-FREEZESTATUS Obtains the FREEZE status of a TERM that is preventing

a server from being frozen ZPWY-CMD-IN F O Obtains the configu ration of an objec t ZPWY-CMD-INSPECT Invokes the HP Inspect debugging tool to debu g a

SCRE EN C OBOL prog ram running on a Pat hway TERM

object ZPWY-CMD-REFRESHCODE Causes the TCP to check for the currently active version

of called SCREEN COBOL programs ZPWY-CMD-RESUM E Restarts ex ec ut ion of a SCREEN COBOL program th at

has been suspended with the SUSPEND command ZPWY-CMD-STATS Obtains resource usage and performance statistics for an

object ZPWY-CMD-STATUS Obtains the current status of an object or LINKMON

process ZPWY-CMD-STOP Stops an object if the comm a nd is used after certain

conditions are met ZPWY-CMD-SUSPEND Causes the TCP temporarily to suspend execution of a

SCRE EN C OBOL prog ram on a TERM object ZPWY-CMD-SWITCH Exchanges the function of an object’s primary process

with the function of its backup process ZPWY-CMD-TELL Displa y s a n operator-su pplied message on a TER M object

Table 3-1. Pathway/iTS Programmatic Commands (page 2 of 2)

Command Meaning

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-6

Object Types

All commands and responses contain an object-type token in the header. For the Pathway subsystem, object types are identified in programs by symbolic names of the form ZPWY-OBJ-name, where name identifies the object type. For example, the TCP object type is represented by the name ZPWY-OBJ-TCP. The object-type header token, ZSPI-TKN-OBJECT-TYPE, always has one of these names.

For Pathway/iTS commands, the Pathway subsystem supports the programmatic objects listed in Table 3-3.

Table 3-2. TS/MP Commands Affecting Pathway/iTS Objects

TS/MP Command Meaning

ZPWY-CMD-FREEZE

Prohibits all link managers (such as LINKMON processes or TCPs) from sending requests to a server class if the object is not active

ZPWY-CMD-SHUTD OWN2 Stops TERM and TCP objects during the Pathw ay

subsystem shutdown process

ZPWY-CMD-THAW

Allows link managers (such as LINKMON processes and TCPs) to send to the server class

Table 3-3. Pathway/iTS Object Types (page1of2)

Object Type Description TCP Objects

ZPWY-OBJ-TCP A definition for a te rm inal control p roc ess (TCP) that interprets

and exec ut es SCREEN C OBOL programs. TCPs co ordinate communication among SCREEN COBOL programs, the associated I/O devices or processes, and the server processes.

ZPWY-OBJ-TCPLINK A link between a TC P and a specific se rv er process in a s erv er

class.

ZPWY-OBJ-TCPSC A server class linked to a TCP. This object type is used with the

STATS command and ZPWY-VAL-ALLSC to obtain statistics on all server classes that have links to a single TCP.

ZPWY-OBJ-SCTCP A TCP linked to a server class.

TERM Objects

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-7

Object Types

Table 3-4 on page 3-8 lists the valid objects for each command. Commands that affect

Pathway/iTS objects are described in this manual. Commands that affect TS/MP objects are described in the TS/MP Management Programming Manual.

ZPWY-OBJ-TERM TERM objects represent tasks that control I/O devices such as

terminals or workstations, or that control processes that enable users to interoperate with a transaction-processing application. Each task runs as a thread in the TCP; the TCP can handle many such threads concurrently. There are two types: configured TERM objects and temporary TERM objects.

Configu red TERM objects are thos e y ou define and add to the PATHMON configuration file. These represent tasks that use SCREEN COBOL programs to control I/O devices or processes. The names you specify for configured TERM objects must begin with a letter.

Temporary TERM objects are created (and automatic all y deleted) by the PATHMON process in response to a START PROG co m m and, using the template you configu red as a PROG object. The PATHMON process assigns names

ZPWY-OBJ-TCPTERM A T ERM object running unde r th e c ontrol of a TCP. ZPWY-OBJ-SCTERM A TERM object that is preventing its associated server class

from being frozen.

PROGRAM Objects

ZPWY-OBJ-PROG A template used by the PATHMON process when creating and

starting temporary TERM objects. The templates define tasks that enab le T C Ps t o run screen prog rams temporarily on one or more devices. When the task is completed, the TERM object is automa ti ca lly deleted.

ZPWY-OBJ-PROGTERM A device type definition for a specific PROG.

TELL Objects

ZPWY-OBJ-TELL A tempor ary object that exis ts only for the duration of a tell

message.

Note: You cannot use commands on Pathway/iTS objects unless a licensed copy of the Pathway/iTS product exists on the system.

Table 3-3. Pathway/iTS Object Types (page2of2)

Object Type Description

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-8

Object Names

In the management programming interface to the Pathway subsystem, the form of an object name depends on the object type. Token Codes for Object Names on page 5-4 describes the name formats for objects of each type.

Object-Selector Tokens

Many Pathway commands and responses contain object-selector tokens that, when combined with object-type information, designate which objects are affected by the command. Object-selector tokens are represented by the name ZPWY-DDL-SELname, where name is the name of the specific object.

Table 3-4. Commands and Objects

Objects (ZPWY-OBJ- ) Commands (ZPWY-CMD- )

ABORT

ADD

ALTER

CONTROL

DELETE

FREEZE

FREEZESTATUS

GETVERSION

INFO

INSPECT

REFRESHCODE

RESUME

SHUTDOWN2

START

STATS

STATUS

STOP

SUSPEND

SWITCH

TELL

THAW

TS/MP

LM X PATHCTL

PATHWAY

X XXXXX

PM PMREQUESTER

XX X

SC SCASSIGN SCDEFINE SCLM SCPARAM SCPROCESS SCSTARTUP

X X X

X X

X X X

XXXX

Pathway/iTS

TCP TCPLINK TCPSC SCTCP

XXXX XX X XX

X X

XXXX

TERM SCTERM TCPTERM

XXXX X

XXXXXXXXXXXXXX

PROG PROGT ERM

XXX

X X

TELL X X X X

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-9

Event Numbers

All event messages cont ain a head er token ide ntifying the eve nt by numbe r. This event number, in combination with the subsystem ID header token, uniquely identifies the kind of event being reported. Event numbers for event messages defined by the Pathway subsystem are identified by symbolic names of the form ZPWY-EVT-name, where name gives a brief description of the event being reported.

In these event messages, the event-number header token (ZEMS-TKNEVENTNUMBER) can have any one of the set of event numbers for the Pathway subsystem. Messages returned by TCPs are described in Sections 11 and 12; messages returned to TCPs or terminals from TS/MP components, are described in the TS/MP Management Programming Manual.

Other Tokens

Commands, responses, and event messages for the Pathway subsystem, like those for other subsystems, also include other tokens, providing further information.

Comment Token

ZSPI-TKN-COMMENT is a token that a requester can use to include arbitrary information of its own in a command. Pathway, like other HP subsystems for NonStop systems, does not use this token and does not return it in responses.

Buffer sizes recommended by HP subsystems allow for one 80-byte comment token in every command. ZSPI-TKN-COMMENT is currently useful only within NonStop software for NonStop systems.

Context Token

The ZSPI-TKN-CONTEXT data token facilitates referencing more than one object with a single command. This token is returned in the response if you specify a constant (that is, ZPWY-VAL-ALLobjectname) in the object-selector token and there are more objects to be processed. To continue the command for additional objects, your management application must copy ZSPI-TKN-CONTEXT into a duplicate of the original command message and resubmit the command message.

For more information on continuation, see Specifying Continuation on page 3-21.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-10

Extensible Structured Tokens

The following is a sample DDL definition for an extensible structured token that defines the attributes for a program. The TAL, COBOL, TACL, PA SCAL, and C code generated follows the DDL definition.

DDL definition for ZPWY-DDL-DEF-PROG:

Note. The TAL, COB OL, TACL, an d C c odes redefin e each characte r f ield (Z^C and Z- C in the examples ) as an integer array and as an array of individual bytes to ac c om modate certai n HP NonStop operating system procedures. For clarity, the redefinitions have been removed from the example.

def ZPWY-DDL-DEF-PROG. 02 ZERRORABORT type ZPWY-DDL-ON-OFF. 02 ZOWNER type ZPWY-DDL-OWNER-ID. 02 ZPRINTERINFO. 03 ZISATTACHED type ZPWY-DDL-YES-NO. 03 ZPRINTERFILE type ZSPI-DDL-FNAME32. 02 ZSECURITY type ZPWY-DDL-SECURITY-VALUE. 02 ZTCP type ZPWY-DDL-OBJECT-NAME. 02 FILLER type ZPWY-DDL-FILLER. 02 ZTMF type ZPWY-DDL-ON-OFF. end.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-11

Extensible Structured Tokens

Corresponding TAL structure for ZPWY-DDL-DEF-PROG:

STRUCT ZPWY^DDL^DEF^PROG^DEF (*); BEGIN INT ZERRORABORT; STRUCT ZOWNER; BEGIN INT ZSYSTEMNUMBER; INT ZGROUPNUMBER; INT ZUSERNUMBER; END; STRUCT ZPRINTERINFO; BEGIN INT ZISATTACHED; STRUCT ZPRINTERFILE; BEGIN STRUCT Z^SYSNAME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; STRUCT Z^LOCALNAME; BEGIN STRUCT Z^DISC; BEGIN STRUCT Z^VOLUME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; STRUCT Z^SUBVOLUME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; STRUCT Z^FILENAME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; END; STRUCT Z^PROCESS = Z^DISC; BEGIN STRUCT Z^CRTPID; BEGIN STRUCT Z^PROCNAME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:5]; END; END; INT Z^CRT[0:2] = Z^PROCNAME;

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-12

Extensible Structured Tokens

TAL structure for ZPWY-DDL-DEF-PROG (continued):

STRUCT Z^PID; BEGIN STRING Z^CPU; STRING Z^PIN; END; INT Z^CPUPIN = Z^PID; END; STRUCT Z^QUAL1; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; STRUCT Z^QUAL2; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; END; STRUCT Z^DEVICE = Z^DISC; BEGIN STRUCT Z^DEVNAME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; STRUCT Z^SUBDEVNAME; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:7]; END; END; STRUCT Z^FILLER; BEGIN STRING BYTE [0:7]; END; END; END; END; END; INT ZSECURITY; STRUCT ZTCP; BEGIN STRUCT Z^C; BEGIN STRING BYTE [0:14]; END; END; FILLER 1; INT ZTMF; END;

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-13

Extensible Structured Tokens

Corresponding COBOL level-01 variable for ZPWY-DDL-DEF-PROG:

01 ZPWY-DDL-DEF-PROG. 02 ZERRORABORT PIC X(2). 02 ZOWNER. 03 ZSYSTEMNUMBER NATIVE-2. 03 ZGROUPNUMBER NATIVE-2. 03 ZUSERNUMBER NATIVE-2. 02 ZPRINTERINFO. 03 ZISATTACHED PIC X(2). 03 ZPRINTERFILE. 04 Z-SYSNAME. 05 Z-C PIC X(8). 04 Z-LOCALNAME. 05 Z-DISC. 06 Z-VOLUME. 07 Z-C PIC X(8). 06 Z-SUBVOLUME. 07 Z-C PIC X(8). 06 Z-FILENAME. 07 Z-C PIC X(8). 05 Z-PROCESS REDEFINES Z-DISC. 06 Z-CRTPID. 07 Z-PROCNAME. 08 Z-C PIC X(6). 07 Z-CRT REDEFINES Z-PROCNAME NATIVE-2 Occurs 3 TIMES. 07 Z-PID. 08 Z-CPU PIC X(1). 08 Z-PIN PIC X(1). 07 Z-CPUPIN REDEFINES Z-PID NATIVE-2. 06 Z-QUAL1. 07 Z-C PIC X(8). 06 Z-QUAL2. 07 Z-C PIC X(8). 05 Z-DEVICE REDEFINES Z-DISC. 06 Z-DEVNAME. 07 Z-C PIC X(8). 06 Z-SUBDEVNAME. 07 Z-C PIC X(8). 06 Z-FILLER PIC X(8). 02 ZSECURITY PIC S9(4) COMP. 02 ZTCP. 03 Z-C PIC X(15). 04 FILLER PIC X. 02 FILLER PIC X. 02 ZTMF PIC X(2).

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-14

Extensible Structured Tokens

Corresponding TACL structure variable for ZPWY-DDL-DEF-PROG:

Corresponding C pragma for ZPWY-DDL-DEF-PROG:

ZPWY^DDL^DEF^PROG Struct Begin BOOL ZERRORABORT; STRUCT ZOWNER; Begin INT ZSYSTEMNUMBER; INT ZGROUPNUMBER; INT ZUSERNUMBER; End; STRUCT ZPRINTERINFO; Begin BOOL ZISATTACHED; FNAME32 ZPRINTERFILE; End; ENUM ZSECURITY; STRUCT ZTCP; Begin STRUCT Z^C; BEGIN CHAR BYTE(0:14); END; End; FILLER 1; BOOL ZTMF; End;

#pragma fieldalign matched2 __zpwy_ddl_def_prog typedef struct __zpwy_ddl_def_prog { short zerrorabort; struct { short zsystemnumber; short zgroupnumber; short zusernumber; } zowner; struct { short zisattached; struct { struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8];

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-15

Extensible Structured Tokens

C pragma for ZPWY-DDL-DEF-PROG (continued):

} u_z_c; } z_sysname; struct { union { struct { struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_volume; struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_subvolume; struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_filename; } z_disc; struct { struct { union {

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-16

Extensible Structured Tokens

C pragma for ZPWY-DDL-DEF-PROG (continued):

struct { union { char z_c[6]; struct { short z_i[3]; } z_s; char z_b[6] } u_z_c; } z_procname; short z_crt[3]; } u_z_procname; union { struct { char z_cpu; char z_pin; } z_pid; unsigned short z_cpupin; } u_z_pid; } z_crtpid; struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_qual1; struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_qual2; } z_process; struct {

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-17

Types for Fields in Structured Tokens

C pragma for ZPWY-DDL-DEF-PROG (continued):

Types for Fields in Structured Tokens

Many token types are built on more elementary types that are defined in the DDL before the extensible structured token is defined.

struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_devname; struct { union { char z_c[8]; struct { short z_i[4]; } z_s; char z_b[8]; } u_z_c; } z_subdevname; char z_filler[8]; } z_device; } u_z_disc; } z_localname; } zprinterfile; } zprinterinfo; short zsecurity; struct { union { char z_c[15]; struct { short z_i[7]; char filler_0; } z_s; char z_b[15]; } u_z_c; } ztcp; char filler_1; short ztmf; } zpwy_ddl_def_prog_def;

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-18

Data Lists and Error Lists

For example, the command-modifier token ZPWY-DDL-PAR-CONTROL-TCP has the following DDL definition:

Within ZPWY-DDL-PAR-CONTROL-TCP, the ZBACKUPCPU field has the type ZPWY-DDL-CPU. ZPWY-DDL-CPU is defined earlier in the Pathway DDL definitions file (ZPWYDDL) as follows:

To further expand the definition, look up ZSPI-DDL-INT in the SPI definitions file (ZSPIDDL). The definition for ZSPI-DDL-INT is as follows:

Consequently, ZBACKUPCPU is a 16-bit integer. ZDUMPFILE has the SPI type ZSPI-DDL-FNAME32. The definition for

ZSPI-DDL-FNAME32 in the ZSPIDDL file is as follows:

Previously in the ZSPIDDL file, ZSPI-DDL-CHAR8 is defined as eight ASCII characters. ZSPI-DDL-FNAME is defined as a Guardian internal format file name, including disk name, process name, and device name.

Throughout this manual, the type of a field is indicated wherever the field is described. Definitions for Pathway subsystem private token and field types are in Section 5,

ZPWY-DDL- Definitions, and Section 6, ZPWY-MAP- Definitions. The type names

defined by SPI (using the prefix ZSPI- ) are fully described in the SPI Programming Manual.

Data Lists and Error Lists

Responses from the Pathway subsystem can contain data lists and error lists, as described in the SPI Programming Manual.

The Pathway subsystem does not support arrays or multiple instances of tokens. The PATHMON process never returns more than one response in a message; however, the single response can be enclosed in a data list for consistency with other

def ZPWY-DDL-PAR-CONTROL-TCP. 02 ZBACKUPCPU token-type ZPWY-DDL-CPU. 02 ZDUMPINFO. 03 ZDUMP token-type ZPWY-DDL-ON-OFF. 03 ZDUMPFILE token-type ZSPI-DDL-FNAME32. 02 ZSTATS token-type ZPWY-DDL-ON-OFF. end.

def ZPWY-DDL-CPU token-type ZSPI-DDL-INT.

def ZSPI-DDL-INT token-type BINARY 16.

def ZSPI-DDL-FNAME32. 02 Z-SYSNAME token-type ZSPI-DDL-CHAR8. 02 Z-LOCALNAME token-type ZSPI-DDL-FNAME. end.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-19

Building and Sending a Command Message

subsystems if you include the ZSPI-TKN-MAXRESP token with a value not equal to zero.

Building and Sending a Command Message

The following subsections summarize the steps your application must take to create and send SPI commands. These summaries are followed by subsystem-specific programming considerations for the Pathway subsystem.

For more information on creating and sending SPI commands and responses, see the SPI Programming Manual.

Summary of Steps

The following is a summary of the steps your application must take to build and send a command message to the Pathway subsystem:

1. Declare a buffer of appropriate size. The constant ZPWY-VAL-BUFLEN designates the buffer length you should use for Pathway requests.

2. Call the SSINIT procedure to initialize the command buffer. SSINIT sets the values of certain header tokens, including the command, the object type, and the target subsystem ID.

3. Call SSNULL to initialize each extensible structured token to be used in the command.

4. Call SSPUT or SSPUTTKN to place the appropriate tokens in the buffer.

5. If you are resending a comm and to r etrie ve the ne xt respo nse me ssage i n a se ries, call SSMOVE or SSMOVETKN to move the context token from the previous response buffer into the command buffer.

6. Send the command message using the mechanism appropriate to your programming language (for example, a WRITEREAD call in TA L, a READ WITH PROMPT verb in COBOL, or a #INPUTV or #OUTPUTV built-in function in TACL).

Note. Always initialize an extensible struc tu red token that is to appear in a command by using the SPI pro c edure SSNU LL. This proce dure ensures th at every field of the toke n is init ialized to its null value. Initializing each fie ld t o a null value is important be cause an operation will be performe d if a fi eld contains a valu e ot her than its null value. For examp le, in th e ALTER TCP command, if a field of the extensible struct ured token that des c ribes the TC P attributes contains a val ue other than its null valu e, that value is assigned to the attr ibut e c orresponding to th a t field.

Using SSNULL is important even when your application assigns a value to every field of an extensible struc t ured token. Oth erw is e, th e application w ill not work corr ec t ly lat er if it is compiled w it h a new version of the definition files tha t add new fields to th e t oke n.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-20

Considerations for SSINIT

When setting up a call to SSINIT, you need to consider the following information.

Using ZSP I -TKN-MAXRESP

ZSPI-TKN-MAXRESP is used by some subsystems to enable multiple responses in a single response buffer. Because the Pathway subsystem does not support multiple responses in a single response buffer, ZSPI-TKN-MAXRESP is only useful if your management application must handle all subsystems in a consistent manner; that is, if Pathway responses must be enclosed in data lists. To reference the Pathway subsystem alone, it is not necessary to specify ZSPI-TKN-MAXRESP.

You can include ZSPI-TKN-MAXRESP by using SSINIT or SSPUT. If you do not include this token in the command message or you include it but set the value to zero, the PATHMON process returns a single response. If you include ZSPI-TKN-MAXRESP and assign a nonzero value, the PATHMON process returns a single response and encloses that response in a data list. (The ZSPI-TKN-DATALIST token precedes the response, and the ZSPI-TKN-ENDLIST token follows the response.)

Declaring the Pathway Subsystem ID

The Pathway subsystem ID is expressed by the value ZPWY-VAL-SSID, defined in Section 4, “SPI and EMS Standard Definitions,” in the T S/M P Manageme nt Programming Manual.

These declarations produce an appropriately initialized structure for COBOL. For TAL, TACL, and C, your program must initialize the structure explicitly, as follows:

For TAL:

ZPWY^VAL^SSID.Z^OWNER.Z^B ':=' [ ZSPI^VAL^TANDEM ]; ZPWY^VAL^SSID.Z^NUMBER := ZSPI^SSN^ZPWY; ZPWY^VAL^SSID.Z^VERSION := ZPWY^VAL^VERSION;

For TACL:

#SET ZPWY^VAL^SSID & [ZSPI^VAL^TANDEM].[ZSPI^SSN^ZPWY].[ZPWY^VAL^VERSION]

For C:

zpwy_val_ssid_def zpwy_val_ssid ={ ZSPI_VAL_TANDEM, ZSPI_SSN_ZPWY ZPWY_VAL_VERSION };

or #include stringb strcopy ( zpwy_val_ssid.z_owner, ZSPI_VAL_TANDEM };

strcopy ( zpwy_val_ssid.z_number = ZSPI_SSN_ZPWY }; strcopy ( zpwy_val_ssid.z_version = ZPWY_VAL_VERSION };

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-21

Considerations for SSPUT

The Pathway subsystem does not support multiple commands in the same message, or arrays or multiple occurrences of the same token.

Considerations for SSNULL and Extensible Structured Tokens

Your program should always call SSNULL to initialize an extensible structured token before assigning values to fields in that token, even if you assign a value to each field and even if the extensible structured token has only one field. Using SSNULL allows your program to accommodate future expansion in the extensible structured tokens.

Null Values and Defaults

You can set all of the fields in any of the Pathway extensible structured tokens to null values by calling SSNULL. In an ADD command, required fields containing the null value cause the PATHMON process to return an error. Fields that are not required and that contain a null value take on their default values when sent with an ADD command. Any field can be null in an ALTER command; the null value means no change.

Issuing an INFO command with a null object-selector (SEL-) token returns the default values for an object’s attributes—the object-selector token is returned with null values in each required field and default values in each optional field. Consequently, it is not necessary for the program to determine either the PATHMON process’s null values or its defaults.

Specifying Continuation

Because the Pathway subsystem does not support multiple responses per response buffer, your management application must use continuation if you want to change or query a series of objects or subobjects with a single command. Continuation allows your management application to resubmit a command repeatedly until all objects or subobjects in a series have been accessed. The Pathway subsystem supports response continuation for some commands but always returns only a single response per response buffer.

Continuation, therefore, is helpful to use when you want to perform the following:

•

Affect, query, or control more than one object or subobject

•

Query a specific object or subobject when you do not have its name or when its name has changed

Continuation Pro c e dure

To specify continuation for commands that support it, your program must:

1. Call the SSINIT procedure, specifying the appropriate command (ZPWY-CMD- ) and object (ZPWY-OBJ- ).

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-22

Specifying Continuation

2. Initialize the ZNAME field in the ZPWY-DDL-SEL-objecttype token by assigning a value in the form ZPWY-VA L-ALLobjecttype to the field. The values are described under Values for Specifying Continuation on page 3-22.

3. Put the selector token and any other needed tokens in the command buffer using SSPUT.

4. Issue the command for the first time. Upon completion of the command, move the context token (that is, ZSPI-TKN-CONTEXT) that was returned by the PATHMON process in the response buffer to the command buffer, using SSMOVE.

5. Reissue the command repeatedly, returning the context token that is returned by the PATHMON process each time your program resubmits the command. Your program must keep issuing the command and returning the context token until a context token is no longer returned and the Pathway subsystem returns the error ZPWY-ERR-PM-NODATA.

End of Continuation

The Pathway subsystem management programming interface is designed to return a context token during continuation whenever there is a response in the response buffer. As a result, the Pathway subsystem always returns an empty response for the last record of a continuation. The value ZPWY-ERR-PM-NODATA denotes an empty response buffer, as well as the end of the response continuation dialog.

You must code your management application to expect and interpret ZPWY-ERR-PM-NODATA during response continuation; this token is the final indication of the end of continuation.

Values for Speci fy ing Continuation

The following tokens represent the predefined values assigned to Pathway/iTS object name fields in object-selector tokens:

These values have the same meaning as the asterisk (*) used in the PATHCOM commands. For example, to implement the PATHCOM INFO TERM * command, you use the predefined value ZPWY-VAL-ALLTERM in the object-selector token ZPWY-DDL-SEL-TERM.

Note. Whe n t he value you assign to t he name field is longer than th e name field its elf, do not move the en ti re lit eral to the name f ield. Instead , move on ly w hat is needed of the literal.

Predefined Value Definition

ZPWY-VA L-ALLPROG Multiple P R OG objects ZPWY-VA L-ALLTCP Multiple TC P objects ZPWY-VAL-ALLTELL Multiple tell messages ZPWY-VAL-ALLTERM Multiple TERM objects ZPWY-VAL-ALLTERMTYPE Multiple device types

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-23

Required Object States for Continuation

For each type of command, continuation only acts on objects in a specific state. If an object is not in the required state, responses might not be returned for all objects or subobjects requested. Table 3-5 indicates the required state for each Pathway subsystem command t hat sup port s continua tion an d ea ch obje c t type applicable to th at command.

Table 3-5. Required Object States for Continuation (page 1 of 2)

Command Object Type Required Object State

ABORT TCPTERM

TERM

TERM running or susp ended; TCP runn ing or suspend ed

DELETE PROG

PROGTERM TCP TCPTERM TERM

Stopped Stopped Stopped TERM stopped; TCP running Stopped

FREEZESTATUS SCTERM TERM linked to th e s pecified SC ; TERM preventing

the freezing of specifie d SC GETVERSION TCP Running INFO PROG

PROGTERM TCP TCPTERM TELL TERM

Any state

Any state REFRESHCODE TCP Running, ZCHECKDIRECTORY field defined as

ZPWY-VAL-OFF RESUME TCPTERM

TERM

TERM su sp ended; TCP running

Suspended START TCP

TCPTERM TERM

Stopped

TERM stopped; TCP running

Stopped STATS TCP

TCPSC SCTCP

TCPTERM TERM

Running

SC running and linked t o s pecified TCP

TCP running and linked to specified SC

TCP set to STATS ON

TERM running; TCP running

Running STATUS TCP

TCPLINK TCPTERM TERM

Any state

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-24

Continuation Example

The following steps describe what occurs when a management application obtains information about the TERM objects named TERM-A, TERM-B, and TERM-C:

STOP TCP

TCPTERM TERM

Running

TERM running; TCP running

Running SUSPEND TCPTERM

TERM

TERM running; TCP running

Running SWITCH TCP Running

The Application… The PATHMON Process…

1. Specifies ZPWY-CMD-INFO and

ZPWY-OBJ-TERM with the SSINIT call.

2. Assigns the constant ZPWY-VAL-

ALLTERM to the ZTERM field in ZPWY-DDL-SEL-TERM.

3. Adds ZPWY-DDL-SEL-TERM to the

command message using SSPUT.

4. Issues the command INFO TERM.

5. Returns the name of TERM-A and a context token.

6. Reissues the INFO TERM command with the speci al select or and adds the context token from the previous response to the message.

7. Returns the name of TERM-B and a context token.

8. Reissues the INFO TERM command with the speci al select or and adds the context token from the previous response to the message.

9. Returns the name of TERM-C and a context token.

Table 3-5. Required Object States for Continuation (page 2 of 2)

Command Object Type Required Object State

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-25

32-Byte File Names

Some commands require that you send a file name to the PATHMON process through the SPI interface. A 32-byte field is required to represent file names for DSM, rather than the 24-byte field that is typically used for this purpose.

Whenever you assign a file name to a field, you must supply the file name as follows:

•

Bytes 0 through 7 contain the name of the system that hosts the file. The name must include the leading backslash character (\) and be left-justified with filler tokens (ZPWY-DDL-FILLER).

If the system is not part of a network and is not named, bytes 0 through 7 contain the backslash character (\) followed by seven blank characters.

•

Bytes 8 through 31 contain the file name in local internal form.

Example 3-1 gives examples of acceptable formats for file names:

The following procedures are provided in the system library for handling file names in this format:

10. Reissues the INFO TERM command with the speci al select or and adds the context token from the previous response to the message.

11. Returns an empty response buffer (the context token is absent) and the error value ZPWY-ERR-PMNODATA.

12. Interprets that there are no more TERM objects about which to obtain information.

Example 3-1. Format for 32-Byte File Names

File Name 32-Byte Format Byte

# 0....5....10...15...20...25....31

\A.$B "\A $B " \A.$B.#C "\A $B #C " \A.$B.#C.D "\A $B #C D " \W.$X.Y.Z "\W $X Y Z "

The Application… The PATHMON Process…

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-26

Resetting Values in Fields

•

FNAME32COLLAPSE, similar to the system procedure FNAMECOLLAPSE, converts 32-byte file names to external format.

•

FNAME32EXPAND, like the system procedure FNAMEEXPAND, converts file names in external format to 32-byte internal format.

•

FNAME32TOFNAME converts a file name from 32-byte format to Guardian internal format, if possible.

•

FNAMETOFNAME32 converts a file name from Guardian internal format to 32-byte format, if possible.

Resetting Values in Fields

Certain constants can be used with an ALTER command to reset any optional field in an extensible structured token to its default value. A reset constant causes the PATHMON process to return an error if the field represents a required parameter and to reset the attribute to its default value if the field represents an optional parameter.

The Pathway subsystem reset constants are listed in Table 3-6.

Resetting Fields With the TA CL Prog ram

To reset fields of type FNAME32, CRTPID, or SUBVOL with the TACL program, you must use the #SETBYTES built-in function. More information on resetting fields with the #SETBYTES built-in function is available in the SPI Progra mmi ng Manual.

Table 3-6. Reset Constants

This Constant… Resets…

ZPWY-VAL-RESETALPHABYTE An alphanumeric byte ZPWY-VAL-RESETALPHAINT An alphanumeric word ZPWY-VAL-R ESETBOOL EANBYTE A Boolean byt e ZPWY-VAL-R ESETBOOL EANINT A Bo olean wor d ZPWY-VAL-RESETNUMERICBYTE A numeric byte ZPWY-VAL- RESETNUMER I C INT A numeric wo rd ZPWY-VAL-R ESETNUMER I C INT2 A numeric doubleword ZPWY-VAL-R ESETNUMER I C INT4 A numeric quadruplewo rd ZPWY-VAL- RESETFNAME32 A 32-byt e fiel d ZPWY-VA L-R ESETCRTP I D A field con tai ning a process I D ZPWY-VAL-R ESETOB J EC T NAME A field containing an object name ZPWY-VA L-R ESETSU BVOL A field con tai ning a subvolu m e name

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-27

Receiving and Decoding Response Messages

The following subsections summarize the steps your application must take to receive and decode SPI command responses. These summaries are followed by subsystemspecific programming considerations for the Pathway subsystem.

For more information on receiving and decoding SPI commands and responses, see the SPI Programming Manual.

Summary of Steps

The following is a summary of the steps your application must take to receive and decode a response message:

1. Declare a buffer of appropriate size.

2. Read the response message by using the mechanism appropriate to your programming language (for example, a WRITEREAD call in TA L).

3. Call SSGET or SSGETTKN to retrieve the values of header tokens and other tokens from the buffer.

4. On encountering the data-list token (ZSPI-TKN-DATALIST) or the error-list token (ZSPI-TKN-ERRLIST), make another call to SSGET or SSGETTKN to retrieve the tokens inside the data list, including the error list if one exists.

5. On encountering a context token (ZSPI-TKN-CONTEXT), finish reading the other tokens in the buffer. Then, optionally, use SSMOVE or SSMOVETKN to copy the context token into the command buffer, and resend the command to get the next message in the response.

The Pathway subsystem can return an empty response if an application returns a ZSPI-TKN-CONTEXT token and there are no more responses to be returned. The return token ZSPI-TKN-RETCODE in the returned response always has the value ZPWY-ERR-PM-EOF.

6. Take action appropriate to the information in the response.

Considerations

The response buffer always contains the return token, ZSPI-TKN-RETCODE. The value of the ZSPI-TKN-R ETCOD E token i s either zero (to indi cate that the comman d is successful), or it is a nonzero error number (to indicate that the command was not performed). The command can contain error lists in either case.

Although the Pathway subsystem generates responses for all commands, responses from some commands (such as INFO TCP and STATUS TCP) must be obtained from fields within an extensible structured token. For example, the extensible structured token in the INFO TCP or STATUS TCP command contains all of the information about TCPs that is available from the PATHMON process. To see a field within an extensible

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-28

Event and Error Handling

structured token, you must first obtain the entire structured token by using SSGET. Then refer to the fields of the structure by using the defined field names.

The PATHMON process does not provide support for selecting the types of responses to be returned with the SPI standard token ZSPI-TKN-RESPONSE-TYPE. The Pathway subsystem always returns a response for every object—whether or not errors or warnings occur for the object. For more information on sending messages and receiving the responses, see the SPI Programming Manual.

Event and Error Handling

Each response returned by the Pathway subsystem includes a return token (ZSPITKN-RETCODE), whose value indicates whether an error occurred when the PATHMON process attem pted to perfor m the comma nd. An error is a serious conditio n that prevents the command from being completed. If the command completes with no errors, the value of the return token is zero. If ZSPI-TKN-RETCODE has any nonzero value, this means that an error occurred. In this case, the PATHMON process includes an error list in the response, providing information about the error.

A warning reports a condition less serious than that of an error. If no errors occur but a warning occurs, the return token has a value of zero, but an error list appears in the response, providing information about the warning condition.

An error list, which always begins with the token ZSPI-TKN-ERRLIST and ends with the token ZSPI-TKN-ENDLIST, is returned only if an error or warning is detected. The information in the list becomes accessible when your program calls SSGET to select ZSPI-TKN-ERRLIST. Although the Pathway subsystem only returns one error list per response, there can be nested error messages.

The PATHMON process does not support ZSPI-TKN-ALLOW-TYPE. The SPI standard token ZSPI-TKN-RETCODE contains a nonzero value if the PATHMON process detects an error in a command message or detects an error when attempting to perform a command. The Pathway subsystem can also return file-system errors.

Event Message Subject Tokens

ZEMS-TKN-SUBJECT-MARK indicates the subject token, which identifies the Pathway subsystem object or file that is most directly involved in the event. The subject token indicates one of the tokens listed in Table 3-7 as present in the event-message buffer:

Table 3-7. Event Message Subject Tokens

Token Description

ZPWY-TKN-FNAME Event con c erns a file. ZPWY-TKN-PMNAME Event concerns the PATHMON process. ZPWY-TKN-PROGNAME Event concerns a terminal template (PROG object). ZPWY-TKN-TCPNAM E Event concerns a term inal control proc ess (TCP).

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-29

Event-Specific Tokens

The subject token indicated by ZEMS-TKN-SUBJECT-MARK contains the name of the specific object involved in the event. For example, if an event message reports an event involving a TCP named TCP-8, ZEMS-TKN-SUBJECT-MARK indicates the subject token ZPWY-TKN-TCPNAME, whose contents is the name TCP-8.

Event-Specific Tokens

Table 3-8 lists event-specific Pathway subsystem EMS tokens. These tokens are

called “program unit location tokens” because they describe the part of a SCREEN COBOL program unit that was executing when an error was detected. These conditional tokens appear in some Pathway subsystem event messages.

Error Messages

Most Pathway subsystem errors reported to a management application are returned in the response buffer the application receives from the PATHMON process. Pathway subsystem errors reported to SPI requesters are returned in one of the following:

•

In the response buffer for a STATUS TCP or STATUS TERM command (as a number in the ZERROR field of ZPWY-DDL-STATUS-TCP or ZPWY-DDL-STATUS-TERMDETA IL)

•

As a number in the ZSPI-TKN-RETCODE token, which is always returned in the response buffer

•

In an error list, which is a compo nent of a respo nse buf fer that is return ed onl y if an error is detected

ZPWY-TKN-TELLNAME Event concerns a tell message. ZPWY-TKN-TERMNAME Event concerns a terminal (TERM object). ZPWY-TKN-UNKNOWNNAME The subject of the event is unknown to PATHMON.

Table 3-8. Event-Specific Pathway EMS Tokens

Token Description

ZPWY-TKN-INSTRUCTION Describes a SCREEN COBOL instruction. ZPWY-TKN-PUNAME Describes a SCREEN COBOL program unit. ZPWY-TKN-PUOFFSET Contains an offset in to a SC R EEN COBOL progra m

unit. ZPWY-TKN-PUVERSION Describes a SCREEN COBOL program unit version. ZPWY-TKN-TCLPROGFNAME Contains the name of the SCREEN COBOL object file in

Distributed Name Service (DNS) format.

Table 3-7. Event Message Subject Tokens

Token Description

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-30

Message Numbers

Scenario

Your management application issues the START TCP command for TCP-A, but the buffer is corrupted. The response message contains the following:

1. The message header, including the command (ZPWY-CMD-START), the object type (ZPWY-OBJ-TCP), the version of the PATHMON process, and the subsystem ID

2. ZSPI-TKN-RETCODE, containing the value ZPWY-ERR-SPI-INVALIDBUFFER

3. ZSPI-TKN-ERRLIST

4. ZSPI-TKN-ERROR, indicating the Pathway subsystem ID and the value ZPWY-ERR-SPI-INVALIDBUFFER

5. ZPWY-TKN-REQCOMMAND, containing the value ZSPI-TKN-NULL-COMMAND

6. ZPWY-TKN-REQOBJECTTYPE, containing the value ZSPI-TKN-NULL-OBJECTTYPE

7. ZSPI-TKN-ENDLIST

Message Numbers

Message numbers returned by the Pathway subsystem are in the following ranges:

Error messages with a value of 0 indicate that the command completed successfully (ZPWY-VAL-OK).

For more information on errors, error lists, and nested error messages, see the TS/MP Management Programming Manual. For more information about ZSPI-TKN-ERRLIST and ZSPI-TKN-ENDLIST, see the SPI Programming Manual.

Messag e Numb ers in This Range… Are Generated by… With The Tokens…

1000 through 1999 PATHMON

Although some messages generated by the PATHMON process pertain to Pathway/iTS objects, all messages in this range are describe d in t he TS/MP Management Programming Manual.

ZPWY-EVT-PMZPWY-ERR-PM-

3000 through 3999 TCPs (Although only the TCP can generate

an error message, LINKMON processes are the subjects of some messages.)

These messages are described in this manual.

ZPWY-EVT-TCPZPWY-ERR-TCP-

4000 through 4999 SPI (Subsystem Programmatic Interface)

These messages are described in the TS/MP Management Programming Manual.

ZPWY-ERR-SPI-

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-31

Security

The owner of the user ID that starts the PATHMON process can set the ZOWNER and ZSECURITY fields in ZPWY-DDL-DEF-PATHWAY during the execution of a START PATHWAY command to restrict the use of a specific group of commands. Commands included in this restricted group are those that can directly alter the state of an object.

Table 3-9 lists the restricted commands and their object types.

Any user can issue all of the other commands.

Naming Guidelines for Applications

By convention, HP uses names beginning with the letter Z (lowercase z in the C language) for all definitions and all component fields of structures in its definition files on NonStop systems. To avoid conflicts with names defined by HP, it is best not to begin any of your own names with uppercase or lowercase Z.

Table 3-9. Restricted Commands and Objects for Pathway/iTS

To Control…

Use These Restricted (Sensitive) Commands (ZPWY-CMD- ) and Object Types (ZPWY-OBJ- )…

TCP objects ADD TCP

ALTER TCP CONTROL TCP REFRESHCODE TCP STOP TCP SWITCH TCP

TERM objects ABORT TERM

ADD TERM ALTER TERM DELETE TERM INSPECT TERM RESUME TERM START TERM STOP TERM SUSPEND TERM

PROG objects ADD PROG

PROGTERM

ALTER PROG

PROGTERM

DELETE PROG

PROGTERM

Tell Messages ADD TELL

DELETE TELL START TELL TELL TELL

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-32

Programming Considerations for Specific Object

Types

Programming Considerations for Specific Object Types

The following paragraphs discuss special programming considerations for each Pathway/iTS object type.

TCP Objects

When developing a management application that defines and controls TCPs, consider the following:

•

To perform the equivalent of the PATHCOM STATS TCP, DETAIL command, follow these steps:

1. Issue the STATS TCP command, initializing the ZTCP field in

ZPWY-DDL-SEL-TCP to the TCP name.

2. Issue the STATS TCPSC command, initializing the ZTCP field in

ZPWY-DDL-SEL-TCPSC to the TCP name and initializing the ZSERVERCLASS field to ZPWY-VAL-AL LSC. Reissue the STATS TCPSC command repeatedly, using the context token returned by PATHMON, until no data is returned in the reply buffer.

3. Issue the STATS TCP command, initializing the ZTCP field in

ZPWY-DDL-SEL-TCP to ZPWY-VAL-ALLTCP. Reissue the STATS TCP command repeatedly, using the context token returned by PATHMON, until no data is returned in the reply buffer.

4. Issue the STATS TCPTERM command, initializing the ZTCP field in

ZPWY-DDL-SEL-TCPTERM to the TCP name identified in Step 1, and initializing the ZTERM field to ZPWY-VAL-ALLTERM. Reissue the STATS TCPTERM command repeatedly, using the context token returned by PATHMON, until no data is returned in the reply buffer.

•

To perform the equivalent of the PATHCOM PRIMARY TCP command, follow these steps:

1. Use LOOKUPPROCESSNAME to find the processor in which the TCP is

actually running.

2. Use INFO TCP to determine the TCP’s configured processor.

3. Use SWITCH TCP and CONTROL TCP to move the TCP’s primary process

back to the configured processor. The last command in the sequence should be a CONTROL TCP command so that the changes are recorded in the PATHCTL file.

•

To perform the equivalent of the PATHCOM STATUS TCP, DETAIL command, follow these steps:

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-33

TERM Objects

1. Issue the STATUS TCP command, initializing the ZTCP field in

ZPWY-DDL-SEL-TCP to the TCP name.

2. Issue the STATUS TCPTERM command, initializing the ZTCP field in

ZPWY-DDL-SEL-TCPTERM to the TCP name and initializing the ZTERM field to ZPWY-VAL-ALLTERM.

3. Reissue the STATUS TCPTERM command continually, using the context

token returned by PATHMON, until no data is returned in the reply buffer.

TERM Objects

When developing a management application that defines and manages TERM objects, consider the following:

•

Most TERM commands in SPI are very similar in function to the TERM commands in the PATHCOM interface. The exceptions are the TELL commands. For more information, see Tell Messages on page 3-33.

PROG Objects

When developi ng a m anag emen t applic at ion that defi ne s and m anage s PROG object s, consider the following:

•

A PROGTERM entry can only belong to one PROG entry. A PROGTERM entry cannot exist without a corresponding PROG entry. There can be multiple PROGTERM entries, one per device type.

•

A PROG is identified by a PROG name; a PROGTERM is identified by a device type name (for example, T16-6530) within the PROG name.

•

To implement the equivalent of the PATHCOM ADD PROGRAM command, use ADD PROG plus one ADD PROGTERM for each supported device.

•

To implement the equivalent of the PATHCOM RUN PROGRAM command, use the START PROG command.

Tell Messages

When developing a management application that defines and controls tell messages, consider the following:

•

The PATHCOM TELL TERM command is implemented with the SPI ADD TELL, TELL TERM, and START TELL commands.

•

To perform the equivalent of the PATHCOM TELL TERM (term-1, term-2), “string” command, follow these steps:

1. Add the tell message with the text “HELLO”:

1. Call SSINIT, issuing ZPWY-CMD-ADD and ZPWY-OBJ-TELL.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-34

Writing C Programs

2. Call SSNULL to initialize the fields in ZPWY-MAP-DEF-TELL with null values.

3. Assign “HELLO” to the ZAREA field in ZPWY-MAP-DEF-TELL and a value of 5 (the number of characters in HELLO) to the ZLENGTH field. Call SSPUT.

4. Send the buffer and ZPWY-VAL-BUFLEN to PATHMON, using a mechanism appropriate to the language you are using.

2. Queue the tell message for the TERM objects:

1. Call SSGET with ZPWY-MAP-TELLNUM. The tell number is returned in ZNUMBER; save this value.

2. Call SSINIT, issuing ZPWY-CMD-TELL and ZPWY-OBJ-TERM.

3. Call SSNULL to initialize the fields in ZPWY-MAP-SEL-TERM with null values.

4. Assign TERM-1 to the ZTERM field in ZPWY-MAP-SEL-TERM. Call SSPUT.

5. Assign the value from ZNUMBER (the tell number) to the ZNUMBER field in ZPWY-MAP-PAR-TELL-TERM. Call SSPUT.

6. Send the buffer to PATHMON.

7. Repeat Steps 2a through 2f for term-2.

3. Initiate delivery of the message:

1. Call SSINIT, issuing ZPWY-CMD-START and ZPWY-OBJ-TELL.

2. Call SSNULL to initialize the fields in ZPWY-MAP-SEL-TELL with null values.

3. Assign the value from ZNUMBER (returned in ZPWY-MAP-TELLNUM in Step 2a) to the ZNUMBER field in ZPWY-MAP-SEL-TELL. Call SSPUT.

4. Send the buffer to the PATHMON process.

Writ ing C Programs

This subsection contains special considerations for writing C programs.

Building the DDL Dictionary

The DDL comma nd ?CF IEL DALI GN_MATCHED2 allow s the DDL compil e r to g ener ate C data structures starting on byte boundaries. Always issue this command before you start building the DDL dictionary from the ZSPIDDL, ZEMSDDL, and ZPWYDDL files.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-35

Command Presentation

Generating The ZPWYC Inc lude File

Under certain conditions, the DDL compiler introduces an extra level in the structure definitions in the ZPWYC file. If any C compiler errors indicate a problem with the structure fields, make sure the structure definition in the ZPWYC file matches the structure used in the program.

Issuing Commands to PATHMON

Use the WRITEREADX procedure (not the WRITEREAD procedure) to send commands and receive responses; it provides a 32-bit value for the address of the command buffer (which you allocate using the MALLOC function).

Receiving String Values in Responses

Always terminate string values with a null character before using them. All stringmanipulating functions in C require that strings are terminated by a null character. However, string values retrieved from a response buffer might not always be terminated as expected. Failure to add a null character to the end of a string value results in problems that are difficult to detect.

Command Presentation

In the following sections, information on each command and its associated object type includes the following:

•

A description of the command and its effect

•

Information on continuation

•

A syntax box listing the following:

•

The command token (the symbolic name for the command number)

•

The object-type token (the symbolic name for the object type accepted by the command)

•

Tokens in the command buffer, which are specific to the command. (Token descriptions are in Section 5 , ZPWY-DDL- Definitions, and Section 6, ZPWY-

MAP- Definitions.)

•

Tokens in the response buffer, which are specific to the command. (Token descriptions are in Section 5 , ZPWY-DDL- Definitions, and Section 6, ZPWY-

MAP- Definitions.)

Caution. Data is often structured. When putting a null character at the end of a string

field, be careful not to corrupt subsequent data.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-36

Unlisted Tokens

The notation used for simple tokens in the syntax box is an abbreviated version of the essential information given in the DDL TOKEN-CODE statement. You define extensible structured tokens by using DDL DEFINITION statements.

The order of the tokens in the syntax box is not necessarily the order in which they must occur in a command or response buffer—except for the ZSPI-TKN-ENDLIST token. The ZSPI-TKN-ENDLIST token always appears at the end of a list that begins with the ZSPI-TKN-DATALIST or ZSPI- TKN-ERRLIST token.

Data lists and error lists are always indicated with an ellipsis (...). Data lists begin with the ZSPI-TKN-DATALIST token (followed by an ellipsis), and error lists begin with the ZSPI-TKN-ERRLIST token (followed by an ellipsis). Both types of lists (data and error) end with the ZSPI-TKN-ENDLIST token. The ZSPI-TKN-ENDLIST token is indented to symbolize that it is only used if a list token is present. For more information on data lists and error lists, see the SPI Programming Manual.

Unlisted Tokens

The following tokens can be present in command and response buffers but are not repeatedly listed or described in each command unless command-specific information is necessary:

See the descriptions of these tokens earlier in this section. For information about error tokens and error lists, see Section 11, TCP Event Messages, and Section 12, TCP

Error Messages.

Required Tokens and Fields

For each token in the command buffer and for each field of an extensible structured token in the command buffer, the syntax box contains an indication of whether or not the token or field must be present in the command.

For a token, the notation “!r” means that the token must be present (is required) in the command. The absence of the notation “!r” means that the token is optional. For a field of an extensible structured token, the notation “!r” means that the field must have a

Description Token Token Type

Message header tok ens N.A. N.A. Response-control token ZSPI-TKN-MAXRESP ZSPI-TYP-INT Data list tokens

(These are pr es ent only when t he response-control token is used and set to any nonzero value.)

ZSPI-TKN-DATALIST ZSPI-TKN-ENDLIST

ZSPI-TYP-LIST ZSPI-TYP-SSCTL

Return code token ZSPI-TKN-RETCODE ZSPI-TYP-INT Error list tokens

(These are returned only when an error is detect ed. )

ZSPI-TKN-ERRLIST ZSPI-TKN-ENDLIST

ZSPI-TYP-LIST ZSPI-TYP-SSCTL

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-37

Required Tokens and Fields

value other than its null value; a token that is present but has no assigned value is interpreted as having a value of all blanks.

SPI Programming Considerations

NonStop Pathway/iTS Management Programming Manual —426749-002

3-38

Required Tokens and Fields

NonStop Pathway/iTS Management Programming Manual —426749-002

4-1

SPI and EMS Standard Definitions

The information in this section is general information. Information about a definition specific to a particular command or response appears in the description of that command or response, later in this manual.

Definitions in this section appear in Data Definition Language (DDL) format. Definitions of structures use DDL definition statements. For an explanation of DDL, see the Data Definition Language (DDL) Reference Manual.

Definitions encountered in NonStop Pathway/iTS that are used uniquely by TS/MP to support servers and objects related to them are described in the TS/MP Mana geme nt Programming Manual.

SPI Standard Definitions

All items in the definition files are given symbolic names. Definitions whose names begin with ZSPI- are SPI standard definitions. These definitions are available to all subsystems that support SPI procedures; they are provided in the SPI DDL file (ZSPIDEF.ZSPIDDL) and in the corresponding files for other languages. For information about the SPI standard definitions used in the Pathway management programming interface, see the TS/MP Management Programming Manual.

EMS Standard Definitions

Definitions whose names begin with ZEMS- are EMS standard definitions. These definitions are available to all subsystems that support EMS; they are provided in the EMS DDL file (ZSPIDEF.ZEMSDDL) and in the corresponding files for other languages.

Table 4-1

and Table 4-2 list the EMS standard definitions for header tokens and data- portion tokens used in the management programming interface to the Pathway subsystem. The tables do not list EMS error numbers or definitions used only in error lists. For descriptions of EMS standard definitions, see the EMS Manual.

Table 4-1. EMS Standard Definitions for Header Tokens

ZEMS-TKN-CONSOLE-PRINT ZEMS-TKN-CRTPID ZEMS-TKN-EMPHASIS ZEMS-TKN-EVENTNUMBER ZEMS-TKN-GENTIME

ZEMS-TKN-LOGTIME ZEMS-TKN-PIN ZEMS-TKN-SYSTEM ZEMS-TKN-USERID

Table 4-2. EMS Standard Definition for Data-Portion Tokens

ZEMS-TKN-SUBECT-MARK

SPI and EMS Standard Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

4-2

EMS Standard Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-1

5 ZPWY-DDL- Definitions

This section discusses private tokens, field types, and predefined token and field values used in the token-oriented management programming interface to NonStop Pathway/iTS.

Definitions encountered in Pathway/iTS that are used uniquely by the TS/MP software to support servers and objects related to them are described in the TS/MP Management Programming Manual.

Pathway Subsystem Definitions

Definitions whose names begin with ZPWY- are Pathway subsystem definitions. These definitions are provided in the DDL file ZSPIDEF.ZPWYDDL and in the corresponding files for other languages.

Table 5-1 through Table 5-5 on page 5-2 list Pathway subsystem definitions. The

definitions are for:

Buffer declarations Object names Private token and field types Predefined token and field values Field types for predefined values

The definitions are described later in this section. Definitions for extensible structured tokens are described in Sect i on 6, ZPW Y-MAP- Defin i ti on s

Table 5-1. Pathway Buffer Declarations

ZPWY-DDL-MSG-BUFFER ZPWY-DDL-MAX-MSG-BUFFER

Table 5-2. Pathway/iTS Object Names

ZPWY-DDL-PROGNAME ZPWY-DDL-PROGTERMNA ME ZPWY-DDL-SCOBOL-PUNAME ZPWY-DDL-SCTCPNAME ZPWY-DDL-SCTERMNAME ZPWY-DDL-TCPLINKNAME

ZPWY-DDL-TCPNAME ZPWY-DDL-TCPSCNAME ZPWY-DDL-TCPTERMNAME ZPWY-DDL-TELLNAME ZPWY-DDL-TERMNAME ZPWY-DDL-UNKNOWNNAME

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-2

Pathway Subsystem Definitions

A few type names are not described; instead they are expanded into their component fields. These types are:

Table 5-3. Pathway/iTS Private Token and Field Types

ZPWY-DDL-AUTO-RESTART ZPWY-DDL-CHAR15 ZPWY-DDL-CHAR30 ZPWY-DDL-CHAR132 ZPWY-DDL-CPU ZPWY-DDL-DUMP-INFO ZPWY-DDL-ERRINFO2 ZPWY-DDL-ERROR-INFO ZPWY-DDL-FILLER ZPWY-DDL-INSPECT-INFO ZPWY-DDL-IO-PROTOCOL ZPWY-DDL-OBJECT-NAME ZPWY-DDL-ON-OFF

ZPWY-DDL-ON-OFF-CURRENT ZPWY-DDL-OWNER-ID ZPWY-DDL-PRINTER-INFO ZPWY-DDL-TERM-TYPE ZPWY-DDL-TERMTYPE-INFO ZPWY-DDL-TMF-RESTARTS ZPWY-DDL-UNUSED1-INFO ZPWY-DDL-YES-NO ZPWY-DDL-0-2045 ZPWY-DDL-0-2250 ZPWY-DDL-0-4095 ZPWY-DDL-1-199 ZPWY-DDL-1-255

Note. The Pathway subsystem types listed in Table 5-3

are used only as a basis for defining other types . These types in dic ate the stru c t ure or type of parts of o th er types, but your programs should not refer to them directly. Therefore, to save space, Pathway/iTS does not produce programming -language de c larations for them.

STATS ty pes: ZPWY-DDL-TC PAREA-STAT

ZPWY-DDL-TCPPOOL-STAT ZPWY-DDL-TCPQUEUE-STAT ZPWY-DDL-TCP2DATAAREA-STAT ZPWY-DDL-TCP2CODEAREA-STAT ZPWY-DDL-TERMAREA-STAT ZPWY-DDL-TERM2CODE-STAT ZPWY-DDL-TERM2DATA-STAT

Table 5-4. Pathway Predefined Token and Field Values

ZPWY-VAL-SSID ZPWY-VAL-BUFLEN

ZPWY-VAL-BUFSIZE ZPWY-VAL-VERSION

Table 5-5. Pathway/iTS Field Types for Predefined Values

ZPWY-DDL-CHARSET-VALUE ZPWY-DDL-FRZSTATETERM-VALUE ZPWY-DDL-NONSTOP-VALUE ZPWY-DDL-OBJSTATE-VALUE ZPWY-DDL-POP-VALUE

ZPWY-DDL-SECURITY-VALUE ZPWY-DDL-TCPQUALSTATE-VALUE ZPWY-DDL-TERMPEND-VALUE ZPWY-DDL-TERMWAIT-V A LUE ZPWY-DDL-TRMQUALSTATE-VALUE

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-3

Buffer Declarations

Pathway/iTS provides the following buffer declarations for message buffers you can use with the SPI procedures.

ZPWY-DDL-MSG-BUFFER

is a message buffer of the appropriate size for use with most SPI procedures.

This buffer message declaration is also defined in the ZSPIDEF.ZPWYTACL file with the size of the Z-FILLER field set to 2048 bytes.

ZPWY-DDL-MAX-MSG-BUFFER

is a message buffer of the appropriate size for use with the SPI procedures in applications that manage requestors written in TACL.

This buffer message declaration is also defined in the ZSPIDEF.ZPWYTACL file with the size of the Z-FILLER field set to 4994 bytes. It is defined in the ZSPIDEF.ZPWYTAL file with the size of the Z-FILLER field set to 30000 bytes.

Object Names

The DDL definitions for object names are used to define the object-selector tokens referenced with token maps (not token codes). For object-selector tokens, whether each field is required or optional depends upon the command in which the token type is used; required and optional fields are therefore marked in the individual command descriptions.

def ZPWY-DDL-MSG-BUFFER. 02 Z-MSGCODE token-type ZSPI-DDL-INT. 02 Z-BUFLEN token-type ZSPI-DDL-INT. 02 Z-OCCURS token-type ZSPI-DDL-INT. 02 Z-FILLER token-type ZSPI-DDL-CHAR. occurs 0 to ZPWY-VAL-BUFLEN times depending on Z-OCCURS. end.

def ZPWY-DDL-MAX-MSG-BUFFER. 02 Z-MSGCODE token-type ZSPI-DDL-INT. 02 Z-BUFLEN token-type ZSPI-DDL-INT. 02 Z-OCCURS token-type ZSPI-DDL-INT. 02 Z-FILLER token-type ZSPI-DDL-CHAR. occurs 0 to ZPWY-VAL-MAX-TACLBUFLEN times depending on Z-OCCURS. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-4

Toke n Codes for Objec t Name s

The DDL definitions for object names are also used to define the error tokens ZPWY - TKN-REQobjecttypeNAME and ZPWY-TKN-objecttypeNAME and the subject tokens for event messages.

Token Codes for Object Names

The DDL definitions for object names describe token types that have the prefix ZPWY-TYP-. The token types are used to build token codes, which have the prefix ZPWY-TKN-. Each token code for an object name has the same name as its corresponding token type; for example, the token type ZPWY-TYP-PROGNAME is used to build the token code ZPWY-TKN-PROGNAME.

ZPWY-DDL-PROGNAME

ZPWY-DDL-PROGNAME identifies a PROG object—a template used by the PATHMON process to create temporary TERM objects.

ZPROGRAM

specifies the name of a PROG object definition.

ZPWY-DDL-PROGT ERMNAME

ZPWY-DDL-PROGTERMNAME specifies the PROG object name and the type of device on which the program runs.

ZPROGRAM

specifies the name of the program with which this device is associated.

ZTERMTYPE

specifies the type of device. For more information on device types, see the description of ZPWY-DDL-TERMTYPE-INFO on page 5-17.

def ZPWY-DDL-PROGNAME. 02 ZPROGRAM token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

def ZPWY-DDL-PROGTERMNAME. 02 ZPROGRAM token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER token-type ZPWY-DDL-FILLER. 02 ZTERMTYPE token-type ZPWY-DDL-TERM-TYPE. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-5

ZPWY-DDL-SCOBOL-PUNAME

ZPWY-DDL-SCOBOL-PUNAME identifies a SCREEN COBOL program unit. This name is the program name specified in the PROGRAM-ID sentence of the identification division in a SCREEN COBOL program.

ZPWY-DDL-SCTCPNAME

ZPWY-DDL-SCTCPNAME specifies the name of a server class and the name of a TCP that is linked to that server class.

ZSERVERCLASS

is the name of the server class. For more information on server classes, see the TS/MP Management Programming Manual.

ZTCP

is the name of the TCP.

ZPWY-DDL-SCTERMNAME

ZPWY-DDL-SCTERMNAME identifies a specific TERM object associated with a given server class.

ZSERVERCLASS

is the name of the server class. For more information on server classes, see the TS/MP Management Programming Manual.

ZTERM

is the name of a TERM object.

def ZPWY-DDL-SCOBOL-PUNAME token-typ ZPWY-DDL-CHAR30.

def ZPWY-DDL-SCTCPNAME. 02 ZSERVERCLASS token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER token-type ZPWY-DDL-FILLER. 02 ZTCP token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

def ZPWY-DDL-SCTERMNAME. 02 ZNAME. 03 ZSERVERCLASS token-type ZPWY-DDL-OBJECT-NAME. 03 FILLER token-type ZPWY-DDL-FILLER. 03 ZTERM token-type ZPWY-DDL-OBJECT-NAME. 03 FILLER-1 token-type ZPWY-DDL-FILLER. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-6

ZPWY-DDL-TCPLINKNAME

ZPWY-DDL-TCPLINKNAME specifies a link between a TCP and a specific server process in a server class.

ZSERVERCLASS

is the name of the server class.

ZPROCESS

is the Guardian process name of the server process. The name consists of a dollar sign ($) followed by one to five alphanumeric characters. The first character must be a letter.

ZTCP

is the name of the TCP currently linked to the server class.

ZPWY-DDL-TCPNAME

ZPWY-DDL-TCPNAME identifies a specific TCP.

ZTCP

is the name of the specific TCP.

ZPWY-DDL-TCPSCNAME

ZPWY-DDL-TCPSCNAME specifies the name of a server class and the name of the TCP linked to that server class.

def ZPWY-DDL-TCPLINKNAME. 02 ZSERVERCLASS token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER token-type ZPWY-DDL-FILLER. 02 ZPROCESS token-type ZSPI-DDL-CHAR6. 02 ZTCP token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

def ZPWY-DDL-TCPNAME. 02 ZTCP token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

def ZPWY-DDL-TCPSCNAME. 02 ZTCP token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER token-type ZPWY-DDL-FILLER. 02 ZSERVERCLASS token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-7

ZPWY-DDL-TCPTERMNAME

ZTCP

is the name of the TCP.

ZSERVERCLASS

is the name of the server class.

ZPWY-DDL-TCPTERMNAME

ZPWY-DDL-TCPTERMNAME identifies a terminal associated with a specific TCP.

ZTERM

is the name of a TERM object.

ZTCP

is the name of the TCP with which this TERM object is associated.

ZPWY-DDL-TELLNAME

ZPWY-DDL-TELLNAME specifies the number of a tell message.

ZNUMBER

is a binary number that the PATHMON process returns to the ADD TELL command to identify the tell message for subsequent commands. The number is defined as two characters to allow programs to use continuation.

ZPWY-DDL-TERMNAME

ZPWY-DDL-TERMNAME identifies a TERM object.

def ZPWY-DDL-TCPTERMNAME. 02 ZTCP token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER token-type ZPWY-DDL-FILLER. 02 ZTERM token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

def ZPWY-DDL-TELLNAME. 02 ZNUMBER token-type ZSPI-DDL-CHAR-PAIR. end.

def ZPWY-DDL-TERMNAME. 02 ZTERM token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-8

ZPWY-DDL-UNKNOWNNAME

ZTERM

is the name of the specific TERM object.

ZPWY-DDL-UNKNOWNNAME

ZPWY-DDL-UNKNOWNNAME is used in event management to identify the name of the subject when the object type (for example, TCP or TERM) is unknown. It is also used for internal errors when the type of the subject is not known.

ZUNKNOWN

identifies the name of the subject of an event, which is of an unknown type.

Private Token and Field Types

A private token is a token defined and used exclusively by the subsystem that defines it.

The following paragraphs describe the private token and field types defined by the Pathway subsystem for Pathway/iTS.

ZPWY-DDL-AUTO-RESTART

ZPWY-DDL-AUTO-RESTART specifies the maximum number of times that the PATHMON process attempts to restart an object (that is, a server, TCP, or TERM) within a fixed 10-minute interval.

ZPWY-DDL-CHAR15

ZPWY-DDL-CHAR15 designates 15 ASCII characters, addressable as a STRUCT, as bytes or as integers.

def ZPWY-DDL-UNKNOWNNAME. 02 UNKNOWN token-type ZPWY-DDL-OBJECT-NAME. 02 FILLER-1 token-type ZPWY-DDL-FILLER. end.

def ZPWY-DDL-AUTO-RESTART token-type ZSPI-DDL-INT2.

def ZPWY-DDL-CHAR15. 02 Z-C PIC X(15). 02 Z-S redefines Z-C. 03 Z-I type BINARY 16 occurs 7 times. 03 FILLER PIC X. 02 Z-B redefines Z-C PIC X occurs 15 times. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-9

ZPWY-DDL-CHAR30

ZPWY-DDL-CHAR30 designates 30 ASCII characters, addressable as a STRUCT, as bytes or as integers.

ZPWY-DDL-CHAR132

ZPWY-DDL-CHAR132 designates 132 ASCII characters, addressable as a STRUCT, as bytes or as integers.

ZPWY-DDL-CPU

ZPWY-DDL-CPU is the processor number of a particular processor in a system. Valid values range from 0 to 15.

ZPWY-DDL-DUMP-INFO

ZPWY-DDL-DUMP-INFO specifies whether the TCP writes the contents of its data stack and extended data segment information to a file if an internal error occurs. If dumping is enabled, you can specify the name of the file to which the information is written.

def ZPWY-DDL-CHAR30. 02 Z-C PIC X(30). 02 Z-S redefines Z-C. 03 Z-I type BINARY 16 occurs 15 times. 02 Z-B redefines Z-C PIC X occurs 30 times. end.

def ZPWY-DDL-CHAR132. 02 Z-C PIC X(132). 02 Z-S redefines Z-C. 03 Z-I type BINARY 16 occurs 66 times. 02 Z-B redefines Z-C PIC X occurs 132 times. end.

def ZPWY-DDL-CPU token-type ZSPI-DDL-INT.

def ZPWY-DDL-DUMP-INFO. 02 ZDUMP token-type ZPWY-DDL-ON-OFF. 02 ZDUMPFILE token-type ZSPI-DDL-FNAME32. end.

Note. The value s pec ified for ZDUMP in th e C ONTROL TC P c om mand override s th e valu e specified for ZDUMP in the ADD TCP command.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-10

ZPWY-DDL-DUMP-INFO

ZDUMP

enables or disables memory dumping. The following values are valid:

ZDUMPFILE

specifies the name of the file that the TCP creates for its dump operation. The following values are valid:

[\node] [.$volume] [.subvol] [.filename]

You can specify either a specific node name or \*, a generic name representing the node on which the PATHMON process is currently running. If you do not specify a node name, the default node for file-name expansion can be affected by the value you specify for the ZNODEINDEPENDENT field of the TS/MP START PATHWAY command. For more information on node independence, see the Pathway/iTS System Management Manual.

If a file error interferes with creating a file that you specify, the TCP creates the dump file on the same subvolume as its program object file and uses the form ZZTCPnnx for the file name.

If you do not specify a file name, the TCP creates it s dum p file on the sam e volume and subvolume as the PATHMON configuration file. The format of the file names are ZZTCPnnP and ZZTCPnnB, where nn is a number from 01 to 10, and P and B indicate the primary or the backup process, respectively, that the TCP dumped.

Reset values for each field are predefined. These values are described in Section 3,

SPI Programming Considerations. To reset the fields using the TACL program, you

must use the #SETBYTES built-in function. For more information, see the SPI Programming Manual.

ZPWY-VAL-OFF Directs the TCP not to write data stack information to a file

when it encounters an inter nal or fatal error. This is the default value.

ZPWY-VAL-ON Directs the TCP to create one or more disk files and write the

contents of its data stack and its extended data segment to these files.

After creating 10 primary process and 10 backup process dump files, the PATHMON process and the TCP stop performing memory dumps. This prevents writing over existing dump files that may indicate the original cause of a problem, and prevents filling a disk with dump files.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-11

ZPWY-DDL-ERRINFO2

ZPWY-DDL-ERRINFO2 provides process-creation error information in a two-word format.

ZERROR2

contains a Pathway subsystem error number. The error numbers are described by symbolic names in the Pathway/iTS System Management Manual.

ZINFO2

contains the process-creation error information in the PROCESS_CREATE_ and PROCESS_SPAWN_ two-word format. The following values are valid:

ZDETAIL2

contains additional error information.

The following example shows error information returned in ZERRORINFO and ZERRORINFO2:

ZERRORINFO ZERROR 1038 ZINFO %001413 ZERRORINFO2

def ZPWY-DDL-ERRINFO2. 02 ZERROR2 token-type ZPWY-DDL-INT. 02 ZINFO2 token-type ZSPI-DDL-INT. 02 ZDETAIL2 token-type ZSPI-DDL-INT. end.

ZPWY-VAL-: PROCCREATBACKUPSUBTYP

PROCCREATBADHOMETERM PROCCREATBADLIBFORMAT PROCCREATBADPFSSIZE PROCCREATBADPRGFORMAT PROCCREATBOUNDS PROCCREATDEFINE PROCCREATDEVICESUBTYP PROCCREATEXTSWAP PROCCREATHOMETERM PROCCREATLIBCONFLICT PROCCREATLIBRARY PROCCREATLICENSE PROCCREATMAINSTKALLOC PROCCREATMAINSTKLOCK PROCCREATMAP PROCCREATMONITOR PROCCREATNOPCB PROCCREATPARAM

PROCCREATPRIVSTKALLOC PROCCREATPRIVSTKLOCK PROCCREATPROCESSNAME PROCCREATPROGRAM PROCCREATSAMEFILES PROCCREATSEGMENTINIT PROCCREATSUCCESS PROCCREATSWAP PROCCREATUNKNOWNFROMC PROCCREATUNNAMEDCALLR PROCCREATUNRESOLVDEXT TPCERRALLOCSTATIC TPCERRBECOMEOSS TPCERRDUPFD TPCERRINTERPRETER TPCERRNOTOSS TPCERROPENPATHNAME TPCERROPENTIMEOUT TPCERRWORKINGDIR

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-12

ZPWY-DDL-ERROR-INFO

ZERROR2 1038 ZINFO2 1 ZDETAIL2 11

ZPWY-DDL-ERROR-INFO

ZPWY-DDL-ERROR-INFO provides error information.

ZERROR

contains a Pathway environment error number. The error numbers are described by symbolic names in the NonStop Pathway/iTS Management Reference Manual.

ZINFO

contains the number of a second error that provides further information about ZERROR.

The following example shows error information returned in ZERRORINFO:

ZERRORINFO

ZERROR 1038 ZINFO %001413

ZPWY-DDL-FILLER

ZPWY-DDL-FILLER is a filler character.

SSNULL initializes a field with this type to a blank character.

ZPWY-DDL-INSPECT-INFO

ZPWY-DDL-INSPECT-INFO indicates whether SCREEN COBOL programs running on TERM objects controlled by a TCP can be examined by using the HP Inspect debugging tool. This token can also specify an Inspect command terminal.

def ZPWY-DDL-ERROR-INFO. 02 ZERROR token-type ZPWY-DDL-INT. 02 ZINFO token-type ZSPI-DDL-INT. end.

def ZPWY-DDL-FILLER token-type ZSPI-DDL-CHAR.

def ZPWY-DDL-INSPECT-INFO. token-type ZSPI-DDL-INT. 02 ZINSPECT token-type ZPWY-DDL-ON-OFF. 02 ZINSPECTFILE token-type ZSPI-DDL-FNAME32.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-13

ZPWY-DD L-IO-PROTOCOL

ZINSPECT

specifies whether a SCREEN COBOL program running on a TERM object starts the Inspect process when the program begins execution. The following values are valid:

If you do not assign a value to this field, the default is ZPWY-VAL-OFF.

ZINSPECTFILE

contains the name of the Inspect command terminal. You can specify either a specific node name or \*, a generic name representing the

node on which the PATHMON process is currently running. If you do not specify a node name, the default node for file-name expansion can be affected by the value you specify for the ZNODEINDEPENDENT field of the TS/MP START PATHWAY command. For more information on node independence, see the Pathway/iTS System Management Manual.

To reset this field using the TACL program, you must use the #SETBYTES built-in function. For more information, see the SPI Programming Manual.

ZPWY-DDL-IO-PROTOCOL

ZPWY-DDL-IO-PROTOCOL specifies the protocol the TCP follows when a SCREEN COBOL SEND ME SSAGE st atem ent completes with a time out o r u nsoli cited messag e. The values for this type are described under ZIOPROTOCOL on page 6-11

ZPWY-DDL-OBJECT-NAME

ZPWY-DDL-OBJECT-NAME designates a name given to an object in the PATHMON environment (such as a TCP, PROG, or TERM object). The name can have from 1 through 15 alphanu mer ic or hyphen cha racter s, must st art w ith a letter, must be unique within the Pathway subsystem, and must not be a Pathway reserved word. The name must be left-justified and blank-filled. Pathway subsystem reserved words are listed in the Pathway/iTS System Management Manual.

ZPWY-VAL-OFF The Inspect process is not started when the program begins. ZPWY-VAL-ON The Inspect process is started when the program begins. The

program is positioned at a breakpoint before the first instruction executes.

def ZPWY-DDL-IO-PROTOCOL. token-type ZPWY-DDL-INT.

ZPWY-DDL-OBJECT-NAME token-type ZPWY-DDL-CHAR15.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-14

ZPWY-DDL-ON-OFF

ZPWY-DDL-ON-OFF specifies whether a feature or capability (such as using an Inspect process or TMF auditing) is enabled.

Values can be ZPWY-VAL-ON or ZPWY-VAL-OFF; their meanings are further described in the fields in which they occur.

ZPWY-DDL-ON-OFF-CURRENT

ZPWY-DDL-ON-OFF-CURRENT specifies whether to override the echo mode configured for a device at system generation. This type applies to the TERM and PROG objects.

The following values are valid:

ZPWY-DDL-OWNER-ID

ZPWY-DDL-OWNER-ID is the user ID allowed to issue commands that directly alter the state of PATHMON-controlled objects. The user ID must be known to the system in which your management application is running.

def ZPWY-DDL-ON-OFF token-type ZSPI-DDL-BOOLEAN.

Note. ZPWY-VAL-ON is equivalent to ZSPI-VAL-TRUE, and ZPWY-VAL-OFF is equivalent to ZSPI-VAL-FALSE, ne ith er of which values are supported in CO BOL. For information on working wi th Boolean values a nd C OBOL co ding suggestions, see the SP I P rogramming Manual.

def ZPWY-DDL-ON-OFF-CURRENT token-type ZSPI-DDL-ENUM.

ZPWY-VAL-ON Causes input to appear on the output device. ZPWY-VAL-OFF Correct s the d i splay by sup pressin g the d upl icate ch aract ers

(if an output device is configured so that it normally displays input characters).

If you define this option for the supported device types T16-6520, T16-6530, and T16-6540, no input characters appear on the screen.

ZPWY-VAL-CURRENT Causes the TCP to obtain the operating mode of the output

device from the operating system and to use that mode when the TCP opens the output device.

def ZPWY-DDL-OWNER-ID. 02 ZSYSTEMNUMBER token-type ZSPI-DDL-INT. 02 ZGROUPNUMBER token-type ZSPI-DDL-INT. 02 ZUSERNUMBER token-type ZSPI-DDL-INT. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-15

ZPWY-DDL-PRINTER-INFO

ZSYSTEMNUMBER

is a number from 0 through 255 that uniquely identifies a system. To find your system number, call the MYSYSTEMNUMBER procedure as described in the Guardian Procedure Calls Reference Manual. You need not specify a system number if the system associated with the user ID is the same as the system in which your management application is running.

To specify node-independence, set this field to ZPWY-VAL-NODEINDOWNERSYS.

ZGROUPNUMBER

is a number from 0 through 255 that uniquely identifies a group of users on a system. This field is required.

ZUSERNUMBER

is a number from 0 through 255 that uniquely identifies a user within a group. This field is required.

If you do not assign values to these fields, the default is the owner ID of the user who started the PAT HMON process.

ZPWY-DDL-PRINTER-INFO

ZPWY-DDL-PRINTER-INFO provides information about the printer to be used for the SCREEN COBOL verb PRI N T SCREEN.

ZISATTACHED

directs the copy of the screen imag e to a printer that is eithe r physicall y att ached to the terminal (for example, a 6520, 6530, or 6540 terminal) or is on the same line controller as the terminal on which the management application runs (for example, an IBM 3270 compatible terminal using AM3270). The following values are valid:

def ZPWY-DDL-PRINTER-INFO. 02 ZISATTACHED token-type ZPWY-DDL-YES-NO. 02 ZPRINTERFILE token-type ZSPI-DDL-FNAME32. end.

ZPWY-VAL-NO Specifies that no printer is attached. ZPWY-VAL-YES Specifies that a printer is attached.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-16

ZPWY-DDL-TERM-TYPE

ZISATTACHED directs the copy of the screen image to the attached printer. The field has the following associations:

If you assign ZPWY-VAL-YES to ZISATTACHED for a 6520, 6530, or 6540 terminal, the SCREEN COBOL special register TERMINAL-PRINTER is ignor ed.

If you do not assign a value to this field, the default is ZPWY-VAL-NO.

ZPRINTERFILE

is the file name of a print device placed in the SCREEN COBOL special register TERMINAL-PRINTER when a PROG or TERM object starts. The SCREEN COBOL PRINT SCREEN verb obtains the printer’s file name from the TERMINALPRINTER special register. You can modify the file name in the SCREEN COBOL program’s TERMINAL-PRINTER register and then use the new file name.

To reset this field using the TACL program, you must use the #SETBYTES built-in function. For more information, see the SPI Programming Manual.

ZPWY-DDL-TERM-TYPE

ZPWY-DDL-TERM-TYPE specifies the device type that the TCP uses for running a SCREEN COBOL program on a device.

The following values are valid:

T16-6530 Directs copy to a printer attached directly to the terminal. T16-6520 Directs copy to a printer attached directly to the terminal. IBM-3270 Directs copy to the printer, which must be attached to the

same control unit as the terminal.

def ZPWY-DDL-TERM-TYPE token-type ZSPI-DDL-OBJECTNAME.

IBM-3270 IBM 3270 terminal T16-6520 6520 terminal T16-6530 6530 terminal CONVERSATIONAL Conversa ti onal-m ode term inal

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-17

ZPWY-DDL-TERMTYPE-INFO

When specifying a device type, consider the following:

•

If a program is running on an incompatible device type, the results can be unpredictable, depending on the device type. For example, the results are unpredictable wh en a SCREEN COBOL program compi led for an IBM 3270 terminal is executed on a 6530 terminal.

•

Programs compiled for 6520, 6530, and conversational-mode terminals can be executed on a 6540 terminal defined as a 6530 device emulator.

•

You can run a program compiled for a 6520 terminal on 6530 and 6540 terminals. If you specify a type T16-6520 and you run the program on a 6530 terminal, the features that are unique to the 6530 terminal do not function. In the same way, if you run programs compiled for 6530 terminals on 6540 terminals, the features unique to the 6530 terminals do not function.

•

The TCP can execute the same SCREEN COBOL programs on different types of devices; therefore, you can run SCREEN COBOL programs written for conversational mode on some block mode devices.

•

If you specify type CONVERSATIONAL for a terminal, the SCREEN COBOL programs compiled for a terminal operating in conversational mode can run on an IBM 3270 terminal; 6520, 6530, and 6540 terminals; or any device operating as a conversational-mode terminal recognized by the file system.

For information about conversational-mode terminal characteristics, see the Guardian Programmer's Guide.

•

Unlike the PATHCOM interface, which allows you to specify the device type by number or name, you can specify the device type only by name for the Pathway management programming interface.

ZPWY-DDL-TERMTYPE-INFO

ZPWY-DDL-TERMTYPE-INFO provides information about the device type that the TCP uses for running a SCREEN COBOL program on a device.

T16-6540 6540 terminal emulating a 6530 terminal INTELLIGENT Intelligent device T16-6530WP 6530WP terminal

def ZPWY-DDL-TERMTYPE-INFO 03 ZTERMTYPE token-type ZPWY-DDL-TERM-TYPE. 03 FILLER token-type ZPWY-DDL-FILLER. 03 ZSUBTYPE token-type ZSPI-DDL-INT. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-18

ZPWY-DDL-TERMTYPE-INFO

ZTERMTYPE

specifies the type of device on which the TERM runs or selects from the PROG definition the type of device on which the program runs. The ZTERMTYPE field in ZPWY-DDL-TERMTYPE-INFO has the same possible values as ZPWY-DDL-TERM-TYPE.

When specifying the type of device on which a TERM runs, consider the following:

•

If ZTERMTYPE specifies IBM-3270 or INTELLIGENT, then you must also assign a value to the ZSUBTYPE field.

•

Specifying or changing the ZTERMTYPE field does not set or reset the ZSUBTYPE field; each field must be explicitly set or reset. For example, if ZTERMTYPE i s IB M- 3270 and ZSU BTYPE is 4, a nd you change ZTER MTYP E to T16-6530, you must change ZSUBTYPE to 0 to avoid generating an error.

•

If the SCREEN COBOL TERMINAL IS clause specifies CONVERSATIONAL and the ZTERMTYPE field has the value T16-6530, the TCP executes the program on the 6530 terminal in conversational mode. If the TERMINAL IS clause is omitted and the TCP attempts to execute this same program, it returns an error.

•

If the TERMINAL IS clause of the running SCREEN COBOL program is not present, the value specified for the ZTERMTYPE field is used.

•

If the TERMINAL IS clause is not present and a value for ZTERMTYPE is not specified, the TCP obtains the device type from a call to the file-system DEVICEINFO procedure.

When determining the type of device on which a program runs, consider the following:

•

The selection of the device type depends on the type of device on which the program runs.

•

A PROG definition can have more than one device type associated with it. For example, a program can run on an IBM 3270 terminal, a 6530 terminal, and an intelligent device. A sep arate program u nit is associated with ea ch d evice t y pe.

•

If you specify a value for ZTERMTYPE, the PATHMON process uses that value to select the device type from the PROG definition.

•

If you specify a value for ZTERMTYPE but the device type you have entered is not defined in the PROG definition, the STA RT PROG command fails with the following error:

*1086* TERM TYPE NOT DEFINED FOR PROGRAM

•

If you do not specify a ZTERMTYPE value, the PATHMON process issues a file-system DEVICEINFO query to the device on which the program runs. The reply from the DEVICEINFO query is used to determine the appropriate device type.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-19

ZPWY-DDL-TERMTYPE-INFO

•

If the device type derived from the DEVICEINFO reply is not defined in the PROG definition, the START PROG command fails with the following error:

*1086* TERM TYPE NOT DEFINED FOR PROGRAM

To reset this field using the TACL program, you must use the #SETBYTES built-in function. For more information on this function, see the SPI Programming Manual.

ZSUBTYPE

contains additional information about specific device types on which TERM objects run. For intelligent devices, ZTERMTYPE must be INTELLIGENT, and ZSUBTYPE, which specifies the I/O protocol, must be one of the following:

For IBM 3270 terminals, ZTERMTYPE must be IBM-3270 and ZSUBTYPE, which specifies the screen display, must be one of the following:

For information on using IBM 3270 terminals in a Pathway environment, see the Pathway/iTS TCP and Terminal Programming Guide.

When specifying additional info rmation about a device type, consider the foll owing:

•

Specifying or changing the ZSUBTYPE field does not set or reset the ZTERMTYPE field. Each field must be explicitly set or reset.

•

If the TERMINAL IS clause of the running SCREEN COBOL program does not specify additional device information, the value specified for the ZSUBTYPE field is used.

•

If the TERMINAL IS clause is not present and a value for ZSUBTYPE is not specified, the TCP obtains the additional device information from a call to the file-system DEVICEINFO procedure.

0 WRITEREAD I/O protocol; write to device and wait for reply (default) in

conversational mode.

1 WRITE and READ I/O protocol; write to device and then read from device in

block mode.

2 WRITEREAD I/O protocol; write to device and wait for reply in block mode.

Terminal Subtype Screen Size Model

1 480, 12 x 40 IBM 3277 M1 2 1920, 24 x 80 IBM 3277 M2 3 2560, 24 x 80, alternate 32 x 80 IBM 3278 M3 4 3440, 24 x 80, alternate 43 x 80 IBM 3278 M4 5 960, 12 x 40, alternate 12 x 80 IBM 3278 M1 6 3564, 24 x 80, alternate 27 x

132

IBM 3278 M5

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-20

ZPWY-DDL-TMF-RESTARTS

•

If a value for ZSUBTYPE is not specified in the TERMINAL IS clause of a program for an intelligent device or in ZPWY-DDL-TERMTYPE-INFO, a default value is used rather than the value obtained from the file-system DEVICEINFO call.

ZPWY-DDL-TMF-RESTARTS

ZPWY-DDL-TMF-RESTARTS specifies the maximum number of times a TCP can attempt to restart a logical TMF transaction after the transaction aborts and before the SEND error occurs.

The following values are valid:

ZPWY-DDL-YES-NO

ZPWY-DDL-YES-NO specifies a yes or no decision. Valid values are ZPWY-VAL-YES or ZPWY-VAL-NO.

ZPWY-DDL-0-2045

ZPWY-DDL-0-2045 is a value from 0 through 2045.

ZPWY-DDL-0-2250

ZPWY-DDL-0-2250 is a value from 0 through to 2250.

def ZPWY-DDL-TMF-RESTARTS token-type ZSPI-DDL-INT2.

0 No restarts

-1 Unlimited number of restarts 1 through 32,767 Number of restarts specified

def ZPWY-DDL-YES-NO token-type ZSPI-DDL-BOOLEAN.

Note. ZPWY-VAL-YES is equivalent to ZSPI-VAL-TRUE, and ZPWY-VAL-NO is equivale nt to ZSPI-VAL-FALSE, ne ith er of which is suppor te d in COBOL. For infor m ation on working with Boolean values and COBOL coding suggestions, see the SPI Programming Manual.

def ZPWY-DDL-0-2045 token-type ZSPI-DDL-INT.

def ZPWY-DDL-0-2250 token-type ZSPI-DDL-INT.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-21

ZPWY-DDL-0-4095

ZPWY-DDL-0-4095 is a value from 0 through 4095.

ZPWY-DDL-1-199

ZPWY-DDL-1-199 is a value from 1 through 199.

ZPWY-DDL-1-255

ZPWY-DDL-1-255 is a value from 1 through 255.

Predefined Token and Field Values

A predefined token or field is given a symbolic name in the Pathway subsystem definitions file. The Pathway subsystem defines the following token and field values:

ZPWY-VAL-SSID

is the subsystem ID of the Pathway subsystem with the following structure:

ZPWY-VAL-BUFLEN

is the length of the message buffer, in bytes.

ZPWY-VAL-BUFSIZE

is the size of the message buffer, in words. The message buffer is used to communicate with the PATHMON process.

def ZPWY-DDL-0-4095 token-type ZSPI-DDL-INT.

def ZPWY-DDL-1-199 token-type ZSPI-DDL-INT.

def ZPWY-DDL-1-255 token-type ZSPI-DDL-INT.

def ZPWY-VAL-SSID Tacl SSID. 02 Z-FILLER token-type ZSPI-DDL-CHAR 8. value ZSPI-VAL-TANDEM. 02 Z-OWNER token-type ZSPI-DDL-CHAR 8. redefines Z-FILLER 02 Z-NUMBER token-type ZSPI-DDL-INT. value ZSPI-SSN-ZPWY. 02 Z-VERSION token-type ZSPI-DDL-INT value ZPWY-VAL-VERSION. end.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-22

Private Field Types for Predefined Values

ZPWY-VAL-VERSION

is the product version number of the Pathway 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; for example, D30.

Private Field Types for Predefined Values

Many predefined token and field values are associated with private field types specific to the Pathway subsystem. For example, the predefined values ZPWY-VAL-SUPER, ZPWY-VAL-O, and ZPWY-VAL-A are some of the values associated with the private field type ZPWY-DDL-SECURITY-VALUE.

The private field types are described in the following paragraphs and share the following features:

•

They are associated with the predefined values described. Values that appear in only one field are listed and described with the command in which they appear. Values that appear in multiple fields are listed and described here.

•

They are used only as a basis for defining other types. These types indicate the structure or type of part s of other types, but your progra ms should not have to refer to them directly. Therefore, to save space, the Pathway subsystem does not produce programming-language declarations for them.

ZPWY-DDL-CHARSET-VALUE

ZPWY-DDL-CHARSET-VALUE designates the USASCII or a foreign character set supported for a device.

The character set is specified in the OBJECT-COMPUTER paragraph of the associated SCREEN COBOL program. The following values are

valid:

def ZPWY-DDL-CHARSET-VALUE token-type ZSPI-DDL-ENUM.

ZPWY-VAL-USASCII US ASCII ZPWY-VAL-FRANCAIS-AZ French (AZERTY) ZPWY-VAL-FRANCAIS-QZ French (QWERTY) ZPWY-VAL-DEUTSCH German/Austrian ZPWY-VAL-ESPANOL Spanish

ZPWY-VAL-UK

United Kingdom

ZPWY-VAL-SVENSK-SUOMI

Swedish/Finnish

ZPWY-VAL-DANSK-NORSK

Danish/Norwegian

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-23

ZPWY-DDL-FRZSTATETERM-VALUE

ZPWY-DDL-FRZSTATETERM-VALUE specifies the freeze status of a TERM object preventing a server process from being frozen.

Values are described with ZPWY-MAP-STATUS-TERMFREEZE on page6-79.

ZPWY-DDL-NONSTOP-VALUE

ZPWY-DDL-NONSTOP-VALUE designates whether the TCP runs with a backup process.

The following values are valid:

If you do not assign a value to this field, the default is ZPWY-VAL-NONSTOP1.

ZPWY-DDL-OBJSTATE-VALUE

ZPWY-DDL-OBJSTATE-VALUE provides the state of a TCP or TERM object.

The following values are valid:

ZPWY-DDL-POP-VAL UE

ZPWY-DDL-POP-VALUE provides the name of the currently executing SCREEN COBOL instruction in response to a STATUS TERM command. This is internal information.

def ZPWY-DDL-FRZSTATETERM-VALUE token-type ZSPI-DDL-ENUM.

def ZPWY-DDL-NONSTOP-VALUE token-type ZPWY-DDL-ENUM.

ZPWY-VAL-NONSTOP0 Directs the TCP not to run with a backup process. ZPWY-VAL-NONSTOP1 Directs the TCP to run with a backup process.

def ZPWY-DDL-OBJSTATE-VALUE token-type ZSPI-DDL-ENUM.

ZPWY-VAL-STOPPED The object is stopped. ZPWY-VAL-PENDING The object is stopping. ZPWY-VAL-SUSPENDED The object is suspended. ZPWY-VAL-RUNNING The object is running.

def ZPWY-DDL-POP-VALUE token-type ZSPI-DDL-ENUM.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-24

ZPWY-DDL-SECURITY-VALUE

ZPWY-DDL-SECURITY-VALUE identifies the users who can issue commands that directly alter the state of Pathway subsystem objects.

The following values are valid:

ZPWY-DDL-TCPQUALSTATE-VALUE

ZPWY-DDL-TCPQUALSTATE-VALUE specifies the state of a TCP.

ZPWY-DDL-TCPQUALSTATE-VALUE is defined as an integer pair. The first integer can have the following values:

The second integer can have the following values:

ZPWY-DDL-TERMPEND-VALUE

ZPWY-DDL-TERMPEND-VALUE specifies the reason a TERM object is pending.

def ZPWY-DDL-SECURITY-VALUE token-type ZSPI-DDL-ENUM.

ZPWY-VAL-A Any local user ZPWY-VAL-G A group member or owner ZPWY-VAL-O An owner on ly ZPWY-VAL-N Any local or remote user ZPWY-VAL-C Any member of owner’s community ZPWY-VAL-U Any member of owner’s user class ZPWY-VAL-SUPER A local super ID

def ZPWY-DDL-TCPQUALSTATE-VALUE type ZSPI-DDL-INT-PAIR.

ZSPI-VAL-TRUE Selects objects that are in the specified state (that is, the

PENDING, RUNNING, or STOPPED state).

ZSPI-VAL-FALSE Selects object s that are in the state t hat i s th e comp lemen t of

the specified state. For example, the complement of the PENDING state is NOT PENDING; that is, either RUNNING or STOPPED.

ZPWY-VAL-PENDING The TCP is stopping. ZPWY-VAL-RUNNING The TCP is running and can control TERM objects. ZPWY-VAL-STOPPED The TCP is stopped.

def ZPWY-DDL-TERMPEND-VALUE type ZSPI-DDL-ENUM.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-25

ZPWY-DDL-TERMWAIT-VALUE

Values are described under ZPWY-MAP-ST ATUS-TERMDETAIL on page 6-73.

ZPWY-DDL-TERMWAIT-VALUE

ZPWY-DDL-TERMWAIT-VALUE specifies the reason a TERM object is waiting.

Values are described under ZPWY-MAP-ST ATUS-TERMDETAIL on page 6-73.

ZPWY-DDL-TRMQUALSTATE-VALUE

ZPWY-DDL-TRMQUALSTATE-VALUE specifies the state of a TERM object.

ZPWY-DDL-TRMQUALSTATE-VALUE is defined as an integer pair. The first integer can have the following values:

The second integer can have the following values:

Simple Tokens

A simple token has a value consisting of a single field or a fixed structure. The only simple tokens defined with private Pathway token codes are:

•

The error tokens REQobjecttypeNAME and objecttypeNAME

•

Event subjects and tokens

For more information on error and event tokens, see Section 11, TCP Event

Messages, in this manual and see the TS/MP Management Programming Manual.

def ZPWY-DDL-TERMWAIT-VALUE type ZSPI-DDL-ENUM.

def ZPWY-DDL-TRMQUALSTATE-VALUE type ZSPI-DDL-INT-PAIR.

ZSPI-VAL-TRUE Selects objects that are in the specified state (that is, the

RUNNING, STOPPED, or SUSPENDED state).

ZSPI-VAL-FALSE Selects objects that are in the state that is the

complement of the specified state. For example, the complement of the RUNNING state is the STOPPED or SUSPENDED state.

ZPWY-VAL-RUNNING The TERM object is running. ZPWY-VAL-STOPPED The TERM object is stopped. ZPWY-VAL-SUSPENDED The TERM object is suspended.

ZPWY-DDL- Definitions

NonStop Pathway/iTS Management Programming Manual —426749-002

5-26

Simple T ok ens

HP NonStop Pathway/iTS Programming Manual

Specifications and Main Features

Frequently Asked Questions

User Manual