HP NonStop TMF Programming Manual

HP NonStop TMF Management Programming Manual

Abstract

This manual is for system and application programmers. It provides system-specific information about the management programming interfaces to the HP NonStop™ Transaction Management Facility (TMF). These interfaces are based on the Subsystem Programmatic Interface (SPI) and the Event Management Service (EMS). They allow applications to send commands to, and monitor events reported by, TMF 3.6.

Product Version

TMF H01

Supported Release Version Updates (RVUs)

This publication supports J06.03 and all subsequent J-series RVUs and H06.06 and all subsequent H-series RVUs, until otherwise indicated by its replacement publications.

Part Number Published

540140-008 February 2013

Document History

Part Number Product Version Published

540140-003 TMF H01 April 2006 540140-004 TMF H01 May 2007 540140-005 TMF H01 February 2009 540140-006 TMF H01 August 2010 540140-007 TMF H01 February 2011 540140-008 TMF H01 Februrary 2013

Legal Notices

Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Export of the information contained in this publication may require authorization from the U.S. Department of Commerce.

Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation. Intel, Itanium, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its

subsidiaries in the United States and other countries. Java® is a registered trademark of Oracle and/or its affiliates. Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks and IT DialTone and The

Open Group are trademarks of The Open Group in the U.S. and other countries. Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the

Open Software Foundation, Inc.

OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material.

© 1987, 1988, 1989 Carnegie-Mellon University. © 1989, 1990, 1991 Digital Equipment Corporation. © 1985, 1988, 1989, 1990 Encore Computer Corporation. © 1988 Free Software Foundation, Inc. © 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. © 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corpor a tion. © 1988, 1989 Massachusetts Institute of Technology. © 1988, 1989, 1990 Mentat Inc. © 1988 Microsoft Corporation. © 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. © 1990, 1991 Siemens Nixdorf Informationssysteme AG. © 1986, 1989, 1996, 1997 Sun Microsystems, Inc. © 1989, 1990, 1991 Transarc Corporation.

This software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. © 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California.

Printed in the US

HP NonStop TMF Management Programming Manual

Index Tables

Legal Notices What’s New in This Manual vii

Manual Information vii New and Changed Information viii

About This Manual xi

Who Should Read This Manual xii How This Manual is Organized xii TMF Documentation xiii Other Documentation xiv Notation Conventions xiv HP Encourages Your Comments xv

1. Introduction to TMF

Management Programming for TMF 1-1

What is Management Programming? 1-1 How Does Management Programming Apply to TMF? 1-2 Why Use Management Programming for TMF? 1-2

TMF Basic Concepts

Transactions Audit Trails Database Tables and Files 1-5 Recovery Processes 1-5

Management Interfaces

TMFCOM EMS 1-6 FUP

1-7

1-3

1-6

1-3

1-6

PATHCOM Pathway SCREEN COBOL Operating System Procedure Calls TACL 1-11 Measure Subsystem

1-8

Hewlett-Packard Company—540140-008

1-9

1-10

1-11

Contents

1. Introduction to TMF (continued)

TMF Object Types 1-11 TMF Commands 1-12 TMF Event Messages 1-15

2. Communicating With the TMFSERVE Process

Communicating With the TMFSERVE Process 2-1 Starting and Opening TMFSERVE 2-2

Starting TMFSERVE 2-2 Startup Message 2-2 Opening TMFSERVE 2-2

Naming TMFSERVE 2-3 Closing TMFSERVE 2-3 Running an EMS Consumer Distributor 2-3

3. SPI Programming Considerations for TMF

Definition Files 3-1 Message Elements for TMF 3-3

Commands 3-3

Object Types 3-3

Object Names 3-4

Event Numbers 3-4

Other Tokens 3-4

Data Lists and Error Lists 3-4 Using SPI to Build Commands and Decode Responses 3-5

Building and Sending a Command Message

Discontinuing a Command in Progress 3-6

Receiving and Decoding a Response Message

Error Handling 3-7

Security Retrieving and Decoding Event Messages 3-8

Event-Management Considerations for TMF

Critical Events

3-8

3-10

3-5

3-6

3-9

Filters 3-10 Templates and Labels Naming Guidelines for Applications

4. Common Definitions

SPI Standard Definitions 4-1

Information Specific to TMF 4-3

HP NonStop TMF Management Programming Manual—540140-008

3-10

3-11

Contents

4. Common Definitions (continued)

EMS Standard Definitions 4-4 TMF Definitions 4-4

Buffer Declarations 4-5

Private Token and Field Types 4-6

Predefined Token and Field Values 4-11

Simple Tokens 4-11

Extensible Structured Tokens 4-11

Tokens in Event Messages 4-11

5. Commands and Responses

Command Summary 5-2 Command Descriptions 5-4 ABORT TRANSACTION 5-5 ADD AUDITTRAIL 5-8 ADD DATAVOLS 5-13 ADD DUMPS 5-17

4. Common Definitions (continued)

ADD MEDIA 5-20 ADD RESOURCEMANAGER 5-23 ALTER AUDITDUMP 5-26 ALTER AUDITTRAIL 5-31 ALTER BEGINTRANS 5-38 ALTER CATALOG 5-43 ALTER DATAVOLS 5-45 ALTER DUMPS 5-47 ALTER MEDIA ALTER PROCESS ALTER TMF

5-49

5-51

5-56

CANCEL OPERATION 5-60 CLOSE RESOURCEMANAGER 5-61 DELETE CATALOG DELETE DATAVOLS

5-63

5-64

DELETE DUMPS 5-66 DELETE MEDIA DELETE RESOURCEMANAGER DELETE TMF DELETE TRANSACTION

5-68

5-70

5-73

5-74

DISABLE AUDITDUMP 5-76 DISABLE BEGINTRANS

HP NonStop TMF Management Programming Manual—540140-008

5-78

iii

Contents

5. Commands and Responses (continued)

DISABLE DATAVOLS 5-79 DUMP FILES 5-81 ENABLE AUDITDUMP 5-88 ENABLE BEGINTRANS 5-90 ENABLE DATAVOLS 5-91 INFO ATDUMPDM 5-93 INFO ATVOLUME 5-95 INFO AUDITDUMP 5-98 INFO AUDITTRAIL 5-101 INFO BEGINTRANS 5-105 INFO CATALOG 5-109 INFO DATAVOLS 5-111 INFO DUMPS 5-114 INFO MEDIA 5-121 INFO PROCESS 5-124 INFO RESOURCEMANAGER 5-128 INFO TMF 5-131 LIST AUDITTRAIL 5-134 NEXT AUDITTRAIL 5-136 RECOVER FILES 5-137 RELOCATE DISKDUMPS 5-145 RESOLVE TRANSACTION 5-148 START TMF 5-150 STATUS ATFILE 5-153 STATUS AUDITDUMP 5-158 STATUS AUDITTRAIL

5-161

STATUS BEGINTRANS 5-166 STATUS CATALOG 5-169 STATUS DATAVOLS STATUS OPERATION

5-171

5-177

STATUS RESOURCEMANAGER 5-181 STATUS RMTRANSBRANCHES STATUS TMF

5-190

5-186

STATUS TMFSERVER STATUS TRANSACTION STATUS TRANSACTIONCHILDREN 5-205 STOP TMF

5-207

HP NonStop TMF Management Programming Manual—540140-008

5-195

5-198

Contents

6. Event Messages

Common Tokens in Event Messages 6-1

Unconditional Tokens 6-2

Conditional Tokens 6-3 Obtaining TMF Event Messages 6-4 Sources of TMF Event Messages 6-4

TMP Event Messages 6-5

TMFMON Event Messages 6-13

Recovery Event Messages 6-13

TMF Dump/Restore Event Messages 6-16

TMF Catalog Event Messages 6-17 Event-Management Programming for TMF 6-18

Console Printing 6-19

Subsystem ID 6-19

Action Events 6-19

Buffer Size 6-19

6. Event Messages

Event Filtering 6-19 Descriptions of Event Messages 6-19

7. Error and Warning Messages

Error Information and Failure Data Capture 7-2 Errors 7-3 Archive Tape Errors and Warnings 7-55 Dump/Restore Errors and Warnings 7-65 Audit Reading Exceptions 7-81

A. TMF Configuration Limits and Defaults Index

Tables

Table 1-1. FUP Commands for Designating Audit Files 1-7 Table 1-2. PATHCOM Commands for Configuring TMF Options 1-8 Table 1-3. Table 1-4.

Pathway SCREEN COBOL Statements 1-9

Pathway SCREEN COBOL Registers 1-9 Table 1-5. Table 1-6. Table 1-7. TMFCOM Commands and Equivalent Programmatic Commands 1- 13 Table 3-1. Table 4-1. SPI Standard Definitions for Header Tokens 4-2

System Procedure Calls 1-10

TACL Built-In Functions 1-11

File-System Errors Returned by TMFSERVE 3-8

HP NonStop TMF Management Programming Manual—540140-008

Contents

Tables (continued)

Table 4-2. SPI Standard Definitions for Other Simple Tokens 4-2 Table 4-3. SPI Standard Definitions for Special Tokens 4-2 Table 4-4. SPI Standard Definitions for Token Types 4-2 Table 4-5. SPI Standard Definitions for Structures 4-3 Table 4-6. SPI Standard Definitions for Value Names 4-3 Table 4-7. EMS Standard Definitions for Header Tokens 4-4 Table 4-8. EMS Standard Definition for Data-Portion Tokens 4-4 Table 4-9. TMF Buffer Declarations 4-5 Table 4-10. TMF Private Token and Field Types 4-5 Table 4-11. TMF Predefined Token and Field Values 4-5 Table 5-1. TMF Commands, by Command 5-2 Table 5-2. TMF Commands, by Object 5-3 Table 6-1. TMP Event Messages 6-5 Table 6-2. TMFMON Event Messages 6-13 Table 6-3. Recovery Event Messages 6-13

Tables (continued)

Table 6-4. TMF Dump/Restore Event Messages 6-16 Table 6-5. TMF Catalog Event Messages 6-17 Table A-1. TMF Global Limits and Defaults A-1 Table A-2. Audit Trail Limits and Defaults A-1 Table A-3. Transaction Limits and Defaults A-2 Table A-4. Audit Dump and Online Dump Limits and Defaults A-3 Table A-5. Resource Manager Limits and Defaults A-3 Table A-6. Process Limits and Defaults A-3 Table A-7. Default Program File Names for Processes A-5

HP NonStop TMF Management Programming Manual—540140-008

What’s New in This Manual

Manual Information

HP NonStop TMF Management Programming Manual

Abstract

Product Version

TMF H01

Supported Release Version Updates (RVUs)

This publication supports J06.03 and all subsequent J-series RVUs and H06.06 and all subsequent H-series RVUs, until otherwise indicated by its replacement publications.

Part Number Published

540140-008 February 2013

Document History

Part Number Product Version Published

540140-003 TMF H01 April 2006 540140-004 TMF H01 May 2007 540140-005 TMF H01 February 2009 540140-006 TMF H01 August 2010 540140-007 TMF H01 February 2011 540140-008 TMF H01 Februrary 2013

HP NonStop TMF Management Programming Manual—540140-008

vii

What’s New in This Manual

New and Changed Information

Changes to the H06.26/J06.15 manual:

Added the following event messages event Messages:



531: ZTMF-EVT-BTN-Registered on page 6-452



532: ZTMF-EVT-BTN-NotRegistered on page 6-453



533: ZTMF-EVT-BTN-DeRegistering on page 6-454



534: ZTMF-EVT-BTN-DeRegistered on page 6-455



535: ZTMF-EVT-BTN-ImpExportFailed on page 6-456



Changes to the H06.22/J06.11 manual:

Updated the description of ZMaxPioPerBuffer on page 4-9.



New and Changed Information

Added the following event messages in Table 6-1, TMP Event Messages:



480: ZTMF-EVT-TransPerCpu-Exceeded on page 6-11



481: ZTMF-EVT-NetTrnsPerCpu-Xceeded on page 6-12



499: ZTMF-EVT-OldTransId on page 6-12



Added 480: ZTMF-EVT-TransPerCpu-Exceeded on page 6-447.



Added 481: ZTMF-EVT-NetTrnsPerCpu-Xceeded on page 6-448.



Added 499: ZTMF-EVT-OldTransId on page 6-451.



Changes to the H06.21/J06.10 Manual

Supported release statements have been updated to include J-series RVUs.



Added the following fields in the ZTMF-MAP-Alter-BeginTrans token of the



ALTER BEGINTRANS command:

ZThreshAutoIncrease



ZThreshLowerLimit



ZThreshIncrAmount



ZThreshNumberOfIncr



Added the following fields in the ZTMF-MAP-Info-BeginTrans token of the



INFO BEGINTRANS command:

ZThreshAutoIncrease



ZThreshLowerLimit



HP NonStop TMF Management Programming Manual —540140-008

viii

What’s New in This Manual

ZThreshIncrAmount



ZThreshNumberOfIncr



Added new tokens in the following commands:



DUMP FILES on page 5-84



INFO DUMPS on page 5-116



RECOVER FILES on page 5-140



Added new tokens in the following event messages:



78: ZTMF-EVT-Tx-Abort-ProcFail on page 6-26



288: ZTMF-EVT-TransAutoAborted on page 6-297



295: ZTMF-EVT-TransHung on page 6-307



296: ZTMF-EVT-TransAbort on page 6-308



297: ZTMF-EVT-DownNode on page 6-309



Changes to the H06.21/J06.10 Manual

Added the following event messages in Table 6-1, TMP Event Messages:



447: ZTMF-EVT-AbortTxNodeDownRev on page 6-11



475: ZTMF-EVT-TmpNet-UnSup-Msg on page 6-11



476: ZTMF-EVT-TmpNet-Msg-Drop on page 6-11



482: ZTMF-EVT-ThreshLowerLimXceeded on page 6-12



485: ZTMF-EVT-ATOVThresholdExceed on page 6-12



Added 447: ZTMF-EVT-AbortTxNodeDownRev on page 6-415.



Added 475: ZTMF-EVT-TmpNet-UnSup-Msg on page 6-445.



Added 476: ZTMF-EVT-TmpNet-Msg-Drop on page 6-446.



Added 482: ZTMF-EVT-ThreshLowerLimXceeded on page 6-449.



Added 485: ZTMF-EVT-ATOVThresholdExceed on page 6-450.



Added the following error numbers:



193 ZTMF-ERR-InvThreshAutoIncrease



194 ZTMF-ERR-InvThreshLowerLimit



195 ZTMF-ERR-InvThreshIncrAmount



196 ZTMF-ERR-InvThreshNumberOfIncr



HP NonStop TMF Management Programming Manual —540140-008

What’s New in This Manual

Changes in the earlier version of the Manual

This is the third edition of the HP NonStop TMF Management Programming Manual. It has been updated to support the H06.10 release version update (RVU) of the TMF product and to correct and clarify elements in the previous edition. The changes are as follows:

Section 4, Common Definitions



Altered the following token description:

ZTMF-TYP-TmpWaitTimer on page 4-9

Section 7, Error and Warning Messages



Altered the following error message description:

481 ZTMF-ERR-InvTmpWaitTimer on page 7-46

HP NonStop TMF Management Programming Manual —540140-008

About This Manual

This manual provides subsystem-specific information about the management programming interfaces to the HP NonStop Transaction Management Facility (TMF) on HP NonStop servers. These interfaces are based on the Subsystem Programmatic Interface (SPI) and the Event Management Service (EMS). They allow applications to send commands to, and monitor events reported by, TMF.

This manual serves as both a reference manual and a programmer’s guide. It does the following:

Explains the architecture of TMF and how a management application fits into that



architecture Explains how to communicate with TMF through the TMFSERVE process



Provides management programming considerations for TMF



Gives a complete reference to the contents of all tokens, token and field values,



commands, responses, event messages, and error lists defined by TMF

To learn more about this manual, read the following topics:

Topic Page

Who Should Read This Manual xii How This Manual is Organized xii TMF Documentation xiii Other Documentation xiv Notation Conventions xiv

HP NonStop TMF Management Programming Manual—540140-008

About This Manual

Who Should Read This Manual

You should read this manual if you are an experienced application programmer in one of the following categories:

A Transaction Application Language (TAL), C, C++, or COBOL85 programmer



writing applications that need to control or monitor TMF A TACL user writing macros or routines that control or monitor TMF



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

Basic NonStop system architecture



Programming for the HP NonStop OS



Programming using TAL, TACL, C, C++, or COBOL85



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



in the “Summary of DDL for SPI” appendix in the SPI Programming Manual.

Who Should Read This Manual

The Distributed Systems Management (DSM) facilities



The tasks necessary for managing TMF



How This Manual is Organized

In this manual, Sections 1 through 3 give background information and programming considerations, including the following:

The architecture of TMF and how a management application fits into it (Section 1)



The types of objects managed by TMF and the operations necessary to manage



these objects (Section 1) The kinds of events reported by TMF (Section 1)



How to set up communications with TMF, including how to start the TMFSERVE



process (Section 2) Programming considerations for management applications that manage TMF



(Section 3)

Sections 4 through 7 provide reference information, as follows:

Subsystem-specific information about tokens, token values, and related definitions



defined by other sources (such as SPI and EMS) and used by the DSM interfaces to TMF (Section 4)

Descriptions of tokens, token values, and related definitions defined by TMF



(Section 4 Detailed descriptions of all programmatic commands that can be directed to TMF



and their corresponding responses from TMF (Section 5

)

HP NonStop TMF Management Programming Manual—540140-008

)

xii

About This Manual

Detailed descriptions of all event messages than can be returned by TMF (Section



Detailed descriptions of all error and warning messages than can be returned by



TMF (Section 7)

Appendix A, TMF Configuration Limits and Defaults provides summarizes various TMF

limits.

TMF Documentation

Readers of this manual might also wish to refer to documentation describing the TMF product and other related products.

Audience Title

All readers TMF Introduction

TMF Glossary

TMF Documentation

System managers and operators

Application programmers

TMF Planning and Configuration Guide TMF Operations and Recovery Guide TMF Reference Manual TMF Application Programmer’s Guide TMF Management Programming Manual (This manual)

Documentation Description

TMF Introduction



Read this manual first. It provides a general overview of TMF concepts and capabilities for business professionals, application designers and programmers, and system managers and administrators.

TMF Glossary



For the technical terms used in the TMF documentation set, see this manual. TMF Planning and Configuration Guide



Read this guide for information about how to plan, configure, and manage a TMF environment. This guide also describes how to move your applications between an earlier TMF product version and the current one.

TMF Operations and Recovery Guide



Read this guide for information about how to perform and monitor standard TMF operations, obtain online and audit dumps, and respond to a variety of TMF exception conditions.

HP NonStop TMF Management Programming Manual—540140-008

xiii

About This Manual

TMF Reference Manual



For information about how to use the TMFCOM command interface to TMF, see this manual. This manual includes syntax, cautionary considerations, and command examples for TMFCOM.

TMF Application Programmer’s Guide



Read this guide for information about how to design requester and server modules to run in the TMF programming environment. Also read it for information about a set of procedures that are helpful in examining the content of TMF audit trails.

Other Documentation

HP Tandem Advanced Command Language (TACL)



HP NonStop SQL Relational Database Management System



HP NonStop Transaction Services (TS/MP)



HP NonStop TUXEDO



Distributed Systems Management/Software Configuration Manager (DSM/SCM)



Event Management Service (EMS)



File Utility Program (FUP)



Measure Subsystem



Pathway/TS



Surveyor Subsystem



Various programming languages, including COBOL85, Pathway SCREEN COBOL,



FORTRAN, TAL, Pascal, C, C++, and SQL (NonStop SQL implementation).

Notation Conventions

Hypertext Links

Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example:

This feature is not configurable; if it causes transactions to be aborted that should not be aborted, you must increase audit trail capacity as described in Increasing

Audit Trail Capacity.

HP NonStop TMF Management Programming Manual—540140-008

xiv

About This Manual

Notation for Management Programming Interfaces

UPPERCASE LETTERS. Uppercase letters indicate names from definition files; enter these

names exactly as shown. For example:

ZCOM-TKN-SUBJ-SERV

lowercase letters.

Words in lowercase letters are words that are part of the notation, including Data Definition Language (DDL) keywords. For example:

token-type

Change Bar Notation

Change bars are used to indicate substantive differences between this edition of the manual and the preceding edition. 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 COBOL85 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.

HP Encourages Your Comments

HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to docsfeedback@hp.com.

Include the document title, part number, and any comment, error found, or suggestion for improvement you have concerning this document.

HP NonStop TMF Management Programming Manual—540140-008

About This Manual

HP Encourages Your Comments

HP NonStop TMF Management Programming Manual—540140-008

xvi

1 Introduction to TMF

TMF protects databases in online transaction processing (OLTP) environments. It does this by managing database transactions, keeping track of database activity through the use of audit trails, and providing database recovery methods. TMF performs its functions while sustaining high performance in a high-volume, distributed OLTP application environment.

To manage large systems or networks efficiently, it is beneficial to transfer many of the routine management tasks to the computer system or network itself. This manual describes how to design and code applications that manage TMF.

This section contains the following topics:

Management Programming for TMF on page 1-1



TMF Basic Concepts on page 1-3



Management Interfaces on page 1-6



TMF Object Types on page 1-11



TMF Commands on page 1-12



TMF Event Messages on page 1-15



Management Programming for TMF

TMF supports the Distributed Systems Management (DSM) facilities. In the context of DSM, a subsystem is a set of processes that manages a cohesive set of objects in the computer system. A subsystem can be managed by a person using an interactive text interface like TMFCOM or by a management program that automates operator functions using the Subsystem Programmatic Interface (SPI) to communicate with the TMFSERVE process.

What is Management Programming?

Management programming is a way to automate many routine management tasks and free human operators to do work requiring judgement and creativity.

Many tasks that a program can perform fall into one of two categories: control and inquiry, or event management. Control and inquiry tasks use commands to change or inquire about the configuration or status of objects in a system or network. Commands provide a two-way interface:

A human operator or application program sends a command to a subsystem.



The subsystem performs some action and returns a response to the operator or



application.

HP NonStop TMF Management Programming Manual—540140-008

1-1

Introduction to TMF

An event-management task retrieves information about important events that occur in a system and takes appropriate action in response to those events. Event messages provide a one-way interface:

Information flows from the subsystem to the operator or application program, but



no information flows in the other direction.

The programs that perform these functions are called management applications or programmed operators. A management application issues commands to and receives responses from subsystems, or retrieves event messages (or both) to help manage a system or a network of systems. A programmed operator is a management application that performs functions that might otherwise be performed by a human operator.

How Does Management Programming Apply to

How Does Management Programming Apply to TMF?

TMF supports both interactive and programmatic interfaces for commands and event messages. HP provides a number of DSM facilities to help you manage systems. The DSM facilities include:

TMF?

SPI (Subsystem Programmatic Interface)



An interface that is used to build and decode messages sent between management applications (requesters) and subsystem manager processes (servers, such as the TMFSERVE process).

EMS (Event Management Service)



A service that provides event message collection, logging, and distribution facilities. EMS includes printing and distributor processes that can print or display event messages for operators. TMF generates normal event messages.

The DSM programmatic interfaces for sending commands (control and inquiry) and retrieving event messages (event management) allow programs to perform the same kind of monitoring and control operations that users of TMFCOM and EMS printing and compatibility distributors can perform interactively. This manual describes the DSM programmatic interfaces to TMF.

Why Use Management Programming for TMF?

In some situations, it is desirable to use a programmatic interface, rather than an interactive interface, to manage a subsystem such as TMF. This is true for the following reasons:

It is efficient to transfer as many routine management tasks as possible to



programs running on the system, freeing operators and other system management personnel.

Information obtained through the programmatic interfaces can be used directly by



an application to determine how to proceed, to produce reports, and so forth.

An application that uses the programmatic interfaces to subsystems can perform tasks that once required the use of several different interactive interfaces. In addition, the

HP NonStop TMF Management Programming Manual —540140-008

1-2

Introduction to TMF

capability to write your own management applications allows you to tailor them to the needs and configuration of your system.

Examples of possible applications for using the programmatic interface to TMF are:

An application that checks the status of TMF and monitors the transaction rate at



each node of a network An application that monitors events generated by the TMF management process



pair (TMP) to determine if restore-audit files have been dumped successfully

TMF Basic Concepts

This section of the manual summarizes the most important concepts and components in TMF.

For a more detailed overview, see the TMF Introduction.

Transactions

TMF Basic Concepts

Fundamental to TMF is a programmatic construct called a transaction. A transaction is an explicitly delimited operation or set of related operations that alters the content of a database.

The range of a transaction is identified within the application program by a pair of statements:

BEGIN WORK and COMMIT WORK in the NonStop SQL/MP environment



BEGIN-TRANSACTION and END-TRANSACTION in other programming



environments

All operations within the range of a transaction are treated by TMF as a single unit: either all of the changes performed by a transaction are made permanent (the transaction is committed) or none of the changes are made permanent (the transaction is aborted). If a failure occurs during the execution of a transaction, whatever partial changes were made to the database are backed out, leaving the database in a consistent state.

Audit Trails

Before a transaction permanently commits its changes to the database, information about the affected database rows or records is written to the audit trail. An audit trail is a series of files containing audit records and TMF control records.

Audit records contain before-images and after-images of all database rows or records affected by a particular operation; it is typical to have several audit records per transaction.

Control records identify transaction-related events such as transaction committed, transaction aborted, undo incomplete, subsystem configuration, and state information.

HP NonStop TMF Management Programming Manual—540140-008

1-3

Introduction to TMF

Together, TMF control records constitute a chronological record of all transactionrelated activities.

If the database is distributed over a network, separate audit trails are maintained on each node where the database resides. Before-images and after-images are written to the audit trail on the same node as reside the rows or records changed by the transaction.

The Master Audit Trail

There is one master audit trail (MAT) in each TMF system. The MAT contains all of the TMF control records and usually also contains audit records for a set of data volumes specified by the TMF system manager.

Auxiliary Audit Trails

Application environments with unusual performance or capacity demands can sometimes benefit from the use of additional audit trails, called auxiliary audit trails. These audit trails contain audit records in addition to those in the MAT; they do not duplicate the MAT’s audit records.

Audit Trails

Active-Audit Volumes

When you configure an audit trail, you specify the names of the disk volumes that will receive audit information. These are referred to as active-audit volumes. You can add and delete active-audit volumes without stopping TMF or your applications. An active-audit volume cannot also be a data volume.

Overflow-Audit Volumes

When you configure an audit trail, you can also specify disk volumes to use if all restore-audit files become filled. These are referred to as overflow-audit volumes. They can be any disk volumes in the system (including data volumes or active-audit volumes).

Audit Dumps

Audit dumps preserve copies of restore-audit files for file recovery. Audit dumps copy

restore-audit files from active-audit volumes to tape or disk. Audit-trail files remain either on active-audit volumes or on the audit dump medium until they are no longer needed for recovery.

Restore-Audit Volumes

When you configure an audit trail, you can also specify disk volumes for receiving copies of restore-audit files restored from an audit dump during a recovery. These are referred to as restore-audit volumes. They can be any disk volumes in the system (including data volumes or active-audit volumes).

HP NonStop TMF Management Programming Manual —540140-008

1-4

Introduction to TMF

Database Tables and Files

You can use TMF to protect NonStop SQL/MP t ables and Enscribe files.

Data Volumes

When configuring your TMF environment, you must identify all disk volumes that will contain audited tables or files. These are referred to as data volumes.

To generate audit information, a database operation must occur within the bounds of a TMF transaction and the table or file being manipulated must reside on a configured TMF data volume.

Online Dumps

Online dumps are copies of audited database tables and files for use by the file

recovery process. If your database is damaged, the file recovery process can restore online dump files to disk and then apply the restore-audit images to reconstruct the database tables and files. Online dumps can be made while transactions are being processed by your applications.

Database Tables and Files

Recovery Processes

The TMF recovery processes are backout, volume recovery, and file recovery. They are responsible for recovering from transaction, media, and system failures.

Backout

The TMF backout process undoes the effects of aborted transactions. It is created when you start TMF and automatically invoked whenever a transaction aborts.

Volume Recovery

The TMF volume recovery process recovers data volumes that had one or more tables or files open when a media or system failure occurred. It uses information in the audit trail to back out transactions that were incomplete (not yet committed or aborted) at the time of the failure. The TMF management process automatically invokes the volume recovery process in response to START TMF and ENABLE DATAVOLS commands or when a data volume comes up.

File Recovery

The TMF file recovery process uses online dumps (archived copies of database tables and files) and audit dumps (archived copies of restore-audit files) to restore tables and files to a consistent state after an accidental purge or a media failure. (File recovery is also used to reorder a database to a previous date and time, after a problem with the application occurs.) Volume recovery usually makes this

HP NonStop TMF Management Programming Manual—540140-008

1-5

Introduction to TMF

unnecessary; however, file recovery would be required, for example, if a media failure involves a nonmirrored volume, or both volumes of a mirrored pair.

File recovery is not invoked automatically; you have to issue a RECOVER FILES command, specifying the tables or files you want recovered.

Management Interfaces

Your management application can manage and operate TMF programmatically using Subsystem Programmatic Interface (SPI) commands and responses to interface with the TMFSERVE process.

The programmatic interface to TMF is based on SPI, the TMFSERVE process, and the Event Management System (EMS). SPI builds and decodes messages that are needed by TMF to communicate with management applications. The TMFSERVE process provides access to TMF through SPI, and EMS collects event messages from TMF and distributes the messages to the management application.

In addition to the programmatic management interface, you can access TMF through software products such as the following.

Management Interfaces

TMFCOM

TMFCOM is the TMF’s interactive command interface and provides interactive

commands for all TMF operations required by system managers and operators. TMFCOM commands allow you to manage, control, and retrieve information about TMF objects such as dumps, files, and the subsystem itself.

For detailed information about TMFCOM and TMFCOM commands, see the TMF Reference Manual.

EMS

TMF sends event messages to the Event Management Service (EMS). The EMS collects event messages from reporting processes and subsystems and then selectively distributes those messages to various destinations. Such destinations range from a local operator console device to a management application running on a remote system. See Section 6, Event Messages for more information about EMS, or see the EMS Manual.

HP NonStop TMF Management Programming Manual —540140-008

1-6

Introduction to TMF

FUP

The File Utility Program (FUP) also provides an interactive management interface. It performs operations on files stored on disk drives and tape volumes. With FUP, for example, you can create, purge, duplicate, and display files, alter file characteristics, and load data into files.

Through FUP commands, you can request several TMF operations. In particular, you can designate files to be audited by TMF or you can change such a designation. The FUP commands for Enscribe files related to these operations are listed in Table 1-1. The equivalent NonStop SQLCI commands also apply.

Table 1-1. FUP Commands for Designating Audit Files

Command Description

ALTER Changes attributes of an existing file. CREATE Creates a file. INFO Reports information about a file, including whether the redo or undo p hases of

FUP

file recovery are pending. RESET Resets to the default attribute values used for CREATE. SET Sets attribute values for files created when the CREATE command is issued.

Use the following FUP command options to indicate audited files:

AUDIT designates the file as audited by TMF.



NO AUDIT designates the file as nonaudited (default).



AUDITCOMPRESS designates audit compression for an audited file. Audit



compression is the writing of before-images and after-images to restore-audit files so that only the changed portions of records are written.

NO AUDITCOMPRESS designates no audit compression for an audited file



(default).

For further information about FUP commands, see the File Utility Program (FUP)

Reference Manual.

HP NonStop TMF Management Programming Manual—540140-008

1-7

Introduction to TMF

PATHCOM

The Pathway transaction processing system enables you to create and manage online transaction processing applications. In particular, Pathway controls the flow of transactions between the input/output devices and the database used by an application.

Pathway systems that use audited files must be configured to define how TMF works with server classes and terminals, and how failures are treated. Use the Pathway PATHCOM interactive command interpreter to configure and manage a Pathway system. Table 1-2 lists the PATHCOM commands that have TMF-related options.

Table 1-2. PATHCOM Commands for Configuring TMF Options

Command Description

SET PATHWAY Specifies a global transaction restart limit, defining the maximum

SET PROGRAM Specifies whether TMF runs along with the program.

PATHCOM

number of times a failed transaction can be restarted automatically.

ADD SERVER Defines server classes that can update database files audited by TMF. ALTER SERVER Redefines server classes that can update database files audited by

TMF.

RESET SERVER Redefines server classes that can update database files audited by

TMF. SET SERVER Redefines server classes that can update database files audited TMF. ADD TERM Specifies, in terminal program units, which program units are not

configured to operate in transaction mode with TMF. ALTER TERM Respecifies, in terminal program units, which program units are not

configured to operate in transaction mode with TMF. RESET TERM Respecifies, in terminal program units, which program units are not

configured to operate in transaction mode with TMF. SET TERM Respecifies, in terminal program units, which program units are not

configured to operate in transaction mode with TMF. STATUS TERM Reports the configuration of each terminal.

For further information about PATHCOM commands, see the Pathway PATHCOM

Reference Manual.

HP NonStop TMF Management Programming Manual —540140-008

1-8

Introduction to TMF

Pathway SCREEN COBOL

The SCREEN COBOL programming language allows programmers to write client processes that communicate with operator terminals and intelligent input/output devices, and that send data to server processes that manage application databases, all under the control of Pathway. SCREEN COBOL programmers use special statements and registers for accessing TMF. Table 1-3 lists statements in the SCREEN COBOL language that manage transactions programmatically.

Table 1-3. Pathway SCREEN COBOL Statements

Statement Description

ABORT-TRANSACTION Cancels the transaction of a terminal operating in transaction

mode. All database updates made to audited files during the transaction are backed out and no attempt is made to restart the transaction.

BEGIN-TRANSACTION Marks the beginning of a series of operations that are to be

treated as a single transaction. When this statement executes, the terminal enters transaction mode.

Pathway SCREEN COBOL

END-TRANSACTION Marks the completion of a sequence of operations that are

treated as a single transaction. When this statement executes, the terminal leaves transaction mode.

RESTART-TRANSACTION Is equivalent to an ABORT-TRANSACTION statement

followed by a BEGIN-TRANSACTION statement.

For more information about these statements, see the Pathway SCREEN COBOL

Reference Manual.

Table 1-4 lists the SCREEN COBOL language registers that manage transactions

programmatically.

Table 1-4. Pathway SCREEN COBOL Registers

RESTART-COUNTER Contains the number of times a transaction has been restarted

during transaction mode. TERMINATION-STATUS Communicates an error number, further describing the error. TRANSACTION-ID Contains the value of the transaction identifier that the TMF

subsystem assigns when the SCREEN COBOL BEGIN-

TRANSACTION statement executes.

For more information about these registers, see the Pathway SCREEN COBOL

Reference Manual.

HP NonStop TMF Management Programming Manual—540140-008

1-9

Introduction to TMF

Operating System Procedure Calls

Through its Guardian application program interface (API), the NonStop operating system provides procedure calls you can include in application programs written in any of the following languages: C, C++, COBOL, FORTRAN, Pascal, and the native Transaction Application Language (TAL). In most cases, the code for the procedures is made available through external declaration files provided with the compiler.

Through the procedure calls, you can request many system services. Table 1-5 lists a few of the calls that you can apply to TMF transactions.

Table 1-5. System Procedure Calls

Procedure Call Description

ABORTTRANSACTION Cancels a transaction. When a process calls this

procedure, TMF backs out the database changes associated with the current transaction.

ACTIVATERECEIVETRANSID Permits multithreaded servers to read requests from

$RECEIVE before replying to previously read $RECEIVE requests.

Operating System Procedure Calls

BEGINTRANSACTION Starts a new transaction and creates a new

transaction identifier for the process.

COMPUTETRANSID Converts the individual numeric components of a

transaction identifier to a transaction identifier in internal format.

ENDTRANSACTION Commits the database changes associated with a

transaction identifier. If the action completes successfully, the changes made by the transaction are permanent.

FILE_GETINFO[LIST][BYNAME] Returns information about a file, including whether the

redo or undo phases of file recovery are required to return the file to a consistent state.

GETTMPNAME Obtains the name of the transaction management

process.

GETTRANSID Returns the current transaction identifier of the calling

process.

INTERPRETTRANSID Converts a transaction identifier in internal format to

its numeric components.

RESUMETRANSACTION Restores as current a transaction identifier created by

a previous call to BEGINTRANSACTION.

STATUSTRANSACTION Returns the transaction state of the current

TEXTTOTRANSID Converts a transaction identifier from its external

TRANSIDTOTEXT Converts a transaction identifier in internal format to

HP NonStop TMF Management Programming Manual —540140-008

transaction or that of a specified transaction.

ASCII form to internal format.

its external ASCII form.

1-10

Introduction to TMF

For further information about system procedure calls, see the Guardian Procedure Calls Reference Manual. For information about how to issue these calls from the language you are using, see that language’s reference manual.

TACL

The Tandem Advanced Command Language (TACL) provides the Guardian environment’s command interface to the operating system. TACL features built-in functions that can be used for constructing programmatic routines and macros.

Table 1-6 lists some of the functions that call operating system procedures for

performing TMF operations.

Table 1-6. TACL Built-In Functions

Function Description

#ABORTTRANSACTION Invokes the ABORTTRANSACTION system procedure. #BEGINTRANSACTION Invokes the BEGINTRANSACTION system procedure. #COMPUTETRANSID Invokes the COMPUTETRANSID system procedure.

TACL

#ENDTRANSACTION Invokes the ENDTRANSACTION system procedure. #FILEINFO Invokes the FILE_GETINFO[LIST][BYNAME] system

#INTERPRETTRANSID Invokes the INTERPRETTRANSID system procedure.

For further information about TACL built-in functions, see the TACL Reference Manual.

Measure Subsystem

The Measure performance analysis subsystem is used to collect performance statistics on a wide range of system resources. With Measure, you can gather data from system components, network components, and applications. Among these elements, Measure allows you to obtain and display performance statistics for TMF. See the Measure Reference Manual and the Measure User’s Guide for descriptions of these statistics and the TMF entities to which they apply.

TMF Object Types

Like all subsystems that support DSM, TMF defines a set of object types—the types of objects that can be managed by TMF. The object types for the TMFCOM interactive interface are not exactly the same as those for the TMFSERVE programmatic interface. The object types for the programmatic interface are as follows:

procedure.

ATDUMPDM ATVOLUME AUDITDUMPFILES AUDITTRAIL BEGINTRANS CATALOG DATAVOLS DISKDUMPS

HP NonStop TMF Management Programming Manual—540140-008

1-11

Introduction to TMF

DUMPS MEDIA PROCESS RESOURCEMANAGER (or RM) TMF TMFSERVER TRANSACTION TRANSACTIONCHILDREN

TMF Commands

Your management application can perform the following functions by sending commands to the TMFSERVE process:

Add and delete audit trails, data volumes, dump files, and tape volumes in a TMF



system Start and stop TMF



Start and stop transaction processing



TMF Commands

Display the status of TMF and related objects



Configure audit trails for dumping



Dump audited files



Control specific transactions



Change certain characteristics, or attributes, of restore-audit files, dump files,



catalogs, data volumes, and TMF processes Obtain information about the current configuration of the subsystem, its processes,



restore-audit files, dump files, data volumes, catalogs, and tape volumes

The TMF commands used in management applications (programmatic commands) are similar to the TMFCOM commands used by operators. Both command types combine an action element, such as ADD, with an object element, such as DATAVOLS, but the interactive TMFCOM commands use keywords and the TMF programmatic commands use codes. Each programmatic command corresponds to an interactive command that you can issue through TMFCOM, although there is not a direct one-to-one correspondence between interactive and programmatic commands, and there are no programmatic equivalents for some of the TMFCOM commands. Table 1-7 TMFCOM commands and their programmatic counterparts.

shows the

HP NonStop TMF Management Programming Manual —540140-008

1-12

Introduction to TMF

Table 1-7. TMFCOM Commands and Equivalent Programmatic Commands (page1of2)

TMF Commands

Interactive (TMFCOM) Command

Interactive (TMFCOM) Object Type

Programmatic Command

Programmatic Object Type

ABORT TRANSACTION ZTMF-CMD-ABORT ZTMF-OBJ-TRANSACTION ADD AUDITTRAIL ZTMF-CMD-ADD ZTMF-OBJ-AUDITTRAIL

DATAVOLS ZTMF-OBJ-DATAVOLS DUMPS ZTMF-OBJ-DUMPS RM ZTMF-OBJ-RM TAPEMEDIA ZTMF-OBJ-MEDIA

ALTER AUDITDUMP ZTMF-CMD-ALTER ZTMF-OBJ-AUDITDUMP

AUDITTRAIL ZTMF-OBJ-AUDITTRAIL BEGINTRANS ZTMF-OBJ-BEGINTRANS CATALOG ZTMF-OBJ-CATALOG DATAVOLS ZTMF-OBJ-DATAVOLS DUMPS ZTMF-OBJ-DUMPS PROCESS ZTMF-OBJ-PROCESS TAPEMEDIA ZTMF-OBJ-MEDIA

TMF ZTMF-OBJ-TMF CANCEL OPERATIONS ZTMF-CMD-CANCEL ZTMF-OBJ-OPERATION CLOSE RM ZTMF-CMD-CLOSE ZTMF-OBJ-RM DELETE CATALOG ZTMF-CMD-DELETE ZTMF-OBJ-CATALOG

DATAVOLS ZTMF-OBJ-DATAVOLS

DUMPS ZTMF-OBJ-DUMPS

RM ZTMF-OBJ-RM

TAPEMEDIA ZTMF-OBJ-MEDIA

TMF ZTMF-OBJ-TMF

TRANSACTION ZTMF-OBJ-TRANSACTION DISABLE AUDITDUMP ZTMF-CMD-DISABLE ZTMF-OBJ-AUDITDUMP

BEGINTRANS ZTMF-OBJ-BEGINTRANS

DATAVOLS ZTMF-OBJ-DATAVOLS DUMP FILES ZTMF-CMD-DUMP ZTMF-OBJ-FILES ENABLE AUDITDUMP ZTMF-CMD-ENABLE ZTMF-OBJ-AUDITDUMP

BEGINTRANS ZTMF-OBJ-BEGINTRANS

DATAVOLS ZTMF-OBJ-DATAVOLS

HP NonStop TMF Management Programming Manual—540140-008

1-13

Introduction to TMF

Table 1-7. TMFCOM Commands and Equivalent Programmatic Commands (page2of2)

TMF Commands

Interactive (TMFCOM) Command

Interactive

(TMFCOM)

Object Type

Programmatic Command

Programmatic Object Type

INFO AUDITDUMP ZTMF-CMD-INFO ZTMF-OBJ-AUDITDUMP and

ZTMF-OBJ-ATDUMPDM

AUDITTRAIL ZTMF-OBJ-AUDITTRAIL and

ZTMF-OBJ-ATVOLUME BEGINTRANS ZTMF-OBJ-BEGINTRANS CATALOG ZTMF-OBJ-CATALOG DATAVOLS ZTMF-OBJ-DATAVOLS DUMPS ZTMF-OBJ-DUMPS RM ZTMF-OBJ-RM PROCESS ZTMF-OBJ-PROCESS TAPEMEDIA ZTMF-OBJ-MEDIA

N/A N/A ZTMF-CMD-LIST ZTMF-OBJ-AUDITTRAIL NEXT AUDITTRAIL ZTMF-CMD-NEXT ZTMF-OBJ-AUDITTRAIL RECOVER FILES ZTMF-CMD-

ZTMF-OBJ-FILES

RECOVER RESOLVE TRANSACTION ZTMF-CMD-RESOLVE ZTMF-OBJ-TRANSACTION START TMF ZTMF-CMD-START ZTMF-OBJ-TMF STATUS AUDITDUMP ZTMF-CMD-STATUS ZTMF-OBJ-AUDITDUMP

AUDITTRAIL ZTMF-OBJ-AUDITTRAIL and

ZTMF-OBJ-ATFILE BEGINTRANS ZTMF-OBJ-BEGINTRANS CATALOG ZTMF-OBJ-CATALOG DATAVOLS ZTMF-OBJ-DATAVOLS OPERATIONS ZTMF-OBJ-OPERATIONS RM ZTMF-OBJ-RM SERVER ZTMF-OBJ-TMFSERVER TMF ZTMF-OBJ-TMF TRANSACTION ZTMF-CMD-STATUS ZTMF-OBJ-TRANSACTION

and

ZTMF-OBJ-TRANSACTION

CHILDREN

STOP TMF ZTMF-CMD-STOP ZTMF-OBJ-TMF

For detailed descriptions of the TMFCOM interactive commands listed in Table 1-7, see the TMF Reference Manual.

HP NonStop TMF Management Programming Manual —540140-008

1-14

Introduction to TMF

Section 5, Commands and Responses in this manual, describes in detail the

SPI-format programmatic commands that management applications can direct to the TMFSERVE process, and the SPI-format responses that TMF returns.

TMF Event Messages

TMF generates event messages when it detects significant events, such as a trap caused by a hardware or software error, a management counter reaching a threshold, or a transaction failure. TMF sends these event messages, in SPI format, to the Event Management Service (EMS), which makes them available to management applications upon request.

Section 6, Event Messages describes in detail the contents of the event messages.

These event messages can be displayed for system operators using an EMS printing distributor or the View Point console application. For information about the use of EMS printing distributors, see the EMS Manual. For descriptions of the displayed format of these messages, see the Operator Messages Manual.

TMF Event Messages

HP NonStop TMF Management Programming Manual—540140-008

1-15

Introduction to TMF

TMF Event Messages

HP NonStop TMF Management Programming Manual —540140-008

1-16

Communicating With the TMFSERVE Process

A management application communicates with TMF through the Subsystem Programmatic Interface (SPI). It retrieves event messages from TMF through the Event Management Service (EMS).

This section contains the following topics:

Communicating With the TMFSERVE Process on page 2-1



Starting and Opening TMFSERVE on page 2-2



Closing TMFSERVE on page 2-3



Running an EMS Consumer Distributor on page 2-3



Communicating With the TMFSERVE Process

The TMFSERVE process supports management applications written in TAL, COBOL85, TACL, or C.

When writing a management application using the TMFSERVE process, use the following guidelines:

It is not a process pair



It can be opened by a primary process or its backup



It can be opened by a requester only once



It can be opened by up to 10 requesters at a time



It can be started by any user that has execute access to the TMFSERVE object file



It responds to one request before it begins work on another (it is single-threaded)



It can accept a sync depth of 0 or 1



It does not support multiple outstanding requests from the same requester



It can only manage TMF on the system where it is running



If you want to manage TMF on a remote system, you must establish communication with a TMFSERVE process on that system.

If you want to make audit dumps or online dumps using a tape drive on another system, that system must have labeled-tape processing configured by SYSGEN.

HP NonStop TMF Management Programming Manual—540140-008

2-1

Communicating With the TMFSERVE Process

TMFSERVE is a context-free server; that is, a requester can freely divide a series of commands among a number of copies of TMFSERVE. A requester need not always communicate with the same copy of TMFSERVE.

Users that can issue TMFCOM commands can issue the corresponding programmatic commands. For example, users that can issue the TMFCOM command ABORT TRANSACTION can issue the equivalent programmatic command using ZTMF-CMDABORT and ZTMF-OBJ-TRANSACTION. Operational notes in Section 5, Commands

and Responses indicate which users can issue which programmatic commands for

TMF.

Starting and Opening TMFSERVE

Use the following guidelines when starting and opening the TMFSERVE process through your management application.

Starting TMFSERVE

Starting and Opening TMFSERVE

To start the TMFSERVE process, use one of the following: TAL The NEWPROCESS or PROCESS_CREATE_ procedure on the

NonStop OS COBOL85 The CREATEPROCESS verb TACL The #NEWPROCESS built-in function

Startup Message

The TMFSERVE process requires a startup message, and it can accept one from the NonStop OS. The only portion of the startup message that TMFSERVE uses is the parameter line specifying the optional AUTOSTOP parameter. For information about including the AUTOSTOP parameter in a startup message, see the “Starting the Management Process” in Section 5 of the SPI Programming Manual.

Opening TMFSERVE

To open an existing TMFSERVE process, use one of the following: TAL The OPEN or FILE_OPEN_ procedure on the NonStop OS COBOL85 The OPEN verb TACL The #REQUESTER built-in function

HP NonStop TMF Management Programming Manual—540140-008

2-2

Communicating With the TMFSERVE Process

Naming TMFSERVE

The name of a TMFSERVE process has the following form:

$process.#ZSPI

$process

is the name of a TMFSERVE process and begins with a dollar sign ($) followed by a letter. If the name of the TMFSERVE process is not to be used in a network it can include up to 5 alphanumeric characters after the dollar sign; otherwise it can include 4 alphanumeric characters after the dollar sign.

#ZSPI

is a process name qualifier indicating that the OPEN is for the purpose of communicating using the SPI procedures.

Closing TMFSERVE

Naming TMFSERVE

To close the TMFSERVE process, use one of the following: TAL The CLOSE or FILE_CLOSE_ procedure on the NonStop OS COBOL85 The CLOSE verb TACL The #REQUESTER built-in function

Running an EMS Consumer Distributor

Before your management application can retrieve event messages generated by TMF, you must start an Event Management Service (EMS) consumer distributor process. A consumer distributor returns selected event messages to a requesting management application. You need to open the consumer distributor for SPI communication, and then specify the source of event messages by using a CONTROL command. The EMS Manual provides full details.

To avoid receiving all event messages from all subsystem (something you will rarely want to do), you must install a filter to select only those messages your application intends to act upon. You install your filter when you start the consumer distributor . Filters are written in the EMS filter language, which is described in the EMS Manual.

HP NonStop TMF Management Programming Manual —540140-008

2-3

Communicating With the TMFSERVE Process

Running an EMS Consumer Distributor

HP NonStop TMF Management Programming Manual—540140-008

2-4

SPI Programming Considerations for TMF

Once your subsystem and EMS processes are running and your management application has established communication with the TMFSERVE process, 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 some summary information and discusses SPI programming considerations that are specific to TMF.

This section contains the following topics:

Definition Files on page 3-1



Message Elements for TMF on page 3-3



Using SPI to Build Commands and Decode Responses on page 3-5



Retrieving and Decoding Event Messages on page 3-8



Templates and Labels on page 3-10



Naming Guidelines for Applications on page 3-11



For a complete list of all token codes and token maps specific to TMF, see the ZTMFDDL file.

Definition Files

The commands, responses, and event messages sent to and received from TMF are made up of items called tokens. Each token contains a particular piece of information, such as a command parameter or an item of information 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/or in every event message.

Tokens and related data items for commands, responses, and event messages must be declared in your management applications, and HP provides these declarations for you in definition files. A set of definition files is provided as part of each HP subsystem that supports DSM, and a few other software components (such as SPI and EMS) also provide definition files. Each such software component includes definition files for the TAL, COBOL85, TACL, and DDL languages.

To be able to use the data declarations defined by a particular HP software component, your application must incorporate the appropriate programming-language definition file associated with that software component. The declarations in a COBOL85 definition file are grouped into sections to enable COBOL85 programs to declare multiple copies

HP NonStop TMF Management Programming Manual —540140-008

3-1

SPI Programming Considerations for TMF

of structures in the definition file. TAL programs can source either the entire definition file or just the sections they need. The TACL command interpreter always loads the entire definition file. For further information about how definition files are used by an application, see the SPI Programming Manual.

Definition files are named according to the following convention:

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

subsys

is a three-character code identifying the subsystem or other software component to which these definitions belong. This code is TMF for the TMF product.

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

Definition Files

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

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

The SPI (ZSPI) definition file



The TMF (ZTMF) definition file



An application that retrieves event messages issued by TMF needs all the definition files listed above, plus the following:

The EMS (ZEMS) definition file



For example, a management application written in TAL that sends commands to and retrieves event messages issued by TMF would need the following SOURCE statements:

?SOURCE ZSPIDEF.ZSPITAL ?SOURCE ZSPIDEF.ZTMFTAL ?SOURCE ZSPIDEF.ZEMSTAL

If your application manages other subsystems besides TMF, it also needs the definition files required by those subsystems. For instance, you might want your TMF management application to manage an associated Pathway system as well. If you were writing the TAL management application mentioned above and also wanted to manage Pathway, you would need the following additional SOURCE statement:

?SOURCE ZSPIDEF.ZPWYTAL

HP NonStop TMF Management Programming Manual—540140-008

3-2

SPI Programming Considerations for TMF

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 TMF definitions are described in this manual.

Message Elements for TMF

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

Commands

TMF supports the following programmatic commands: ABORT DELETE INFO RESOLVE ADD DISABLE LIST START

Message Elements for TMF

ALTER DUMP NEXT STATUS CANCEL ENABLE RECOVER STOP

Programmatic commands for TMF are identified by command numbers that have symbolic names of the form ZTMF-CMD-name, where name identifies the command. (The separator character varies with the language; hyphens are shown throughout this and other DSM manuals because hyphens are used in DDL.) For example, the name used by application programs for the ALTER command is ZTMF-CMD-ALTER. These names represent the values that can be assigned to the command number header token, ZSPI-TKN-COMMAND.

These commands and TMF’s responses to them are described in Section 5,

Commands and Responses.

Object Types

TMF supports the following programmatic object types: ATDUMPDM CATALOG PROCESS ATFILE DATAVOLS TMF ATVOLUME DUMPS TMFSERVER AUDITDUMP FILES TRANSACTION AUDITTRAIL MEDIA TRANSACTIONCHILDREN BEGINTRANS OPERATION

HP NonStop TMF Management Programming Manual—540140-008

3-3

SPI Programming Considerations for TMF

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

Object Names

Many TMF commands and responses contain object-name tokens that, when combined with object-type information, designate which objects are to be or were affected by the command.

In the management programming interface to TMF, th e form of an object name depends on the object type.

Object-name templates (wildcards) within TMF are implemented as predefined value names (for example, ZTMF-VAL-WILDAUDITTRAILID, which specifies all audit trails on a system). Valid object-name templates contain only the asterisk (*) wild-card character; the question mark character (?) is not allowed. The object-name templates are used to represent all instances of the object type. The tokens and fields that allow object-name templates are indicated in Section 5, Commands and Responses.

Object Names

Event Numbers

All event messages contain a header token identifying the event by number. 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 TMF are identified by symbolic names of the form ZTMF-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 assume any one of the set of event numbers for TMF, which are listed at the beginning of Section 6, Event Messages.

Other Tokens

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

Data Lists and Error Lists

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

HP NonStop TMF Management Programming Manual—540140-008

3-4

SPI Programming Considerations for TMF

Using SPI to Build Commands and Decode

Responses

Using SPI to Build Commands and Decode Responses

The following subsections summarize the steps your application must take to create, send, retrieve, and decode SPI messages. These summaries are followed by subsystem-specific programming considerations for TMF.

For more information about creating, sending, retrieving and decoding SPI commands and responses, see the SPI Programming Manual.

Building and Sending a Command Message

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

1. Declare a buffer of appropriate size.

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 command to retrieve the next response message in a series,

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 TAL, a READ WITH PROMPT verb in COBOL85, or a #INPUTV or #OUTPUTV built-in function in TACL).

Caution. An extensible structured token that is to appear in a command should always be initialized using the SPI procedure SSNULL. Doing this ensures that every field of the token is initialized to its null value. This is important because an operation will be performed if a field contains a value other than its null value. For example, in the ALTER AUDITTRAIL command, if a field of the extensible structured token that describes the audittrail attributes contains a value other than its null value, that value is assigned to the attribute corresponding to that field.

Using SSNULL is important even when your application assigns a value to every field of an extensible structured token. Otherwise, the application will not work correctly later if it is compiled using a new version of the definition files that add new fields to the token.

The recommended buffer length in bytes for a TMF command is a predefined value that has the name ZTMF-VAL-BUFLEN. The minimum buffer length is a predefined value named ZTMF-VAL-MINBUFLEN, and the maximum buffer length is a predefined value named ZTMF-VAL-MAXBUFLEN.

HP NonStop TMF Management Programming Manual—540140-008

3-5

SPI Programming Considerations for TMF

TMF does not support multiple commands in a single request message. However, many of the TMF commands accept multiple object names in one command (as many as will fit in the buffer), so a single command can operate on a number of objects. All objects named in a command must be of the same object type, for example, a program can specify multiple ZTMF-TKN-AUDITTRAILID tokens in a STATUS AUDITTRAIL command to determine the current activity of multiple audit trails. Object-name templates (wild-card names), an implicit way of specifying more than one object in a command, can also be used in many commands.

Discontinuing a Command in Progress

Commands in progress are cancelled using the CANCEL or CANCELREQ procedures. Although there is no harm done by cancelling a command, the TMFSERVE process does not check for request cancellation. If a requestor cancels a request to the TMFSERVE process, it is impossible to determine whether or not the command was performed. If the TMFSERVE process has already read the request, the cancellation is not detected. The TMFSERVE process executes the request and issues a reply, which the NonStop OS then discards. Cancellation does take effect if the TMFSERVE process has not yet read the request.

Discontinuing a Command in Progress

The TMFSERVE process does not respond to requests for discontinuing a command in progress, and TMF does not support the use of the standard SPI token ZSPI-TKNALLOW-TYPE. TMF continues to the next object if it failed on a previous object.

Note. Other subsystems (not TMF) use the ZSPI-TKN-ALLOW-TYPE token to allow an application to specify (in a command operating on multiple objects) if the subsystem should continue to the next object—if it failed on a previous one.

Receiving and Decoding a Response Message

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 using the mechanism appropriate to your

programming language (for example, a WRITEREAD call in TAL).

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.

HP NonStop TMF Management Programming Manual—540140-008

3-6

SPI Programming Considerations for TMF

TMF can return an empty response if an application returns a ZSPI-TKNCONTEXT token to the TMFSERVE process and there are no more responses to be returned. The return token ZSPI-TKN-RETCODE in an empty response record always has the value ZTMF-ERR-EMPTYRESPONSE.

6. Take action appropriate to the information in the response. The response buffer always contains the return token, ZSPI-TKN-RETCODE. The

value of the ZSPI-TKN-RETCODE token is either zero (to indicate that the command is successful), or it is a non-zero error number (to indicate that the command was not performed). The command can contain error lists in either case.

TMF supports multiple occurrences of the same token in responses for specific commands, and the TMFSERVE process returns multiple instances of the same token in responses for these commands.

TMF returns multiple response records in its responses to some commands, as described in the SPI Programming Manual. A response record normally contains response information for the operation of the command on a single object.

Error Handling

The recommended buffer size (in bytes) for all commands sent to TMF is ZMHS-VALBUFLEN. The minimum buffer length is ZTMF-VAL-MINBUFLEN and the maximum buffer length is ZTMF-VAL-MAXBUFLEN.

Although TMF generates responses for all commands, responses from some commands (such as INFO AUDITTRAIL and STATUS AUDITTRAIL) must be obtained from fields within an extensible structured token. The token in this example contains all of the information about audit trails that is available from the TMFSERVE process. To refer to a field within an extensible structured token, you must first obtain the entire structured token using SSGET. Then you refer to the fields of the structure using the defined field names.

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

Error Handling

Each response returned by TMF includes a return token (ZSPI-TKN-RETCODE), whose value indicates whether an error occurred when TMF attempted to perform the command. An error is a serious condition that prevents the command from being completed. If the command completed with no errors, the value of the return token is zero. If ZSPI-TKN-RETCODE has any non-zero value, this means that an error occurred. In this case, TMF 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 occurred but a warning did occur, the return token has a value of zero, but an error list appears in the response, providing information about the warning condition.

HP NonStop TMF Management Programming Manual—540140-008

3-7

SPI Programming Considerations for TMF

The TMFSERVE process does not provide support for continuing—despite errors— through the use of the SPI standard token ZSPI-TKN-ALLOW-TYPE. The SPI standard token ZSPI-TKN-RETCODE contains a nonzero value if the TMFSERVE process detects an error in a command message—or in attempting to perform a command.

TMF can also return file-system errors. These errors are listed in Table 3-1.

Table 3-1. File-System Errors Returned by TMFSERVE

Error Number Description

11 A process name qualifier other than #ZSPI was used. 12 Too many requesters are attempting to communicate with TMFSERVE. 17 An OPEN request was received from a backup process, but the parameters do

not match those used to request the OPEN for the primary process; or TMFSERVE was not opened by the primary process.

28 An attempt was made to open TMFSERVE with a NOWAIT depth greater

than 1.

Security

39 The request has a sync ID that is older than the set of saved replies. 60 TMFSERVE has failed and has been replaced by a different process having the

same name since TMFSERVE was opened.

Note. Errors 39 and 60 can be returned in response to any command. The other errors are returned only in response to a call to the OPEN procedure.

Security

TMF commands are either sensitive or nonsensitive. Sensitive commands can change the state or configuration of subsystem objects; nonsensitive commands cannot. The TMFSERVE process allows sensitive commands to be issued only by members of the super group. The description of each command in Section 5, Commands and

Responses identifies which users can issue the command.

Retrieving and Decoding Event Messages

The following is a summary of the steps your application must take to retrieve and act upon event messages:

1. Declare a buffer of appropriate size for the Event Management Service (EMS)

GETEVENT command and its response. (For recommended sizes, see Event-

Management Considerations for TMF on page 3-9.)

2. Start an EMS consumer distributor and open it using the #ZSPI qualifier.

3. Format an EMS distributor CONTROL programmatic command to load a filter you

have written, and to specify the source and destination of event messages, if desired. Send the CONTROL command to the consumer distributor using the

HP NonStop TMF Management Programming Manual—540140-008

3-8

SPI Programming Considerations for TMF

mechanism appropriate to your programming language (for example, a WRITEREAD call in TAL).

4. Read the response from the distributor using the mechanism appropriate to your

programming language (for example, a WRITEREAD call in TAL).

5. Repeat the following steps in a loop:

a. Format and send a GETEVENT command to the consumer distributor to get

the next event message, using the mechanism appropriate to your programming language (for example, a WRITEREAD call in TAL).

b. Read the response from the distributor using the mechanism appropriate to

your programming language (for example, a WRITEREAD call in TAL).

c. Call SSMOVE or SSMOVETKN to move the context token from the response

buffer into the GETEVENT command buffer. The context token will be needed when your application resends the command to get the next event.

d. Call SSGET or SSGETTKN to retrieve the token containing the event message

(ZEMS-TKN-EVENT) from the response buffer.

Event-Management Considerations for TMF

e. Call EMSGET or EMSGETTKN to retrieve the subsystem ID (ZSPI-TKN-SSID)

and the event number (ZEMS-TKN-EVENTNUMBER) from the event message. Together, these two tokens identify the event message and determine what information tokens it will contain.

f. Call EMSGET or EMSGETTKN twice to retrieve the subject of the event

message. In the first call, retrieve the subject-mark token (ZEMS-TKNSUBJECT-MARK) to get the token code and index of the token identifying the subject. Then make another call to retrieve the subject token itself.

g. Call EMSGET or EMSGETTKN to retrieve the values of other tokens from the

event message.

h. If you encounter the error-list token (ZSPI-TKN-ERRLIST), make another call

to EMSGET or EMSGETTKN to retrieve the tokens inside the error list.

i. Take action appropriate to the information in the event message.

The EMS Manual provides information about how to retrieve tokens from an event message.

Event-Management Considerations for TMF

The overall goal of event reporting by TMF is to allow the system operator or a management program to monitor and control the operation of the subsystem. TMF reports events to EMS but not to the Tandem Maintenance and Diagnostic Subsystem (TMDS).

The maximum buffer size needed for any TMF event message is 4024 bytes.

HP NonStop TMF Management Programming Manual—540140-008

3-9

SPI Programming Considerations for TMF

Some TMF event messages contain extensible structured tokens providing information for use by your application. In addition, some TMF event messages contain error lists. Some of these error lists provide information for use by your application; others contain information you should report to your service provider. The descriptions of individual event messages in Section 6, Event Messages explain what to do with each error list.

Critical Events

Events reported by TMF are divided into two classes: critical and noncritical. Critical events can have serious consequences, such as the loss of a device or the occurrence of certain errors. Noncritical events are less serious, such as a counter exceeding a threshold. The value of the token ZEMS-TKN-Emphasis indicates whether an event is critical. If the value is ZSPI-VAL-True, the event is critical; if the value is ZSPI-VALFalse, the event is not critical.

Filters

EMS provides you with the ability to create filters, which allow applications to select particular event messages from among those reported. Filters select messages to be returned to an application by examining the values of tokens in the messages. For example, to select only event messages reported by TMF, a filter would examine the token that contains the subsystem ID of the issuing subsystem and then allow only those messages containing TMF ID to pass.

Critical Events

You code a filter in the EMS filter language, compile the filter source file using the EMS filter compiler, and load the resulting filter when you run the EMS consumer distributor. You can replace filters online.

It is recommended that your application always use a filter when retrieving event messages. Otherwise, the application will receive all the event messages sent to the event log on the local system. You can use any of the tokens contained in event messages to select which event messages will be returned to your application. You can create filters that return only critical event messages, all messages associated with a particular device, all messages with a certain event number, and so forth.

The EMS Manual provides information about how to code, compile, load, and replace filters.

Templates and Labels

Event-message templates are provided with the TMF product. These define the text used for displays of event messages by the ViewPoint console application and other console devices and applications. Both source and compiled templates are provided. You can modify the source templates and compile them again if you wish to customize your messages.

The name of the TMF template object file is ZTMFTMPL; the source file is STMFTMPL. For general information on DSM templates and instructions on how to use and modify them, see the DSM Template Services Manual.

HP NonStop TMF Management Programming Manual—540140-008

3-10

SPI Programming Considerations for TMF

Naming Guidelines for Applications

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

HP NonStop TMF Management Programming Manual—540140-008

3-11

SPI Programming Considerations for TMF

Naming Guidelines for Applications

HP NonStop TMF Management Programming Manual—540140-008

3-12

4 Common Definitions

This section discusses SPI standard definitions, EMS standard definitions, and TMF definitions used in the token-oriented programmatic interface to TMF.

The information in this section is general information that applies to all uses of the definitions in the interface to TMF. Information about a definition that is specific to a particular command, response, event message, or error list appears in the description of that command, response, event message, or error list.

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.

This section contains the following topics:

SPI Standard Definitions on page 4-1



EMS Standard Definitions on page 4-4



TMF Definitions on page 4-4



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.

Table 4-1 through Table 4-6 list the SPI standard definitions used in the management

programming interface to TMF. The definitions are for: Header tokens

Other simple tokens Special tokens Token types Structures Value names

The tables do not list SPI error numbers or definitions used only in error lists associated with those error numbers, nor do they list all SPI token values an application can use.

For descriptions of SPI standard definitions, see the SPI Programming Manual. Information about the definitions that is specific to TMF follows Table 4-6.

HP NonStop TMF Management Programming Manual—540140-008

4-1

Common Definitions

Table 4-1. SPI Standard Definitions for Header Tokens

SPI Standard Definitions

ZSPI-TKN-BUFLEN ZSPI-TKN-CHECKSUM ZSPI-TKN-COMMAND ZSPI-TKN-HDRTYPE ZSPI-TKN-LASTERR ZSPI-TKN-LASTERRCODE ZSPI-TKN-

ZSPI-TKN-MAX-FIELD-VERSION ZSPI-TKN-MAXRESP ZSPI-TKN-OBJECT-TYPE ZSPI-TKN-POSITION ZSPI-TKN-SERVER-VERSION ZSPI-TKN-SSID ZSPI-TKN-USEDLEN

LASTPOSITION

Table 4-2. SPI Standard Definitions for Other Simple Tokens

ZSPI-TKN-COMMENT ZSPI-TKN-CONTEXT ZSPI-TKN-DATALIST ZSPI-TKN-ENDLIST

ZSPI-TKN-ERRLIST ZSPI-TKN-ERROR ZSPI-TKN-RETCODE ZSPI-TKN-SERVER-BANNER

Table 4-3. SPI Standard Definitions for Special Tokens

ZSPI-TKN-ADDR ZSPI-TKN-CLEARERR ZSPI-TKN-COUNT ZSPI-TKN-DATA-FLUSH ZSPI-TKN-DEFAULT-SSID ZSPI-TKN-DELETE

ZSPI-TKN-INITIAL-POSITION ZSPI-TKN-LEN ZSPI-TKN-NEXTCODE ZSPI-TKN-NEXTTOKEN ZSPI-TKN-OFFSET ZSPI-TKN-RESET-BUFFER ZSPI-TKN-USEDLEN

Table 4-4. SPI Standard Definitions for Token Types

ZSPI-TYP-BOOLEAN ZSPI-TYP-BYTESTRING ZSPI-TYP-CHAR8 ZSPI-TYP-CRTPID ZSPI-TYP-DEVICE ZSPI-TYP-ENUM ZSPI-TYP-INT ZSPI-TYP-INT-PAIR ZSPI-TYP-INT2

ZSPI-TYP-LIST ZSPI-TYP-SSCTL ZSPI-TYP-SSID ZSPI-TYP-STRING ZSPI-TYP-TIMESTAMP ZSPI-TYP-TOKENCODE ZSPI-TYP-TRANSID ZSPI-TYP-UINT ZSPI-TYP-USERID

ZSPI-TYP-INT2-PAIR

HP NonStop TMF Management Programming Manual—540140-008

4-2

Common Definitions

Table 4-5. SPI Standard Definitions for Structures

Information Specific to TMF

ZSPI-DDL-BOOLEAN ZSPI-DDL-BYTE ZSPI-DDL-CHAR-PAIR ZSPI-DDL-CHAR6 ZSPI-DDL-CHAR8 ZSPI-DDL-CRTPID ZSPI-DDL-DEVICE ZSPI-DDL-DISCNAME

ZSPI-DDL-FNAME ZSPI-DDL-INT ZSPI-DDL-INT2 ZSPI-DDL-INT2-PAIR ZSPI-DDL-TIMESTAMP ZSPI-DDL-TRANSID ZSPI-DDL-UINT ZSPI-DDL-USERID

ZSPI-DDL-ENUM

Table 4-6. SPI Standard Definitions for Value Names

ZSPI-SSN-ZTMF ZSPI-VAL-FALSE

ZSPI-VAL-TANDEM ZSPI-VAL-TRUE

Information Specific to TMF

The SPI Programming Manual fully describes all SPI standard definitions. Information about the definitions that is specific to TMF is described in this subsection.

ZSPI-TKN-COMMAND

is the command number of a TMF command. See Section 5, Commands and

Responses for a description of command numbers and associated commands.

ZSPI-TKN-OBJECT-TYPE

is the object-type number of a TMF object. See Section 5, Commands and

Responses for a description of object-type numbers.

ZSPI-TKN-SERVER-VERSION

is the server version of the TMFSERVE process.

ZSPI-TKN-SSID

contains ZTMF-VAL-SSID, the subsystem ID of TMF. It has the following structure:

def ZTMF-VAL-SSID Tacl SSID. 02 Z-FILLER Type Character 8 VALUE ZSPI-VAL-TANDEM. 02 Z-OWNER Redefines Z-FILLER Type ZSPI-DDL-CHAR8. 02 Z-NUMBER Type ZSPI-DDL-INT VALUE ZSPI-SSN-ZTMF. 02 Z-VERSION Type ZSPI-DDL-UINT VALUE ZTMF-VAL-VERSION. end.

HP NonStop TMF Management Programming Manual—540140-008

4-3

Common Definitions

ZSPI-SSN-ZTMF

is the subsystem number assigned to TMF.

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-7 and Table 4-8 list the EMS standard definitions used in the management

programming interface to TMF. The definitions are for: Header tokens

A data-portion token 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. Information about the definitions that is specific to TMF follows Table 4-8.

Table 4-7. EMS Standard Definitions for Header Tokens

EMS Standard Definitions

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

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

ZEMS-TKN-SUBECT-MARK

TMF Definitions

Definitions whose names begin with ZTMF- are TMF definitions. These definitions are provided in the DDL file ZSPIDEF.ZTMFDDL, and in the corresponding files for other languages.

Tables 4-9 through 4-11 list TMF definitions. The definitions are for: Buffer Declarations

Private token and field types Predefined token and field values

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

HP NonStop TMF Management Programming Manual—540140-008

4-4

Common Definitions

Table 4-9. TMF Buffer Declarations

Buffer Declarations

ZTMF-DDL-MSG-BUFFER ZTMF-DDL-MSG-MINBUFFER ZTMF-DDL-MSG-MAXBUFFER ZTMF-VAL-BUFLEN ZTMF-VAL-BUFLEN-W

Table 4-10. TMF Private Token and Field Types

ZTMF-TYP-CHILDREN ZTMF-TYP-MEDIA

Table 4-11. TMF Predefined Token and Field Values

ZTMF-VAL-SSID ZTMF-VAL-VERSION

Buffer Declarations

TMF provides the following buffer declarations for message buffers you can use with the SPI procedures. All applications should use one of these declarations for a buffer of the recommended size.

ZTMF-VAL-MAXBUFLEN ZTMF-VAL-MAXBUFLEN-W ZTMF-VAL-MINBUFLEN ZTMF-VAL-MINBUFLEN-W

ZTMF-TYP-DISKMEDIA ZTMF-TYP-USERNAME

ZTMF-DDL-MSG-BUFFER

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

def ZTMF-DDL-MSG-BUFFER. 02 Z-MSGCODE type ZSPI-DDL-INT. 02 Z-BUFLEN type ZSPI-DDL-UINT. 02 Z-OCCURS type ZSPI-DDL-UINT. 02 Z-FILLER type ZSPI-DDL-BYTE Occurs 0 to ZTMF-VAL-BUFLEN times depending on Z-OCCURS. end.

ZTMF-DDL-MSG-MINBUFFER

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

def ZTMF-DDL-MSG-MINBUFFER. 02 Z-MSGCODE type ZSPI-DDL-INT. 02 Z-BUFLEN type ZSPI-DDL-UINT. 02 Z-OCCURS type ZSPI-DDL-UINT. 02 Z-FILLER type ZSPI-DDL-BYTE Occurs 0 to ZTMF-VAL-MINBUFLEN times depending on Z-OCCURS. end.

HP NonStop TMF Management Programming Manual—540140-008

4-5

Common Definitions

ZTMF-DDL-MSG-MAXBUFFER

is a message buffer of the maximum size for use with the SPI procedures—TACL does not accept a buffer of this size.

def ZTMF-DDL-MSG-MAXBUFFER. 02 Z-MSGCODE type ZSPI-DDL-INT. 02 Z-BUFLEN type ZSPI-DDL-UINT. 02 Z-OCCURS type ZSPI-DDL-UINT. 02 Z-FILLER type ZSPI-DDL-BYTE Occurs 0 to ZTMF-VAL-MAXBUFLEN times depending on Z-OCCURS. end.

ZTMF-VAL-BUFLEN

is the recommended buffer size (in bytes) for commands sent to TMF.

ZTMF-VAL-BUFLEN-W

Private Token and Field Types

is the recommended buffer size (in words) for commands sent to TMF.

ZTMF-VAL-MAXBUFLEN

is the maximum buffer size (in bytes) for commands sent to TMF—TACL does not support buffers of this size.

ZTMF-VAL-MAXBUFLEN-W

is the maximum buffer size (in words) for commands sent to TMF—TACL does not support buffers of this size.

ZTMF-VAL-MINBUFLEN

is the minimum buffer size (in bytes) for commands sent to TMF.

ZTMF-VAL-MINBUFLEN-W

is the minimum buffer size (in words) for commands sent to TMF.

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

ZTMF-TYP-CHILDREN

is a 16-bit signed integer specifying the nodes accessed by a network-distributed transaction. It has a token data type of ZSPI-TDT-INT, it is used to define the ZTMF-TKN-CHILDREN token, and it is part of the ZTMF-DDL-STATUS-TXCHILDREN extensible structured token.

HP NonStop TMF Management Programming Manual—540140-008

4-6

Common Definitions

ZTMF-TYP-MEDIA

defines a piece of TMF tape media and the part and copy number of the dump it contains.

def ZTMF-DDL-MEDIA. 02 Z-NAME type ZSPI-DDL-CHAR6. 02 Z-PARTNUMBER type ZSPI-DDL-INT. 02 Z-COPYNUMBER type ZSPI-DDL-INT. end.

Z-NAME

is the name of the tape volume. If the first character is numeric, up to 5 numeric characters can follow. If the first character is alphabetic, up to 5 numeric or alphabetic characters (in any combination) can follow.

Z-PARTNUMBER

is the part number of the dump that is contained in this tape volume.

Private Token and Field Types

Z-COPYNUMBER

is the copy number of the dump that is contained in this tape volume.

ZTMF-TYP-DISKMEDIA

defines a piece of TMF disk media.

def ZTMF-DDL-DISKMEDIA. 02 Z-SYSTEMFILENAME type ZSPI-DDL-FNAME32. 02 Z-PRIORITYORDER type ZSPI-DDL-INT. end.

Z-SYSTEMFILENAME

is the name of the disk volume. The format is:

[\node.] $volume [.prefix]

Z-PRIORITYORDER

orders the disk media. The value should start at 1 and increase in ascending numeric order.

HP NonStop TMF Management Programming Manual—540140-008

4-7

Common Definitions

ZTMF-TYP-UserName

defines the ZTMF-TKN-UserName token for the NonStop OS group and user name.

def ZTMF-DDL-UserName. 02 Z-GroupName type ZSPI-DDL-Char8. 02 Z-UserName type ZSPI-DDL-Char8. end.

Z-GroupName

is the 8-character group name of the user.

Z-UserName

is the 8-character user name of the user.

ZTMF-TYP-CpusInfo

Private Token and Field Types

defines the processor(s) in which to run a process.

def ZTMF-DDL-CpusInfo. 02 Z-Count type ZSPI-DDL-Int. 02 Z-Int type ZSPI-DDL-Int. end.

Z-Count

is the beginning CPU number.

Z-Int

is the ending CPU number.

ZTMF-TYP-PioBuffer

defines configuration characteristics of the transport layer.

def ZTMF-DDL-PioBuffer. 02 ZPioBufferSize type ZSPI-DDL-Int2. 02 ZMaxPioPerBuffer type ZSPI-DDL-Int. 02 ZPioDelayTimer type ZSPI-DDL-Int2. end.

ZPioBufferSize

is the size, in bytes, of the transport buffer allocated for PIOs. Valid values are 600 to 1800. The default is 600.

HP NonStop TMF Management Programming Manual—540140-008

4-8

Common Definitions

ZMaxPioPerBuffer

is the maximum number of LBEs that will be held in a transport buffer before the buffer content is sent. The specified number can range from 1 to 100. When set to 1, the ZPioBufferSize and ZPioDelayTimer token values are not relevant. The default is 1. When ZMaxPioPerBuffer is set to dynamic, TMF adjusts the ZMaxPioPerBuffer value based on the message packet activity. To use the dynamic feature, either set the ZMaxPioPerBuffer to -1 or use the Dynamic keyword.

ZPioDelayTimer

is the length of time, in microseconds, TMF waits before forwarding the PIO transport buffer. The value can range from 10000 to 2000000. The default is

100000.

ZTMF-TYP-TmpWaitTimer

defines attributes of the TMP wait timer.

Private Token and Field Types

def ZTMF-DDL-TmpWaitTimer. 02 ZType type ZSPI-DDL-Int. 02 ZValue type ZSPI-DDL-Int2. end.

ZType

specifies whether the timer is set automatically or manually, or is off. The following values are valid:

ZTMF-VAL-TmpWaitTimer-Auto Timer is set automatically by the

TMP.

ZTMF-VAL-TmpWaitTimer-Man Timer is set manually. The timer

value is specified by the ZValue field.

ZTMF-VAL-TmpWaitTimer-Off Timer is off. This is the default.

ZValue

is, for manual mode, the timer value in microseconds. The value can range from 1 (one microsecond) to 1000000 (one second). Values less than 1000 (one millisecond) are rounded up to 1000.

HP NonStop TMF Management Programming Manual—540140-008

4-9

Common Definitions

ZTMF-TYP-MemHeapUsage

defines attributes of memory heap usage.

def ZTMF-DDL-MemHeapUsage. 02 ZLib. 03 ZCpuHeapSize type ZSPI-DDL-Int2. 03 ZCpuHeapPercent type ZSPI-DDL-Int OCCURS 16 TIMES. 02 ZTmp. 03 ZTmpHeapSize type ZSPI-DDL-Int2. 03 ZCpu type ZSPI-DDL-Int-Pair. 03 ZHeapPercent type ZSPI-DDL-Int-Pair. end.

ZZCpuHeapSize

is the TMFLIB heap size.

ZZCpuHeapPercent

is the TMFLIB heap usage by CPU in percent. This field occurs 16 times. A null value means the CPU is nonexistent or down.

Private Token and Field Types

ZZTmpHeapSize

is the TMP heap size by CPU. This field occurs two times.

ZZCpu

specifies the CPUs where the primary/backup TMP processes are running.

ZZHeapPercent

is the TMP heap usage in percent for the TMP processes. A null value means that no backup TMP process exists.

HP NonStop TMF Management Programming Manual—540140-008

4-10

Common Definitions

Predefined Token and Field Values

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

ZTMF-VAL-SSID

is the subsystem ID of TMF. For information about the structure of this value, see the description of the ZTMF-VAL-SSID token in SPI Standard Definitions on page 4-1.

ZTMF-VAL-VERSION

is the product version number of TMF. 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.

Simple Tokens

Predefined Token and Field Values

A simple token has a value consisting of a single field or a fixed structure. See

Section 5, Commands and Responses for descriptions of simple tokens in a particular

command, response. See Section 6, Event Messages for descriptions simple tokens in event messages.

Extensible Structured Tokens

An extensible structured token has a token map and a value consisting of data fields whose number can be extended. This extensibility allows addition of new fields to the structure in later releases. Extensible structured tokens are defined by token maps. See Section 5, Commands and Responses for descriptions of the extensible structured tokens in a particular command or response. TMF does not use extensible structured tokens in event messages.

Tokens in Event Messages

See Section 6, Event Messages for a description of each token that occurs in an event message generated by TMF.

HP NonStop TMF Management Programming Manual—540140-008

4-11

Common Definitions

Tokens in Event Messages

HP NonStop TMF Management Programming Manual—540140-008

4-12

5 Commands and Responses

This section describes the programmatic commands you can issue to the TMFSERVE process—and the responses returned by each command. Each command and response description contains usage guidelines, including which user types are allowed to issue it. See Section 4, Common Definitions tokens used in more than one command.

Note. Some limits and default values for the parameters in the following commands, and the operational behavior described, may have changed since this manual was published with RVU G06.26. If such changes were made, they will be described in TMF Supplement for Limits and Defaults Changed After R VU G06 .26. If that supp lement cu rrently exists, please read it for new information about limits and defaults.

This section contains the following topics:

Command Summary on page 5-2



Command Descriptions on page 5-4



These commands allow applications to do the following:

Add and delete objects



for a description of the common

Start, stop, and abort objects



Obtain status on an object or a group of objects



Obtain statistics on an object or a group of objects



Note. The command and response tokens are displayed in DDL. For more information about DDL, see the SPI Programming Manual.

HP NonStop TMF Management Programming Manual —540140-008

5-1

Commands and Responses

Command Summary

Table 5-1 lists all TMF programmatic commands for management applications. These

commands are described, in alphabetic order by command, in this section.

Table 5-1. TMF Commands, by Command

Command Summary

Command (ZTMF-CMD-)

ABORT TRANSACTION ADD AUDITTRAIL DATAVOLS

ALTER AUDITDUMP CATALOG MEDIA

CANCEL OPERATION CLOSE RESOURCEMANAGER DELETE CATALOG RESOURCEMANAGER

DISABLE AUDITDUMP BEGINTRANS DATAVOLS DUMP FILES ENABLE AUDITDUMP BEGINTRANS DATAVOLS INFO ATDUMPDM BEGINTRANS MEDIA

Object Types (ZTMF-OBJ-)

DUMPS MEDIA RESOURCEMANAGER

AUDITTRAIL DATAVOLS PROCESS BEGINTRANS DUMPS TMF

DATAVOLS TMF DUMPS TRANSACTION MEDIA

ATVOLUME CATALOG PROCESS AUDITDUMP DATAVOLS RESOURCEMANAGER

AUDITTRAIL DUMPS TMF

LIST AUDITTRAIL NEXT AUDITTRAIL RECOVER FILES RELOCATE DISKDUMPS RESOLVE TRANSACTION START TMF STATUS ATFILE RESOURCEMANAGER

STOP TMF

HP NonStop TMF Management Programming Manual—540140-008

AUDITDUMP RMTRANSBRANCHES

AUDITTRAIL TMF

BEGINTRANS TMFSERVER

CATALOG TRANSACTION

DATAVOLS TRANSACTIONCHILDREN

OPERATION

5-2

Commands and Responses

Table 5-2 lists the same commands shown in Table 5-1, but in alphabetical order by

object type.

Table 5-2. TMF Commands, by Object

Command Summary

Object Type (ZTMF-OBJ-)

Commands (ZTMF-CMD-)

ATDUMPDM INFO ATFILE STATUS ATVOLUME INFO AUDITDUMP ALTER ENABLE STATUS

DISABLE INFO

AUDITTRAIL ADD INFO NEXT

ALTER LIST STATUS

BEGINTRANS ALTER ENABLE STATUS

DISABLE INFO

CATALOG ALTER INFO STATUS

DELETE

DATAVOLS ADD DISABLE INFO

ALTER ENABLE STATUS DELETE

DUMPS ADD DELETE INFO

ALTER

FILES DUMP RECOVER MEDIA ADD DELETE INFO

ALTER

OPERATION CANCEL STATUS PROCESS ALTER INFO RESOURCEMANAGER ADD DELETE STATUS

CLOSE INFO

RMTRANSBRANCHES STATUS TMF DELETE STATUS STOP

START

TMFSERVER STATUS TRANSACTION ABORT RESOLVE STATUS

DELETE

TRANSACTIONCHILDREN STATUS

HP NonStop TMF Management Programming Manual —540140-008

5-3

Commands and Responses

Command Descriptions

Each command description contains a box that shows the symbolic name of the command number (such as ZTMF-CMD-Abort), the symbolic name for the object type of the command (such as ZTMF-OBJ-Transaction), a list of tokens that the command buffer can contain, and a list of tokens that the response buffer can contain.

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. Extensible structured tokens are defined by using DDL Definition statements.

The tokens listed in the response buffer represent the tokens that can be present in one response record of a response that consists of multiple response records—except for the ZSPI-TKN-Context token. See the SPI Programming Manual for more information about responses consisting of multiple response records.

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.

Command Descriptions

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 about data lists and error lists, see the SPI Programming Manual.

The tokens displayed for the command and response buffers are described in the same order in which they appear in the syntax box. The descriptions indicate whether the tokens are optional or required, and whether multiple occurrences of the tokens are allowed.

HP NonStop TMF Management Programming Manual—540140-008

5-4

Commands and Responses

ABORT TRANSACTION

The ABORT TRANSACTION command cancels the effects of an active transaction, or reattempts to cancel an aborting or hung transaction, and releases the locks held by that transaction.

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Abort

Object Type

ZTMF-OBJ-Transaction

Tokens in Command Buffer

ABORT TRANSACTION

ZTMF-TKN-TransID token-type ZSPI-TYP-TransID. ZTMF-MAP-Abort-Transaction

def ZTMF-DDL-Abort-Transaction. 02 ZIgnoreDataErrors token-type ZSPI-DDL-Boolean. 02 ZAvoidHanging token-type ZSPI-DDL-Boolean. end.

Tokens in Response Buffer

None.

HP NonStop TMF Management Programming Manual —540140-008

5-5

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-TransID

specifies the transaction identifier of the transaction to be aborted.

ZTMF-MAP-Abort-Transaction

is an extensible structured token that contains fields for aborting a transaction. Only one occurrence of this token is allowed. This token contains the following fields:

ZIgnoreDataErrors

specifies whether or not data-related errors are to be ignored while the specified transactions are being undone. This field is optional. If you do not assign a value to this field, the default is ZSPI-VAL-False. The following values are valid:

ZSPI-VAL-True Data-related errors are ignored

ABORT TRANSACTION

ZSPI-VAL-False Data-related errors are not ignored Normally, when the backout process encounters data errors while undoing a

transaction, it places the transaction in the hung state. When ZIgnoreDataErrors is ZSPI-VAL-True, however, the backout process undoes as much of the transaction as possible and, for those files yielding data errors, ignores the errors as if the undo had been performed completely. If you omit ZIgnoreDataErrors, the backout process reacts in the normal way, acknowledging the errors and placing the transaction in the hung state.

Caution. Contact the Global Customer Support Center (GCSC) or your service provider before using this command with ZIgnoreDataErrors set to ZSPI-VAL-True. This field can lead to database corruption and loss of data integrity. Include this field only if all efforts to abort a transaction fail and data availability is more important than data integrity.

ZAvoidHanging

specifies whether files that have data errors be noted and removed from access while the specified transactions are being undone. The following values are valid:

ZSPI-VAL-True

The backout process undoes as much of the transaction as possible. For those files yielding data errors, the backout process writes an audit trail record that preserves information about what parts of the transaction could not be undone and marks the file “undo-needed,” so that it is no longer accessible to applications. (To restore the file to the system, you must typically use the file recovery process.) The backout process then aborts the transaction.

HP NonStop TMF Management Programming Manual—540140-008

5-6

Commands and Responses

ZSPI-VAL-False

The backout process does not abort the transaction but instead leaves it in the hung state.

This field is optional. If you do not assign a value to this field, the default is ZSPI-VAL-False.

Usage Guidelines

Only members of the super user group can issue this command. TMF must be started. The buffer that receives the results should be large enough to hold the results for all

transactions. If ZSPI-TKN-MaxResp is less than the size of buffer needed, the command is not accepted by the TMFSERVE process.

For more information about the ABORT Transaction command, see the TMF Reference Manual.

ABORT TRANSACTION

HP NonStop TMF Management Programming Manual —540140-008

5-7

Commands and Responses

ADD AUDITTRAIL

The ADD AUDITTRAIL command adds an audit trail to the TMF configuration by specifying the audit-trail identifier and the attributes associated with that audit trail (such as volumes to hold the files, the size of the files, and the number of files allocated per active volume).

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Add

Object Type

ZTMF-OBJ-AuditTrail

ADD AUDITTRAIL

Tokens in Command Buffer

ZTMF-TKN-AuditTrailId token-type ZSPI-TYP-Enum. ZTMF-TKN-ActiveVolume token-type ZSPI-TYP-String. ZTMF-TKN-OverflowVolume token-type ZSPI-TYP-String. ZTMF-TKN-RestoreVolume token-type ZSPI-TYP-String.

ZTMF-MAP-Add-AuditTrail def ZTMF-DDL-Add-AuditTrail. 02 ZFilesPerVolume token-type ZSPI-DDL-Int. 02 ZFileSize token-type ZSPI-DDL-Int. 02 ZAuditDump token-type ZSPI-DDL-Boolean. 02 ZOverflowThreshold token-type ZSPI-DDL-Int. 02 ZBeginTransDisable token-type ZSPI-DDL-Int. 02 ZFileSize32 token-type ZSPI-DDL-Int2. end.

Tokens in Response Buffer

ZTMF-TKN-VolumeName token-type ZSPI-TYP-String. ZTMF-TKN-ATVolumeType token-type ZSPI-TYP-Enum. ZTMF-TKN-FS-Error token-type ZSPI-TYP-Int.

HP NonStop TMF Management Programming Manual—540140-008

5-8

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-AuditTrailId

specifies an audit trail to add to the TMF configuration. This token is required; only one occurrence is allowed. The following values are valid:

ZTMF-VAL-Mat Master audit trail ZTMF-VAL-Aux01 Auxiliary audit trail #1 ZTMF-VAL-Aux02 Auxiliary audit trail #2 . . . ZTMF-VAL-Aux015 Auxiliary audit trail #15

Audit trails must be added to the TMF configuration in sequence, starting with the master audit trail, then the auxiliary audit trails Aux01, Aux02, and so forth.

ZTMF-TKN-ActiveVolume

ADD AUDITTRAIL

specifies the disk volume that holds the audit trail files. This token must occur at least once; up to 16 occurrences are allowed. You must specify a unique disk volume for each audit trail.

A volume configured as an active-audit volume cannot be configured as a data volume. To add more audit volumes to the configuration later, use the ALTER AUDITTRAIL command.

Volumes of the same size should be used for a specific audit trail. TMF allocates the same number of files on each volume, and all volumes must be able to hold all of those files. If a mixture of large and small disks is used for an audit trail, some portion of the large disks remains unused because this space receives neither the active audit trail nor the audited files. The unused space, however, could be configured as overflow space or audit restore space.

ZTMF-TKN-OverflowVolume

specifies the disk volume used as overflow space for the audit trail. This token can occur from 1 to 16 times. Although this token is optional, it is recommended that you specify at least one overflow-audit volume. You cannot specify the same overflow-audit volume twice in the same command. Overflow-audit volumes can be the same volumes as the active-audit volumes; they can also be data volumes or any volumes not configured for other TMF purposes.

HP NonStop TMF Management Programming Manual —540140-008

5-9

Commands and Responses

ZTMF-TKN-RestoreVolume

specifies the disk volume used when restoring audit dumps. If audit dumping is configured for the audit trail, you must specify at least one volume for this purpose. This token can occur from 1 to 16 times. You cannot specify the same restore-audit volume twice in the same command. Restore-audit volumes can be the same volumes as the active-audit volumes; they can also be data volumes or any volumes not configured for other TMF purposes.

ZTMF-MAP-Add-AuditTrail

is an extensible structured token that contains fields for adding an audit trail to the TMF configuration. This token is required; only one occurrence is allowed. This token contains the following fields:

ZFilesPerVolume

specifies the number of files in the audit trail that reside on each active-audit volume configured. The audit trail’s capacity is determined by the number of audit-trail files per volume, the number of active-audit volumes, and the file sizes. TMF pre-allocates these files when the ADD AUDITTRAIL command is executed. If the subsystem cannot allocate all the files, this command fails.

ADD AUDITTRAIL

The minimum value is 1 and the maximum value is 100. The default is 5.

Caution. The number of active-audit volumes multiplied by the value of ZFilesPerVolume mu st be 2 or greater.

ZFileSize

must be set to the same value as ZFileSize32, unless the file size exceeds

2047. If the file size exceeds 2047, you must set ZFileSize to ZSPI^Null and ZFileSize32 to the desired file size.

ZAuditDump

specifies whether or not audit dumping is performed for the audit trail. During audit dumping, TMF automatically copies to tape or disk an audit trail file that has become full. The following values are valid:

ZSPI-VAL-True Audit dumping is enabled. ZSPI-VAL-False Audit dumping is prevented.

The default is ZSPI-VAL-True. An auxiliary audit trail cannot be configured with ZAuditDump set to ZSPI-VAL-

True unless the master audit trail is also configured with ZAuditDump set to ZSPI-VAL-True. A master audit trail cannot be configured with ZAuditDump set to ZSPI-VAL-False unless the auxiliary audit trails are also configured with ZAuditDump set to ZSPI-VAL-False. However, a master audit trail can be

HP NonStop TMF Management Programming Manual—540140-008

5-10

Commands and Responses

configured with ZAuditDump set to ZSPI-VAL-True regardless of the ZAuditDump value for the auxiliary audit trails. The possible combinations are:

ADD AUDITTRAIL

ZAuditDump Value for MAT

ZAuditDump Value for AUX Allowed/Disallowed

ZSPI-VAL-True ZSPI-VAL-True Allowed ZSPI-VAL-False ZSPI-VAL-False Allowed ZSPI-VAL-True ZSPI-VAL-False Allowed ZSPI-VAL-False ZSPI-VAL-True Disallowed

ZOverflowThreshold

specifies the percentage of audit trail capacity that can be consumed before TMF begins overflow copying. This field is optional. The minimum value is 50 (percent) and the maximum value is 100 (percent). The default is 80 (percent).

ZBeginTransDisable

specifies the percentage of audit-trail capacity that can be consumed before TMF disables new transactions. When the consumed capacity falls below this threshold, new transactions are no longer disabled by audit-trail usage. (However, new transactions can be disabled for other reasons, as explained under the description of ALTER BEGINTRANS on page 5-38.) The minimum value is 50 (percent) and the maximum value is 100 (percent). The default is 90 (percent).

ZFileSize32

specifies the size of the audit-trail files, in megabytes (MB). The minimum value is 1 and the maximum depends on the format of the audit-trail files, as follows:

For format 1 files: 2047 or the maximum disk size (if less than 2047 MB).



For format 2 files: 1048575 or the maximum disk size (if less than 1048575



MB). (This maximum value equals 1 terabyte (TB) minus 1 megabyte (MB).)

For format 1 files, the default file size is 100, resulting in files of 100 MB (100 x 1024 x 1024 bytes) each. For format 2 files, the default file size is 1024, resulting in files of 1024 MB (1024 x 1024 x 1024 bytes) each.

At any point after the FileSize attribute value is set, you can change that value by using the ALTER AUDITTRAIL command.

HP NonStop TMF Management Programming Manual —540140-008

5-11

Commands and Responses

Tokens in Response Buffer

ZTMF-TKN-VolumeName

contains the name of a volume that was in error, if an error is returned.

ZTMF-TKN-ATVolumeType

contains the type of the volume specified in ZTMF-TKN-VolumeName. This token is only present if ZTMF-TKN-VolumeName is present. The following values are valid:

ZTMF-VAL-ActiveVol The disk volume that holds the audit trail

ZTMF-VAL-OverflowVol The disk volume used as overflow space

ZTMF-VAL-RestoreVol The disk volume used when restoring audit

ADD AUDITTRAIL

files.

for the audit trail.

dumps.

ZTMF-TKN-FS-Error

contains the file-system error that may have caused the command to fail. Its presence depends on the value of ZSPI-Ret-Code.

Usage Guidelines

Only super-group users can issue this command. You can issue ADD AUDITTRAIL commands under either of the following conditions:

1. Before you start TMF for the first time with the START TMF command.

Note. Before entering the START TMF command, you must configure at least one audit trail, the master audit trail. At this time, in addition, you can configure as many auxiliary audit trails as you wish, up to the limit of 15.

2. After TMF is started. At this point, however, you can only configure auxiliary audit trails.

Under either condition you can issue multiple ADD AUDITTRAIL commands. For more information on the ADD AUDITTRAIL command, see the TMF Reference

Manual.

HP NonStop TMF Management Programming Manual—540140-008

5-12

Commands and Responses

ADD DATAVOLS

The ADD DATAVOLS command adds data volumes to the TMF configuration, including management attributes such as the audit trail to receive audit records from these volumes.

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Add

Object Type

ZTMF-OBJ-DataVols

Tokens in Command Buffer

ADD DATAVOLS

ZTMF-TKN-VolumeName token-type ZSPI-TYP-String. ZTMF-TKN-NotVolumeName token-type ZSPI-TYP-String. ZSPI-TKN-MaxResp token-type ZSPI-TYP-Int. ZSPI-TKN-Context token-type ZSPI-TYP-ByteString.

ZTMF-MAP-Add-DataVols def ZTMF-DDL-Add-DataVols. !r 02 ZAuditTrailId token-type ZSPI-DDL-Enum. 02 ZRecoveryMode token-type ZSPI-DDL-Enum. 02 ZIgnorePreviousConfig token-type ZSPI-DDL-Boolean. end.

Tokens in Response Buffer

ZTMF-TKN-VolumeName token-type ZSPI-TYP-String. ZSPI-TKN-Context token-type ZSPI-TYP-ByteString.

HP NonStop TMF Management Programming Manual —540140-008

5-13

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-VolumeName

specifies the name of a disk volume to be added to the TMF configuration as a data volume. This token must occur at least once; multiple occurrences are allowed.

ZTMF-TKN-VolumeName can also contain a wild card (value “*”, length 1). If the wild card is specified, it must be the only instance of this token in the command buffer. The wild card specifies that all accessible disk volumes in the system (not already configured as active-audit volumes or data volumes) should be added to the TMF configuration as data volumes.

ZTMF-TKN-NotVolumeName

specifies the name of a disk volume that is not to be added to the TMF configuration as a data volume. This token is optional; multiple occurrences are allowed.

ADD DATAVOLS

This token is often used with a wild-card value for ZTMF-TKN-VolumeName to exclude certain volumes from consideration. It can also be used along with an explicit list of volumes.

ZTMF-MAP-Add-DataVols

is an extensible structured token specifying attributes of the data volumes to be added to the TMF configuration. This token is required; only one occurrence is allowed. This token contains the following fields:

ZAuditTrailId

specifies the audit trail to which the data volumes send their audit records. The following values are valid:

ZTMF-VAL-Mat Master audit trail ZTMF-VAL-Aux01 Auxiliary audit trail #1 ZTMF-VAL-Aux02 Auxiliary audit trail #2

. . . ZTMF-VAL-Aux015 Auxiliary audit trail #15 If null, the default is ZTMF-VAL-Mat.

HP NonStop TMF Management Programming Manual—540140-008

5-14

Commands and Responses

ZRecoveryMode

specifies whether audit trail files are held on disk until they are no longer required for volume recovery. The following values are valid:

ZTMF-VAL-RecovMode-Online

directs TMF to retain sufficient audit trail files on disk so that volume recovery does not need to restore audit information from an archived audit dump. Retaining audit trail files on disk can affect audit trail management and transaction processing; transaction processing, for example, is disabled if it causes the audit trail to exceed a capacity threshold. This is the default.

ZTMF-VAL-RecovMode-Archive

directs TMF to release audit trail files so that they are not retained on disk solely for the purpose of volume recovery. If volume recovery becomes necessary, one or more audit dumps might need to be restored. This value is valid only if audit dumping is configured for the associated audit trail.

ADD DATAVOLS

ZIgnorePreviousConfig

specifies whether or not a data volume is to be added to the configuration regardless of whether it was associated with a previous TMF configuration and thus might be inconsistent.

ZSPI-VAL-True

specifies that a data volume is to be added to the configuration regardless of whether it was associated with a previous TMF configuration and thus might be inconsistent. The ADD DATAVOLS command does not return an error.

ZSPI-VAL-False

specifies that a data volume from a previous configuration cannot be added to the configuration. The ADD DATAVOLS command fails.

If this field is null, the default is ZSPI-VAL-False.

Caution. Volume recovery cannot repair any inconsistencies that exist when a data volume is added with ZIgnorePreviousConfig set to ZSPI-VAL-True, even if the data volume is returned to its previous configuration environment.

HP NonStop TMF Management Programming Manual —540140-008

5-15

Commands and Responses

Tokens in Response Buffer

ZTMF-TKN-VolumeName

contains the name of the volume(s) specified in the command buffer.

Usage Guidelines

Only super-group users can issue this command. TMF must be started. For more information about the ADD DATAVOLS command, see the TMF Reference

Manual.

ADD DATAVOLS

HP NonStop TMF Management Programming Manual—540140-008

5-16

Commands and Responses

ADD DUMPS

The ADD DUMPS command adds dump entries to the TMF catalog. This command is used to reenter online and audit dump entries accidentally deleted from the catalog, or to recover a destroyed catalog. Use the ADD DUMPS command only under one of these conditions:

The catalog files residing in the $System.ZTMFCONF subvolume have been



damaged or lost. Entries for dumps have been mistakenly deleted from the catalog through a



DELETE DUMPS command. A file is mistakenly purged.



The AUDIT attribute of a file is mistakenly changed to NO AUDIT.



Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

ADD DUMPS

Command

ZTMF-CMD-Add

Object Type

ZTMF-OBJ-Dumps

Tokens in Command Buffer

ZTMF-TKN-FileName token-type ZSPI-TYP-String. ZTMF-TKN-Media token-type ZTMF-TYP-Media. ZTMF-TKN-DiskMedia token-type ZTMF-TYP-DiskMedia.

ZTMF-MAP-Add-Dumps def ZTMF-DDL-Add-Dumps. 02 ZSerial token-type ZSPI-DDL-Int2. 02 ZDumpType token-type ZSPI-DDL-Enum. 02 ZMasterSequence token-type ZSPI-DDL-Int2. 02 ZDataSequence token-type ZSPI-DDL-Int2. 02 ZMedium token-type ZSPI-DDL-Enum. 02 ZTimeStamp token-type ZSPI-DDL-TimeStamp. end.

Tokens in Response Buffer

None.

HP NonStop TMF Management Programming Manual —540140-008

5-17

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-FileName

specifies the audit trail file to be added to the catalog. This token is required; multiple occurrences are allowed.

ZTMF-TKN-Media

for dumps to tape, specifies the name of the tape volume on which the dump is stored. Specify the identifier magnetically encoded in the tape volume label and registered in the TMF catalog. Either ZTMF-TKN-Media or ZTMF-TKN-DiskMedia is required; multiple occurrences are allowed.

ZTMF-TKN-DiskMedia

for dumps to disk, specifies the disk volume on which the dump is located. Either ZTMF-TKN-Media or ZTMF-TKN-DiskMedia is required; multiple occurrences are allowed.

ADD DUMPS

ZTMF-MAP-Add-Dumps

is an extensible structured token specifying the attributes of the dumps to be added to the TMF catalog. This token is required; only one occurrence is allowed. This token contains the following fields:

ZSerial

specifies the dump serial number of the online dump to be added to the TMF catalog. The value should be the serial number of the original online dump. This field is required; you must specify a value greater than or equal to 64.

ZDumpType

specifies the type of dump to be added to the TMF catalog. This field is required. The following values are valid:

ZTMF-VAL-AuditDump The dump is an audit dump. ZTMF-VAL-OnlineDump The dump is an online dump.

ZMasterSequence

specifies the master audit trail sequence number that was active when the dump was made. This field is required if the value of ZDumpType is ZTMFVAL-OnlineDump.

HP NonStop TMF Management Programming Manual—540140-008

5-18

Commands and Responses

ZDataSequence

specifies the auxiliary audit trail sequence number that was active when the dump was made. This field is required if the value of ZDumpType is ZTMF-VAL-OnlineDump.

Note. If only a master audit trail is configured, the values for ZMasterSequence and ZDataSequence are identical.

ZMedium

specifies the type of storage media used to make this dump. This field is required. The following values are valid:

ZTMF-VAL-MediumTape Tape storage media ZTMF-VAL-MediumMagneticDisk Magnetic disk storage media

ZTimeStamp

specifies the time when the audit dump was recorded. If null, the default is the current TMFSERVE time—that is, the current time is recorded into the catalog that has the audit dump being added.

ADD DUMPS

Caution. If recovery is needed, problems can occur if the time listed in the catalog is not the time when the dump actually took place. If you specify a value for ZTimeStamp, make sure to enter the date and time completely and accurately.

Usage Guidelines

Only super-group users can issue this command. For more information on the ADD DUMPS command, see the TMF Reference Manual.

HP NonStop TMF Management Programming Manual —540140-008

5-19

Commands and Responses

ADD MEDIA

The ADD MEDIA command adds one or more tape volumes to the TMF catalog. It also labels tape volumes.

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Add

Object Type

ZTMF-OBJ-Media

Tokens in Command Buffer

ADD MEDIA

ZTMF-TKN-Media token-type ZTMF-TYP-Media. ZTMF-MAP-Add-Media

def ZTMF-DDL-Add-Media. 02 ZMedium token-type ZSPI-DDL-Enum. 02 ZLabelMedia token-type ZSPI-DDL-Boolean. 02 ZOverWriteLabel token-type ZSPI-DDL-Boolean. 02 ZUnloadMedia token-type ZSPI-DDL-Boolean. 02 ZMediaStatus token-type ZSPI-DDL-Enum. 02 ZDensity token-type ZSPI-DDL-Enum. 02 ZTapeMode token-type ZSPI-DDL-Enum. 02 ZTapeDrive token-type ZSPI-DDL-Device. 02 ZOperatorDevice token-type ZSPI-DDL-DevName. end.

Tokens in Response Buffer

None.

Tokens in Command Buffer

ZTMF-TKN-Media

specifies the name of the storage media. This token is required; multiple occurrences are allowed.

HP NonStop TMF Management Programming Manual—540140-008

5-20

Commands and Responses

ZTMF-MAP-Add-Media

is an extensible structured token specifying the attributes of the media to be added to the TMF catalog. This token is required; only one occurrence is allowed. This token contains the following fields:

ZMedium

specifies the type of storage media. This field is required. The following values are valid:

ZTMF-VAL-MediumTape Tape storage media ZTMF-VAL-MediumMagneticDisk Magnetic disk storage media

ZLabelMedia

specifies whether a tape volume is to be labeled (in addition to being added to the TMF catalog). This field is required. The following values are valid:

ZSPI-VAL-True The tape volume is labeled.

ADD MEDIA

ZSPI-VAL-False The tape volume is not labeled.

ZOverWriteLabel

specifies whether an existing tape label is to be overwritten with a new tape label. This field is only valid if ZLabelMedia is ZSPI-VAL-True. The following values are valid (the default is ZSPI-VAL-False):

ZSPI-VAL-True Existing labels are overwritten. ZSPI-VAL-False Existing labels are not overwritten.

ZMediaStatus

specifies the status assigned to the media in the media catalog. This field is only valid if ZLabelMedia is ZSPI-VAL-False. The following values are valid:

ZTMF-VAL-Assigned

specifies that the tape volume contains valid dumps. If the catalog already contains an entry for the tape volume specified, an error message is returned.

ZTMF-VAL-Bad

specifies that the tape volume is defective and cannot be used later for dumping files or for file recovery.

ZTMF-VAL-Released

specifies that the contents of the tape volume are not required for file recovery.

HP NonStop TMF Management Programming Manual —540140-008

5-21

Commands and Responses

ZTMF-VAL-Scratch

specifies that the tape volume can be used for dumping files.

ZDensity

specifies the density at which the tapes are written. This field is only valid if ZLabelMedia is ZSPI-VAL-True. The following values are valid:

ZTMF-VAL-Default If this field is null, the default value depends

ZTMF-VAL-800BPI The density is 800 bits per inch. ZTMF-VAL-1600BPI The density is 1600 bits per inch. ZTMF-VAL-6250BPI The density is 6250 bits per inch.

ZTapeMode

specifies the kind of write operation performed by the tape drive and is applicable only for streaming tape drives. This field is only valid if ZLabelMedia is ZSPI-VAL-True. The following values are valid:

ADD MEDIA

upon the tape drive.

ZTMF-VAL-StartStop ZTMF-VAL-Stream ZTMF-VAL-StreamSlow ZTMF-VAL-StreamFast

If this field is null, the default value depends upon the tape drive. You can specify either ZDensity or ZTapeMode, but not both in the same command.

ZTapeDrive

specifies the name of the tape drive on which you want to label tape volumes. Guardian labeled-tape processing must be enabled on the node (system) you specify. This field is required if the value of ZLabelMedia is ZSPI-VAL-True.

ZOperatorDevice

specifies the name of the device on which TAPECOM prompts are to be displayed. This field is required if the value of ZLabelMedia is ZSPI-VAL-True.

Usage Guidelines

Only super-group users can issue this command. For more information on the ADD TAPEMEDIA command, see the TMF Reference

Manual.

HP NonStop TMF Management Programming Manual—540140-008

5-22

Commands and Responses

ADD RESOURCEMANAGER

The ADD RESOURCEMANAGER command adds one or more recoverable resource managers to the resource manager directory.

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Add

Object Type

ZTMF-OBJ-Rm

Tokens in Command Buffer

ADD RESOURCEMANAGER

ZTMF-TKN-RmName token-type ZSPI-TYP-String. ZTMF-TKN-RmOwnerID token-type ZSPI-TYP-UserID. ZSPI-TKN-MaxResp token-type ZSPI-TYP-Int. ZSPI-TKN-Context token-type ZSPI-TYP-ByteString.

Tokens in Response Buffer

ZTMF-TKN-RmName token-type ZSPI-TYP-String.

HP NonStop TMF Management Programming Manual —540140-008

5-23

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-RmName

specifies the name of a resource manager to be added to the resource manager directory. This token must appear at least once in the command buffer, and can appear multiple times to add multiple resource managers. If multiple resource managers are being added by a single command, the result of the operation is returned in a separate response record for each resource manager name.

Resource manager names can have a maximum length of 128 characters. The first character must be a letter, and the others can be alphanumeric or any of the following special characters:

$ _ - ^ @ &

Names beginning with the string ZZ-VOLATILE- are reserved, and therefore not allowed for this command. Names containing adjoining hyphens (--) are not allowed, although names using multiple hyphens separated by one or more intervening characters are legal. Thus, the name “ALPHA--1” is not permitted, but “ALPHA-N-1” is allowed.

ADD RESOURCEMANAGER

ZTMF-TKN-RmOwnerID

specifies the userid that will own the resource manager. The specified userid is used to restrict programmatic access to and removal of the resource manager by gateway processes. Only gateway processes running under a resource manager’s owner userid or one of the super group userids will be allowed to open or remove the resource manager .

Tokens in Response Buffer

ZTMF-TKN-RmName

specifies the name of the resource manager that was added to the directory or resulted in an error , depending upon the value of ZSPI-TKN-RetCode in the data or error list.

Usage Guidelines

Only super-group users can issue this command. TMF must be started for this command to execute successfully. If TMF is not started,

the error returned is ZTMF-ERR-TmfNotStarted. If the value specified for ZTMF-TKN-RmName is not a valid resource manager name,

the error returned is ZTMF-ERR-InvRmName. If the specified resource manager name is already registered in the directory, the error

returned is ZTMF-ERR-RmNameDuplicate.

HP NonStop TMF Management Programming Manual—540140-008

5-24

Commands and Responses

If no ZTMF-TKN-RmName tokens are supplied in the request, the error returned is ZTMF-ERR-MustSupplyRmName.

If the value specified for the ZSPI-TKN-Context token is not valid, the error returned is ZTMF-ERR-InvalidContext.

It is possible for TMF to discard the results of a command while they are still being retrieved by multiple requests with context. If that occurs, the error returned is ZTMFERR-ContextOutOfDate. In such a situation, it is possible that the command actually succeeded, but TMF discarded the results. This could occur if the TMP has processed more than ten commands for resource managers that required multiple requests to receive the results after the command was originally received.

For more information on the ADD RESOURCEMANAGER command, see the TMF Reference Manual.

ADD RESOURCEMANAGER

HP NonStop TMF Management Programming Manual —540140-008

5-25

Commands and Responses

ALTER AUDITDUMP

The ALTER AUDITDUMP command changes the configured attribute values of an audit dump process.

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Alter

Object Type

ZTMF-OBJ-AuditDump

Tokens in Command Buffer

ALTER AUDITDUMP

ZTMF-TKN-AuditTrailId token-type ZSPI-TYP-Enum. ZTMF-TKN-AddDiskMedia token-type ZTMF-TYP-String. ZTMF-TKN-DelDiskMedia token-type ZTMF-TYP-String.

ZTMF-MAP-Alter-AuditDump def ZTMF-DDL-Alter-AuditDump. 02 ZCopies token-type ZSPI-DDL-Int. 02 ZSeriesCopies token-type ZSPI-DDL-Boolean. 02 ZVerifyTape token-type ZSPI-DDL-Boolean. 02 ZBlockSize token-type ZSPI-DDL-Int. 02 ZUnloadMedia token-type ZSPI-DDL-Boolean. 02 ZMedium token-type ZSPI-DDL-Enum. 02 ZSystemName token-type ZSPI-DDL-Char8. 02 ZSystemName2 token-type ZSPI-DDL-Char8. end.

Tokens in Response Buffer

None.

HP NonStop TMF Management Programming Manual—540140-008

5-26

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-AuditTrailId

specifies the audit trail associated with the audit dump process whose attributes are to be altered. This token is required; only one occurrence is allowed. The following values are valid:

ZTMF-VAL-Mat Master audit trail ZTMF-VAL-Aux01 Auxiliary audit trail #1 ZTMF-VAL-Aux02 Auxiliary audit trail #2 . . . ZTMF-VAL-Aux015 Auxiliary audit trail #15 ZTMF-TKN-AddDiskMedia

specifies disk volumes to be added to the audit dump process configuration. This token is only valid if ZMedium is ZTMF-VAL-MediumMagneticDisk.

ALTER AUDITDUMP

This token can occur from zero to 16 times; however there is a maximum of 16 disk media attributes that can be configured for the process. If the limit is exceeded, the ZTMF-ERR-TooManyDiskMedia error is returned and the command fails. If the disk media to be added already exists in the configuration, the ZTMFERR-DiskMediaExists error is returned.

If you specify multiple disk volumes, the subsystem tries to send the audit dump to the first disk listed. If that disk cannot be accessed or is out of space, the subsystem tries the next disk, and so forth.

If you specify a disk that does not exist, the subsystem does not report this error at once; however, it does report the error when the next dump actually takes place.

ZTMF-TKN-DelDiskMedia

specifies disk volumes to be deleted from the audit dump process configuration. This token is only valid if ZMedium is ZTMF-VAL-MediumMagneticDisk.

This token can occur from zero to 16 times. If the disk media does not currently exist in the configuration, the ZTMF-ERR-DiskMediaNotFound message is returned.

HP NonStop TMF Management Programming Manual —540140-008

5-27

Commands and Responses

ZTMF-MAP-Alter-AuditDump

is an extensible structured token specifying the attributes of the audit dump process to be changed. This token is required; only one occurrence is allowed. This token contains the following fields:

ZCopies

for dumps to tape, specifies the number of copies made of each audit dump. The following values are valid:

If the value of ZCopies is ZTMF-VAL-ResetWord, the number of copies



made is reset to 1. If the value of ZSeries is ZSPI-VAL-False, the value of ZCopies can be 1 or



2. If the value of ZSeries is ZSPI-VAL-True, the value of ZCopies can be 1, 2,



or 3.

Specifying multiple copies is recommended to enable file recovery if one of the copies cannot be read.

ALTER AUDITDUMP

ZSeriesCopies

for dumps to tape, specifies whether multiple copies of audit dumps are made in parallel or in series. The following values are valid:

ZTMF-VAL-True Series copies are made. ZTMF-VAL-False Parallel copies are made.

ZVerifyTape

for dumps to tape, specifies whether tape verification is performed after a tape is written. The following values are valid:

ZTMF-VAL-True

Tapes are verified. After each tape volume is written, it is rewound, read completely, and finally rewound and unloaded. The tape-record checksums, tape-record sequence numbers, and tape format are verified. The checks are the same as those made during file recovery; however, tape verification does not include comparing the tape data to the audit trail files on disk.

If tape verification fails, an error is returned, the audit dump terminates, and the audit dump copy is marked invalid in the catalog. Tape verification approximately doubles the time needed for an audit dump.

ZTMF-VAL-False

Tapes are not verified.

HP NonStop TMF Management Programming Manual—540140-008

5-28

Commands and Responses

ZBlockSize

for dumps to tape, sets the tape data block length, when multiplied by 1024 bytes. It is more efficient to use large data block lengths, but this is limited by the density in bits per inch (bpi) at which the tape drive writes tapes. The following values are valid; the default is 8:

4 Tape data block length of 4096 bytes (800 bpi); recommended. 8 Tape data block length of 8192 bytes (1600 bpi); recommended. 12 Tape data block length of 12288 bytes. 16 Tape data block length of 16384 bytes. 20 Tape data block length of 20480 bytes. 24 Tape data block length of 24576 bytes. 28 Tape data block length of 28672 bytes (6250 bpi); recommended.

ZUnloadMedia

ALTER AUDITDUMP

for dumps to tape, specifies whether the tape is unloaded after the dump process finishes writing to the tape. The following values are valid:

ZTMF-VAL-True Tapes are unloaded after use. ZTMF-VAL-False Tapes are not unloaded after use.

ZMedium

specifies the type of storage media on which the audit dump is recorded. The following values are valid:

ZTMF-VAL-MediumTape Tape storage media. ZTMF-VAL-ResetMedium Tape storage media. ZTMF-VAL-MediumMagneticDisk Magnetic disk storage media.

If ZMedium is ZTMF-VAL-MediumMagneticDisk and there are no disk media attributes configured, then ZTMF-ERR-DiskMediaRequired is returned. If any of the tape-only fields are specified, then ZTMF-ERR-IllegalDiskOption is returned.

If ZMedium is ZTMF-VAL-MediumTape (or is null) and the command is successful, any previously configured disk media attributes are deleted automatically.

ZSystemName

for dumps to tape, specifies the name of the system on which the audit dump process performs automatic volume recognition (AVR). If the value of ZSystemName is ZTMF-VAL-ResetSystemName, the audit dump process performs AVR on the local system.

HP NonStop TMF Management Programming Manual —540140-008

5-29

Commands and Responses

ZSystemName2

for dumps to tape, specifies the name of the system on which the audit dump process performs automatic volume recognition (AVR) for the second parallel copy. If the value of ZSystemName2 is ZTMF-VAL-ResetSystemName2, the audit dump process performs AVR on the same system specified for ZSystemName.

Tokens in Response Buffer

ZTMF-TKN-DiskMediaString

contains the name of the disk media in error. This token is returned only if an error is returned.

Usage Guidelines

Only super-group users can issue this command.

ALTER AUDITDUMP

Only attributes which are specified with non-null values are modified. For more information on the ALTER AUDITDUMP command, see the TMF Reference

Manual.

HP NonStop TMF Management Programming Manual—540140-008

5-30

Commands and Responses

ALTER AUDITTRAIL

The ALTER AUDITTRAIL command changes the configured attribute values of an audit trail and can execute while TMF is running.

Command Syntax

For information on the tokens present in the command and response buffers, see the SPI Programming Manual.

Command

ZTMF-CMD-Alter

Object Type

ZTMF-OBJ-AuditTrail

Tokens in Command Buffer

ALTER AUDITTRAIL

ZTMF-TKN-AuditTrailId token-type ZSPI-TYP-Enum. ZTMF-TKN-AddActiveVolume token-type ZSPI-TYP-String. ZTMF-TKN-DelActiveVolume token-type ZSPI-TYP-String. ZTMF-TKN-AddOverflowVolume token-type ZSPI-TYP-String. ZTMF-TKN-DelOverflowVolume token-type ZSPI-TYP-String. ZTMF-TKN-AddRestoreVolume token-type ZSPI-TYP-String. ZTMF-TKN-DelRestoreVolume token-type ZSPI-TYP-String.

ZTMF-MAP-Alter-AuditTrail def ZTMF-DDL-Alter-AuditTrail. 02 ZFilesPerVolume token-type ZSPI-DDL-Int. 02 ZOverflowThreshold token-type ZSPI-DDL-Int. 02 ZBeginTransDisable token-type ZSPI-DDL-Int. 02 ZAuditDump token-type ZSPI-DDL-Boolean. 02 ZMaxRetainedATFiles token-type ZSPI-DDL-Int. 02 ZFileSize32 token-type ZSPI-DDL-Int2. 02 ZCommitHoldMode token-type ZSPI-DDL-Enum. 02 ZCommitHoldTimer token-type ZSPI-DDL-Int2. 02 ZTimeoutAction token-type ZSPI-DDL-Enum. end.

Tokens in Response Buffer

ZTMF-TKN-VolumeName token-type ZSPI-TYP-String. ZTMF-TKN-ATVolumeType token-type ZSPI-TYP-Enum. ZTMF-TKN-FS-Error token-type ZSPI-TYP-Int.

HP NonStop TMF Management Programming Manual —540140-008

5-31

Commands and Responses

Tokens in Command Buffer

ZTMF-TKN-AuditTrailId

specifies the audit trail to be altered. This token is required and must only appear once in the buffer. The following values are valid:

ZTMF-VAL-Mat Master audit trail ZTMF-VAL-Aux01 Auxiliary audit trail #1 ZTMF-VAL-Aux02 Auxiliary audit trail #2 . . . ZTMF-VAL-Aux015 Auxiliary audit trail #15

ZTMF-TKN-AddActiveVolume

specifies a volume to be added to the active-audit volumes. This token is optional; multiple occurrences are allowed but the total number of volumes configured as active volumes must not exceed 16 (and must be at least 1). You must specify a unique disk volume for each audit trail.

ALTER AUDITTRAIL

If the volume can be added, the current value of ZFilesPerV o lume (for the audit trail) determines how many files are preallocated on the volume when the command is processed. If the volume has insufficient space, the command fails.

Active-audit volumes are added to the end of the list of available volumes maintained by the subsystem; therefore, they might not be used immediately. Audit trail files are written to active-audit volumes sequentially, but the subsystem tries to avoid writing two audit trail files in succession to the same volume. When the subsystem is ready to write to an active-audit volume, it uses the next preallocated file that resides on that volume. Eventually, all preallocated files on the volume are used.

ZTMF-TKN-DelActiveVolume

specifies a volume to be deleted from the active volume list. The volume containing the audit file that is currently receiving audit information cannot be deleted. The volume holding the “Next” file (if it has been prepared) can also not be deleted. If the volume holds active files that are still needed by TMF, it is not removed from the active list immediately, but no new files are allocated to it. When the remaining files are no longer needed, they are purged. When all of the files have been purged, the volume is removed from the active file list.

At least one active volume must be configured for each audit trail. This token is optional; multiple occurrences are allowed but the total number of volumes configured as active volumes must be at least 1.

Deleting a volume from a configuration reduces the capacity of the active audit trail by the number of files specified in ZFilesPerVolume.

HP NonStop TMF Management Programming Manual—540140-008

5-32

Commands and Responses

ZTMF-TKN-AddOverflowVolume

specifies a volume to be added as an overflow volume for the audit trail. This token is optional; multiple occurrences are allowed but the total number of overflow volumes configured must not exceed 16.

ZTMF-TKN-DelOverflowVolume

specifies an overflow volume to be deleted. This token is optional; multiple occurrences are allowed.

If the volume currently holds overflow-audit files still needed by TMF, the volume is marked as “deleting”; no new files are allocated to it. When the remaining files are no longer needed, they are purged. When all files have been purged, the volume is removed from the overflow file list.

ZTMF-TKN-AddRestoreVolume

specifies a volume to be added as a restore volume for the audit trail. This token is optional; multiple occurrences are allowed but the total number of restore volumes configured must not exceed 16.

ALTER AUDITTRAIL

ZTMF-TKN-DelRestoreVolume

specifies a restore volume to be deleted. This token is optional; multiple occurrences are allowed but at least 1 volume must remain if audit dumping is configured.

If the volume currently holds restore-audit files, the volume is marked as “deleting”; no new files are allocated to it. When the remaining files are no longer needed, they are purged. When all of the files have been purged, the volume is removed from the restore file list.

ZTMF-MAP-Alter-AuditTrail

is an extensible structured token specifying the attributes of the audit trail that are to be changed. This token is required; only one occurrence is allowed. This token contains the following fields:

ZFilesPerVolume

specifies the number of audit trail files that reside on each active-audit volume configured. The minimum value is 1 and the maximum value is 100; the value of ZTMF-VAL-ResetWord is 5.

If the number of files per volume is increased, then extra preallocated files are created immediately on each active-audit volume to make up the difference between the old and new values. If this allocation fails, then the ALTER AUDITTRAIL command returns an error and the ZFilesPerVolume value stays the same as before.

HP NonStop TMF Management Programming Manual —540140-008

5-33

Commands and Responses

If the number of files is decreased, the action taken varies. Any preallocated files on the active-audit volume are purged up to the point where each active volume contains the new number of files per volume. If an active-audit volume contains more files than allowed by the new value specified for this field, TMF purges them (rather than renaming them) when they are no longer needed.

Increasing the value of ZFilesPerVolume is the recommended way of increasing the audit trail capacity, if there is sufficient space on the currently configured active-audit volumes. Using this technique evenly distributes the new files among all volumes, rather than concentrating them on any added volumes.

ZOverflowThreshold

specifies the percentage of audit trail capacity in use above which TMF begins overflow copying. This field is optional. The minimum value is 50 (percent) and the maximum value is 100 (percent); the value of ZTMF-VAL-ResetWord is 80 (percent).

ALTER AUDITTRAIL

ZBeginTransDisable

changes the threshold capacity at which new transactions are disallowed. The minimum value is 50, and the maximum value is 100.

specifies the percentage of audit trail capacity that can be consumed before TMF disables new transactions. When the consumed capacity exceeds this threshold, new transactions are not allowed. When the consumed capacity falls back below this threshold, new transactions are no longer disabled by audittrail usage. (However, new transactions can be disabled for other reasons, as explained under the ALTER BEGINTRANS on page 5-38.) The minimum value is 50 (percent) and the maximum value is 100 (percent); the value of ZTMFVAL-ResetWord is 90 (percent).

ZAuditDump

ZSPI-VAL-True Audit dumping is enabled. ZSPI-VAL-False Audit dumping is prevented.

If the value of this field is changed to ZSPI-V AL-True, the first file to be dumped is the current audit trail file at the time of the ALTER AUDITTRAIL command.

If the value of this field is changed to ZSPI-VAL-False, all files that have already been dumped will stay dumped. Any files which are not yet dumped will not be dumped. If an audit dump is in progress, it is aborted.

HP NonStop TMF Management Programming Manual—540140-008

5-34

Commands and Responses

ZMaxRetainedATFiles

specifies the maximum number of restored audit-trail files to retain on disk in the RestoreV ols for the specified audit trai l after the restored audit-trail files are no longer being used by a recovery process. The minimum value is 1, the maximum 9999.

ZFileSize32

specifies the size of the audit-trail files, in megabytes (MB). The minimum value is 1 and the maximum depends on the format of the audit-trail files, as follows:

For format 1 files: 2047 or the maximum disk size (if less than 2047 MB).



The default file size is 1024, resulting in files of 1024 MB (1024 x 1024 x 1024 bytes) each.

For format 2 files: 1048575 or the maximum disk size (if less than 1048575



MB). (1048575 equals 1 terabyte (TB) minus 1 megabyte (MB).) The default file size is 1024, resulting in files of 1024 MB (1024 x 1024 x 1024 bytes) each.

ALTER AUDITTRAIL

ZCommitHoldMode

specifies whether commit-hold mode is on, off, or suspended. The following values are valid:

ZTMF-VAL-ResetWord Resets the commit-hold attribute for the

specified audit trail to unconfigured.

ZTMF-VAL-ZLTCH-On Sets the commit-hold attribute for the

specified audit trail to on.

ZTMF-VAL-ZLTCH-Off Sets the commit-hold attribute for the

specified audit trail to off.

ZTMF-VAL-ZLTCH-Suspend Temporarily suspends the commit-hold

condition for TMF.

The following two fields are valid only if commit-hold mode is not off or unconfigured.

ZCommitHoldTimer

specifies the maximum time TMF stays in commit-hold condition, in seconds, once commit-hold mode is activated. Values can range from 5 to 86400. The value -1 specifies infinite. This field can only be specified for the MAT.

HP NonStop TMF Management Programming Manual —540140-008

5-35

Commands and Responses

ZTimeoutAction

specifies the desired timeout action. The following values are valid:

ZTMF-VAL-ZLTCH-ActionSuspend Suspend commit-hold mode for

ZTMF-VAL-ZLTCH-ActionCrash Crash TMF.

This field can only be specified for the MAT. This field is not valid if the ZCommitHoldTimer value is -1.

Tokens in Response Buffer

ZTMF-TKN-VolumeName

contains the name of a volume that was in error, if an error is returned. This token is not returned if no volume-related error is returned.

ZTMF-TKN-ATVolumeType

ALTER AUDITTRAIL

TMF.

contains the type of the volume specified in ZTMF-TKN-VolumeName. This token is only present if ZTMF-TKN-VolumeName is present. The following values are valid:

ZTMF-VAL-ActiveVol The disk volume that holds the audit trail

files.

ZTMF-VAL-OverflowVol The disk volume used as overflow space

for the audit trail.

ZTMF-VAL-RestoreVol The disk volume used when restoring audit

dumps.

ZTMF-TKN-FS-Error

contains the file-system error that may have caused the command to fail. Its presence depends on the value of ZSPI-Ret-Code.

ZTMF-TKN-DisconnTimer

contains the value from the NetDisconnectTimer command. This token is returned only if an error 388 is returned.

ZTMF-TKN-OldAutoAbort

contains the value of the AutoAbort timer. This token is returned only if an error 388 is returned.

HP NonStop TMF Management Programming Manual—540140-008

5-36

HP NonStop TMF Programming Manual

Specifications and Main Features

Frequently Asked Questions

User Manual