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
Copyright 2013 Hewlett-Packard Development Company L.P.
Confidential computer software. Valid license from HP required for possession, use or copying.
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.
© 1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to
which it relates are derived in part from materials supplied by the following:
© 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-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
i
Contents
1. Introduction to TMF (continued)
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
ii
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)
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
iv
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
v
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
vi
What’s New in This Manual
Manual Information
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
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
ix
What’s New in This Manual
Changes in the earlier version of the 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
x
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
xi
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
6)
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
In addition to the TMFCOM command and SPI programmatic interfaces provided with
the TMF, several other software products and interfaces support limited TMF
operations. Details about the TMF functionality they provide appear in the manuals that
cover these products and interfaces:
HP NonStop Operating System Procedure Calls
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
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
xv
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
Register Description
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
Loading...