HP NonStop TMF Application Programmer’s Guide Abstract This manual describes how to design requester modules and server modules that run in the HP NonStop™ Transaction Management Facility (TMF) programming environment on HP NonStop servers, and how to use the TMF audit-reading procedures. It discusses features and operations available with the TMF 3.7 product. Product Version TMF H01 Supported Releases This manual supports J06.03 and all subsequent J-series RVUs and H06.
Document History Part Number Product Version Published 540139-002 TMF H01 November 2005 540139-003 TMF H01 April 2006 540139-004 TMF H01 February 2009 540139-006 TMF H01 August 2010 540139-007 TMF H01 February 2012 540139-008 TMF H01 February 2013 540139-009 TMF H01 February 2014
Legal Notices Copyright 2005, 2014 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.
HP NonStop TMF Application Programmer’s Guide Index Examples Figures Tables Legal Notices What’s New in This Manual vii Manual Information vii New and Changed Information viii About This Manual xiii Who Should Read This Manual xiii How this Manual is Organized xiii About the TMF Library xiii Related Manuals xiii Notation Conventions xiv HP Encourages Your Comments xvii 1.
2. Designing Single-Threaded Processes Contents 2.
5. TMF ARLIB2 Audit-Reading Procedures Contents GETTRANSID 4-24 GETTRANSINFO 4-26 INTERPRETTRANSID 4-28 RESUMETRANSACTION 4-31 STATUSTRANSACTION 4-34 TEXTTOTRANSID 4-37 TMF_BEGINTAG_FROM_TXHANDLE_ TMF_GETTXHANDLE_ 4-43 TMF_GET_EXTTRANSID_ 4-44 TMF_GET_TX_ID_ 4-46 TMF_JOIN_ 4-48 TMF_JOIN_EXT_ 4-50 Usage Considerations 4-51 TMF_RESUME_ 4-53 TMF_SETTXHANDLE_ 4-55 TMF_SUSPEND_ 4-57 TMF_SUSPEND_EXT_ 4-59 TMF_TXBEGIN_ 4-61 TMF_TXHANDLE_FROM_BEGINTAG_ TRANSIDTOTEXT 4-65 TMF_VERSION_EXT_ 4-67 4-40 4-63 5.
Contents 5.
Index Contents ARPOSITION2 5-92 ARPRINTMESSAGE 5-94 ARREAD 5-95 ARSETOPTIONS 5-97 ARSTART 5-99 ARSTOP 5-101 ARSTOPNETWORKRECS 5-102 ARSTOPNONDATACHNGRECS 5-103 Error Codes 5-104 How to Include Audit Reading in an Application Use of AWAITIOX 5-112 5-111 Index Examples Example 5-1. IMAGEINFO and COLUMNINFO Definitions 5-76 Figures Figure 2-1. Figure 3-1. Figure 3-2. Figure 3-3. Figure 5-1. Figure 5-2.
Contents HP NonStop TMF Application Programmer’s Guide—540139-009 vi
What’s New in This Manual Manual Information HP NonStop TMF Application Programmer’s Guide Abstract This manual describes how to design requester modules and server modules that run in the HP NonStop™ Transaction Management Facility (TMF) programming environment on HP NonStop servers, and how to use the TMF audit-reading procedures. It discusses features and operations available with the TMF 3.7 product. Product Version TMF H01 Supported Releases This manual supports J06.
What’s New in This Manual New and Changed Information New and Changed Information Changes to the H06.28/J06.17 Manual Added a Note for the following procedure: ARLIB2 Compared to ARLIB on page 5-2. Changes to the H06.26/J06.15 Manual Added the procedure GETTRANSACTIONDETAILS on page 4-19. Added the procedure TMF_VERSION_EXT_ on page 4-67. Changes to the H06.24/J06.13 Manual Added the procedure TMF_GET_EXTTRANSID_ on page 4-44.
What’s New in This Manual Changes to the H06.24/J06.
What’s New in This Manual Changes to the H06.21/J06.10 Manual Changes to the H06.21/J06.10 Manual Supported release statements have been updated to include J-series RVUs. Added the following procedures: BEGINTRANSACTION_EXT_ on page 4-10 GETTRANSINFO on page 4-26 TMF_JOIN_EXT_ on page 4-50 TMF_SUSPEND_EXT_ on page 4-59 Updated the description of UPDATE (10) on page 5-27.
What’s New in This Manual Changes in the earlier version of the Manual flags on page 5-68 collation-def on page 5-68 Changed ARGETNONDATACHANGERECS to ARGETNONDATACHNGRECS on page 5-78. Added a new parameter, return-TypeFlags, under ARSETOPTIONS on page 5-97. Added the following error codes in Table 5-3, Error Codes by Class on page 5-94: -903 -904 -905 Updated the example in the How to Include Audit Reading in an Application on page 5-110.
What’s New in This Manual Changes in the earlier version of the Manual HP NonStop TMF Application Programmer’s Guide—540139-009 xii
About This Manual This manual also shows how to design requesters and servers to run effectively in that environment and describes a set of procedures that you can use to examine the contents of a TMF audit trail. Who Should Read This Manual This manual is intended for persons who design requester/server modules that run in the TMF 3.6 programming environment. How this Manual is Organized Section 1, TMF Programming Environment, provides an overview of the TMF programming environment.
Notation Conventions About This Manual Introduction to Data Management provides an overview of HP data-management products, including TMF, and discusses the use of those products in OLTP applications. Enscribe Programmer's Guide discusses writing applications for using TMF when accessing an Enscribe database. Guardian Procedure Calls Reference Manual describes the syntax of many system procedure calls that are used in OLTP applications.
General Syntax Notation About This Manual [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list may be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines.
General Syntax Notation About This Manual Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In the following example, there are no spaces permitted between the period and any other items: $process-name.#su-name Line Spacing.
Change Bar Notation About This Manual 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).
About This Manual HP Encourages Your Comments HP NonStop TMF Application Programmer’s Guide—540139-009 xviii
1 TMF Programming Environment The Transaction Management Facility (TMF) provides protection and concurrency control for HP NonStop SQL/MP and Enscribe files. Database integrity is vital to the success of any online transaction processing (OLTP) environment. It is imperative that data not become corrupted as the result of hardware or software failures, or conflicting operations performed concurrently against the same data.
TMF Programming Environment The TMF Transaction The TMF Transaction Within the TMF programming environment, program operations that modify the content of a protected database must be grouped together into TMF transactions. From a syntactical perspective, a TMF transaction is an executed sequence of code delimited by two unique programming statements: one indicating the start of the transaction and the other indicating the end of the transaction.
Initiating a Transaction TMF Programming Environment communications line failure during the cash withdrawal transaction, for example, should negate the successful outcome of the two preceding fund transfer operations. In this particular example, the situation is further complicated in that each of the individual business operations results in the issuance of a printed receipt to the customer upon successful completion of the operation.
Committing a Transaction TMF Programming Environment Committing a Transaction If a transaction completes successfully, the changes that it made to a protected database are made permanent; this is referred to as “committing the transaction.” You terminate a TMF transaction and commit the effects of that transaction by invoking the ENDTRANSACTION procedure.
TMF Programming Environment Heterogeneous Transaction Processing Heterogeneous Transaction Processing In heterogeneous transaction processing, TMF can start a transaction and then subcontract portions of the transaction (branches) to one or more foreign transaction management systems operating on platforms other than the HP system. Alternatively, a foreign transaction management system can begin a transaction and then subcontract parts to TMF.
TMF Programming Environment The Requester/Server Model The Requester/Server Model Many business applications that run on HP systems use the requester/server application design model to obtain input from end users and apply it to a database. In the most elementary case, a requester is the process that receives the initial request to perform a business operation requiring modification of a database.
TMF Programming Environment The Current Transaction Summary of Requester Actions In general, TMF requester processes do the following: Open any necessary server processes. Initiate TMF transactions. Format work requests describing the necessary database manipulations and send them to the appropriate servers by way of the message system. Receive reply messages from the servers, indicating success or failure. Terminate transactions.
TMF Programming Environment The Nil State The Nil State Requesters and servers start execution with their current transaction in the nil state. If a process attempts to lock or change the content of an audited file when the current transaction is in the nil state, the file system rejects the particular I/O request with a condition code of CCL and an error number 75 (no transaction identifier).
TMF Programming Environment Excluding a Server from a TMF Transaction Enhancing Performance in a Network Environment When a work request associated with a transaction identifier is transmitted from a requester process on one node of a network to a server process on another node, TMF generates additional messages and internal overhead (when the transaction is being either committed or aborted) beyond that required for messages not associated with a transaction identifier.
TMF Programming Environment Setting the Current Transaction to Nil Setting the Current Transaction to Nil A requester or server process sets its current transaction to the nil state by issuing a RESUMETRANSACTION call with a tag value of zero. In TAL, the call is as follows: status := RESUMETRANSACTION (0D); After setting the current transaction to the nil state, however, you must then explicitly reset it back to the transaction identifier of a currently active transaction.
TMF Programming Environment Consistency and Concurrency Consistency and Concurrency In the OLTP environment, there are three fundamental criteria that you can use to judge the integrity of a business database: The data must accurately reflect the results of all business operations performed against the database. In particular, all related data items must be accurate with regard to one another. Every total field, for example, must always equal the sum of all the detail items that it represents.
TMF Programming Environment Levels of Consistency 3. When accessing NonStop SQL/MP objects, specify REPEATABLE ACCESS for all database operations. 4. When accessing Enscribe files, obtain a file lock at the beginning of the transaction and then let the DP2 disk process release the file lock when the transaction commits. Note that the use of file locks with Enscribe files severely limits the amount of concurrent access, thereby reducing throughput and increasing the response time for end users.
TMF Programming Environment Levels of Consistency Finally, other transactions cannot update, delete, or insert anything within the entire range of rows accessed by the transaction. This guarantees you the opportunity to reread previously read rows and see exactly the same data values. You should specify REPEATABLE ACCESS for transactions that make business decisions based on values that they have obtained by first reading the database.
TMF Programming Environment Enscribe Capabilities been updated. A likely sequence of SQL statements for performing this operation would be as follows: UPDATE passenger SET flight-number = 701 WHERE flight-number = 429 FOR REPEATABLE ACCESS; With both REPEATABLE and STABLE access, every row that has been updated is protected against being deleted or changed by any other active transaction.
TMF Programming Environment Enscribe Capabilities with the same character sequence as the key of the referenced record. Generic locking applies only to key-sequenced files. READLOCK and READUPDATELOCK lock the record before reading it. WRITE locks the record that is being inserted. UNLOCKREC unlocks the current record (as determined by the most recent operation against the file). If generic locking is enabled for a key-sequenced file, calls to UNLOCKREC are ignored.
Enscribe Capabilities TMF Programming Environment 73 (file/record is locked). If a record with the same primary-key value already exists, the WRITE request is rejected with a condition code of CCL and an error 10 (file/record already exists). Table 1-1. Enscribe Locking Modes Mode param1 Description Normal mode 0 Any attempt to lock a file, or to read or lock a record, that is already locked through a different transaction identifier is suspended until the existing lock is released.
Enscribe Capabilities TMF Programming Environment between existing rows. While the transaction is in progress, no new rows can be inserted within the entire range of rows accessed by the transaction. Unless you lock an entire file, Enscribe does not provide this protection; therefore, applications using Enscribe files can encounter what is called “the inserted record problem.
Enscribe Capabilities TMF Programming Environment applications using Enscribe files can encounter what is called “the deleted record problem.” Consider the case in which one transaction (designated T2) is using a loop to read a sequence of employee records arranged in alphabetic order and another transaction (designated T2) has previously deleted one of the records.
TMF Programming Environment Enscribe Capabilities ENDTRANSACTION function. In almost any interactive environment, however, this practice is unacceptable because it precludes concurrent access.
TMF Programming Environment HP NonStop TMF Application Programmer’s Guide—540139-009 1-20 Enscribe Capabilities
2 Designing Single-Threaded Processes Application program modules are often designed as single-threaded processes. Singlethreaded requesters can only participate in one transaction at a time. Having initiated one transaction, a single-threaded requester cannot initiate another transaction until it has terminated the existing transaction. Similarly, single-threaded servers can do work on behalf of only one transaction at a time.
Designing Single-Threaded Processes Delegating Work to Servers RESUMETRANSACTION (tag)—resets the current transaction from the nil state to the transaction ID of the transaction identified by the specified BEGINTRANSACTION tag value WRITEREAD—sends a work request to a server process and accepts a reply from the server Delegating Work to Servers To subcontract a unit of work to a server process, the requester must: 1. Open the server process by using the FILE_OPEN_ system procedure. 2.
Designing Single-Threaded Processes Terminating Transactions Table 2-1. WRITEREAD Error Numbers (page 2 of 2) Error Number Meaning 248 A line handler failure occurred (the request was terminated). 249 A network failure occurred (the request was terminated). 250 All paths to a required system are down (the request did not get started). 251 A network protocol error occurred (the request was terminated). 252 A required Expand class is not available (the request did not get started).
Designing Single-Threaded Processes Terminating Transactions After being called, ABORTTRANSACTION returns control immediately to the requester. Because the disk process holds locks on the affected database records until after the relevant changes have been backed out, the requester can safely initiate a new transaction involving the same database files without fear of encountering inconsistent data.
Designing Single-Threaded Processes Terminating Transactions A network failure occurs. A transaction is pinning a file on the MAT, and 45% of the MAT fills during the transaction’s lifetime. The backup process of a process-pair or its processor fails after the transaction has been checkpointed (see Placement of Checkpoints on page 2-7).
Designing Single-Threaded Processes Checkpointing Strategy Table 2-2.
Designing Single-Threaded Processes Checkpointing Strategy BEGINTRANSACTION. Such requesters can ignore the existence of the TFILE altogether. If a requester is the primary process of a NonStop process pair, however, it must explicitly open the TFILE and then execute a CHECKOPEN call to create the backup requester’s copy of the TFILE. To open the TFILE, a single-threaded requester uses an FILE_OPEN_ call of the following form (illustrated in TAL).
Designing Single-Threaded Processes Checkpointing Strategy The processing of a transaction never transfers in midstream from the primary requester to the backup: the backup requester, upon sensing a failure of the associated primary process, either restarts the aborted transaction and performs it in its entirety (if there was a transaction in progress at the time of the failure) or moves on to the next transaction (if the failure occurred between transactions).
Checkpointing Strategy Designing Single-Threaded Processes Figure 2-1. Checkpointing Within Single-threaded Requesters Issue READ to get terminal input. Set up local storage with all the application data necessary to start the transaction. A Call CHECKPOINT. Specify both the application data necessary to start the transaction and the TFILE. Call BEGINTRANSACTION. Failure #1 Failure #3 Issue WRITEREAD call to server. Call ENDTRANSACTION. Failure #2 Yes B Specify the TFILE. Call CHECKPOINT.
Designing Single-Threaded Processes Checkpointing Strategy The procedure call for checkpoint A occurs when the primary process is about to initiate a transaction but has not yet issued the BEGINTRANSACTION call. At that point, the backup requester’s TFILE is updated to indicate that there is no current transaction. All of the application data necessary to start the new transaction is present in the data stack and data blocks that are copied to the backup process by the CHECKPOINT procedure.
Designing Single-Threaded Processes Single-Threaded Servers as a primary) should call ABORTTRANSACTION, start a new backup process, and then restart the transaction using the checkpointed application data. If RESUMETRANSACTION returns no error, TMF has not yet sufficiently processed the failure of the primary process to indicate that the transaction aborted. The application should call ABORTTRANSACTION, start a new backup process, and restart the transaction using checkpointed application data.
Designing Single-Threaded Processes Opening $RECEIVE Opening $RECEIVE To open the $RECEIVE pseudofile, a single-threaded server uses an FILE_OPEN_ call of the following form (illustrated in TAL). CALL FILE_OPEN_ ( filename:8 , filenumber , , , nowait-depth , 1 ); filename specifies the character string $RECEIVE. filenumber is the name of a variable into which the FILE_OPEN_ procedure returns a unique value identifying the $RECEIVE pseudofile.
Designing Single-Threaded Processes WRITEREAD to Another Server abortion: a requester cannot commit a transaction until all servers doing work under the transaction identifier have issued replies. There are some types of interprocess messages—notably status messages sent by the operating system—that do not require a reply. Because there is no way to know in advance what type of message is in $RECEIVE, TMF servers must always use READUPDATE to accept incoming messages.
Designing Single-Threaded Processes The Implications of REPLY A server is only allowed to call ABORTTRANSACTION when it is participating in an active transaction: that is, when the server’s current transaction is not nil. Once the server issues a reply to the requester, the server no longer has the ability to abort the transaction.
Designing Single-Threaded Processes Guarantees to Servers transactions have been aborted, the requesters open a new instance of the failed server and then restart each transaction from the beginning. As a result of this fundamental design characteristic of TMF, the processing of a failed server simply cannot be taken over in midstream by a backup process, and the use of checkpoints within a server is therefore meaningless.
Designing Single-Threaded Processes Context-Sensitive Servers HP NonStop TMF Application Programmer’s Guide—540139-009 2-16
3 Designing Multithreaded Processes Application program modules can be designed as multithreaded processes: for example, multithreaded requesters can have many transactions at the same time. Having initiated one transaction, a multithreaded requester can then initiate other transactions and switch from one transaction to another. Similarly, a multithreaded server can work on many transactions at the same time.
Designing Multithreaded Processes Manipulating the Current Transaction filename is the name of a variable containing the logical device name of the TMF Management Process. The name is always $TMP. You can obtain the name programmatically by calling the GETTMPNAME procedure. filenumber is the name of a variable into which the OPEN procedure returns a unique value identifying this instance of the TFILE. You use filenumber in AWAITIO calls to recognize completions of nowait ENDTRANSACTION calls.
Designing Multithreaded Processes Nowait ENDTRANSACTION Calls If the call to ABORTTRANSACTION or ENDTRANSACTION fails, the current transaction identifier remains unchanged and is the same identifier that was supplied to the procedure. Nowait ENDTRANSACTION Calls Because multithreaded requesters are designed to work on multiple transactions in an interleaved fashion, the requesters must be designed to use both nowait I/O and nowait ENDTRANSACTION calls.
Designing Multithreaded Processes Checkpointing Strategy The sample requester responds to all error conditions by aborting the transaction and refreshing the READ to the affected terminal. The requester does not try to determine what type of error occurred or to make any decisions based on the error condition. Individual Threads As illustrated in Figure 3-1, the sequence of activities in a multithreaded requester is basically the same as that of a TMF transaction in a single-threaded requester.
Designing Multithreaded Processes Checkpointing Strategy As illustrated in the BEGINTRANSACTION box in Figure 3-2, a CHECKPOINT call following the BEGINTRANSACTION call can satisfy both items 1 and 2 in the preceding list. To do that, however, the parameter list of the CHECKPOINT call must include references to all of the following: 1. The local storage variable containing the filenumber of the TFILE 2. The list of active transactions 3.
Checkpointing Strategy Designing Multithreaded Processes Figure 3-1. The Flow of an Individual Thread Issue Nowait READ to get terminal input. SUSPEND AWAITIO Completion? No Yes Set up local storage with all the data necessary to start the transaction. Call BEGINTRANSACTION. Include the transaction tag and the TFILE's file number in the parameter list along with the addresses of all local data blocks necessary to start the transaction. Call CHECKPOINT.
Checkpointing Strategy Designing Multithreaded Processes Figure 3-2.
Checkpointing Strategy Designing Multithreaded Processes Figure 3-3. Multithreaded Requester; Detailed Functionality BEGIN TRANSACTION Set up local storage with all the application data necessary to start the transaction. ISSUE WRITEREAD TO SERVER Issue a nowait WRITEREAD call to a server process. CALL BEGINTRANSACTION. Write the transaction tag to local storage. RESUME TRANSACTION Use the transaction tag returned by AWAITIO in a RESUMETRANSACTION call to resume the transaction.
Designing Multithreaded Processes Checkpointing Strategy by issuing a RESUMETRANSACTION call, followed by ENDTRANSACTION or ABORTTRANSACTION for each tag value in the tag list. If a transaction may have committed before the failure occurred, the RESUMETRANSACTION call returns error number 76 (transaction ended) in the status variable. In that case, the backup process (now acting as a primary) should call ENDTRANSACTION.
Designing Multithreaded Processes Checkpointing Strategy Upon return from either the ABORTTRANSACTION or CHECKPOINTTFILEENTRY code, the MAINLOOP code once again displays the application data form on the particular terminal’s screen, issues a nowait READ for the terminal, and then continues checking for further AWAITIO completions. The BEGINTRANSACTION Code When the MAINLOOP code detects operator input, control passes to the BEGINTRANSACTION code.
Designing Multithreaded Processes Checkpointing Strategy The ENDTRANSACTION Code When the MAINLOOP code receives indication that the final nowait WRITEREAD call for a transaction has completed successfully, control passes to the ENDTRANSACTION code. The major functions of the ENDTRANSACTION code are as follows: 1. Issue a RESUMETRANSACTION call, specifying the tag value returned by the AWAITIO completion. 2. Issue an ENDTRANSACTION call to commit the transaction. 3. Return control to the MAINLOOP code.
Designing Multithreaded Processes Multithreaded Servers Multithreaded Servers Multithreaded servers differ from single-threaded servers in the following ways: Multithreaded servers must open the $RECEIVE pseudofile with receive-depth greater than 1. Multithreaded servers must include the appropriate transaction tag in all REPLY calls.
Designing Multithreaded Processes Manipulating the Current Transaction Manipulating the Current Transaction Immediately after accepting an incoming work request from $RECEIVE, the server must call the LASTRECEIVE procedure to obtain the tag value associated with that work request. After each READUPDATE completion, the transaction identifier associated with the particular incoming work request becomes the server’s current transaction.
Designing Multithreaded Processes Multithreaded Requester/Server Processes Multithreaded Requester/Server Processes You can design program modules that simultaneously act as a multithreaded requester for some transactions and as a multithreaded server for others. These kinds of program modules must open both a TFILE and a $RECEIVE pseudofile (with options greater than 1 for the TFILE and receive-depth greater than 1 for $RECEIVE), but still have only one current transaction.
4 File System Procedures This section presents detailed reference information for those file system procedure calls that pertain directly to TMF. The descriptions are in alphabetic order by procedure name.
File System Procedures TMF_SETTXHANDLE_ on page 4-55 TMF_SUSPEND_ on page 4-57 TMF_SUSPEND_EXT_ on page 4-59 TMF_TXBEGIN_ on page 4-61 TMF_TXHANDLE_FROM_BEGINTAG_ on page 4-63 TRANSIDTOTEXT on page 4-65 TMF_VERSION_EXT_ on page 4-67 Note. For enabling 64-bit features, you can call the 64-bit APIs in the OSS environment using the LP64 memory option. In the Guardian environment, call the 64-bit APIs using Mix Mode.
ABORTTRANSACTION File System Procedures ABORTTRANSACTION This procedure aborts the current transaction (the transaction identified by the calling process’ current transaction identifier). Any application process that is working on a transaction can abort that transaction at any time for any reason. If a server process aborts a transaction, the requester (or its backup) that initiated the transaction must still explicitly terminate the transaction by calling either ENDTRANSACTION or ABORTTRANSACTION.
ABORTTRANSACTION File System Procedures 76 The requester called ABORTTRANSACTION while the transaction was already in the process of ending (the transaction therefore cannot be aborted or resumed). 82 TMF not running. 84 TMF not configured. 97 Transaction already aborted. For a list of file system error numbers, refer to the Operator Messages Manual.
File System Procedures ACTIVATERECEIVETRANSID ACTIVATERECEIVETRANSID Servers use this procedure to set their current transaction to the transaction identifier of a particular work request queued in $RECEIVE. In the call, you supply a message tag that you initially obtained by calling the LASTRECEIVE procedure immediately after the READUPDATE call that accepted the message.
File System Procedures ACTIVATERECEIVETRANSID The function value returned by ACTIVATERECEIVETRANSID, which indicates the condition code, can be interpreted by _status_lt() , _status_eq() , or _status_gt() (defined in the file tal.h ).
BEGINTRANSACTION File System Procedures BEGINTRANSACTION This procedure initiates a new transaction. When you call this procedure, TMF creates a unique transaction identifier that distinguishes the new transaction from all other active transactions. The new transaction identifier becomes the current transaction of the calling process. The form of the transaction identifier is as follows: Transaction ID Description transid[0].
File System Procedures BEGINTRANSACTION Syntax for TAL Programmers status := BEGINTRANSACTION ( [ trans-begin-tag ] ); HP NonStop TMF Application Programmer’s Guide—540139-009 4-8 ! o
BEGINTRANSACTION File System Procedures Parameters returned value status INT is a file system error number: 0 Successful completion. 30 System unable to obtain message block, or is already using its maximum number of RECEIVE or SEND message blocks. 82 TMF not running.
BEGINTRANSACTION_EXT_ File System Procedures BEGINTRANSACTION_EXT_ This procedure initiates a new transaction. The procedure is the same as BEGINTRANSACTION except that it includes two new parameters to specify the transaction type, and a timeout value for the transaction. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
BEGINTRANSACTION_EXT_ File System Procedures 84 TMF not configured. 86 Audit trail at begin-trans-disable threshold, or operator has disabled the BEGINTRANSACTION procedure. 98 TFILE was opened using a nonzero sync-depth and all transaction control blocks (TCBs) within the caller’s CPU are currently occupied. 590 The parameter value is invalid. For a list of file system error numbers, see the Operator Messages Manual. trans-begin-tag output INT(32) :ref or INT(32) .
File System Procedures COMPUTETRANSID STRUCT Type_Flags_Struct (*) FIELDALIGN (SHARED2); BEGIN Fixed Flags[0:-1]; UNSIGNED(8) User_Info; These bits may be set by the customer and are not the concern of TMF. Note: 8 bits allows 256 possibilities. These bits will not be evaluated by TMF, they will simply be carried with the transaction. BIT_FILLER 53; Reserved bits for HP internal use. Should be initialized to zero.
COMPUTETRANSID File System Procedures Syntax for TNS Programmers #include short COMPUTETRANSID ( long long _far *transid , long system , short cpu , long sequence , [ short tm-flags ] ); Syntax for TNS/E Programmers #include short COMPUTETRANSID ( long long _ptr64 *transid , int system , short cpu , int sequence , [ short tm-flags ] ); Syntax for TAL Programmers status := COMPUTETRANSID ( , , , , transid system cpu sequence [tm-flags ] ); ! !
File System Procedures COMPUTETRANSID For a list of file system error numbers, refer to the Operator Messages Manual. output transid FIXED .EXT:ref:1 or INT .EXT:ref:4 or FIXED .EXT64:ref:1 or INT .EXT64:ref:4 is the internal name of the transaction identifier. input system INT(32):value is a required system number in the range 0 through 254. input cpu INT:value is a required CPU number in the range 0 through 15. input sequence INT(32):value is a required sequence number greater than 0.
ENDTRANSACTION File System Procedures ENDTRANSACTION This procedure commits the database changes associated with the current transaction. The only application process that can execute an ENDTRANSACTION call is the requester process that initiated the particular transaction. When a requester calls ENDTRANSACTION, TMF attempts to commit the changes made to the database by the transaction.
ENDTRANSACTION File System Procedures 78 Invalid or obsolete transaction identifier. 81 Outstanding nowaited I/O requests exist for the current transaction. 82 TMF not running. 84 TMF not configured. 90 Transaction’s parent process failed. 91 The TMF subsystem failed and the transaction final outcome is unknown. When TMF is re-started, if the transaction has not been completely committed, it will automatically be aborted and all changes will be removed.
GETTMPNAME File System Procedures GETTMPNAME This procedure returns the logical device name of the TMF Management Process (TMP) defined during system configuration. You need to know the TMP name, which is always $TMP, in order to open the TFILE. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
File System Procedures GETTMPNAME INT .EXT64:ref:12 is the name of a 12-word array into which GETTMPNAME returns the device name of the TMP. This name can then be passed to the OPEN procedure to open the TFILE. To call the FILE_OPEN_ procedure, pass a byte-addressable array that has the same location as devname along with a length value of 4. If the TMP is not configured, the returned device name is all blanks. A process can open the TFILE only once.
GETTRANSACTIONDETAILS File System Procedures GETTRANSACTIONDETAILS This procedure returns transaction related information like TransID, TXID, TxHandle, type flags, begin tag, and process handle of the process that had begun the transaction. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
GETTRANSACTIONDETAILS File System Procedures Syntax for TAL Programmers error := GetTransactionDetails (InputID, TransID, TXID, TXHandle, TypeFlags, Phandle, BeginTag); CALLABLE, EXTENSIBLE; Parameters returned value error INT is an error number indicating the outcome of an operation. The following are the possible errors: FEOK Successful completion. FEMISSPARAM Missing parameter(s). FENOTRANSID Current transaction in NIL state. FEINVTRANSID Invalid or obsolete transaction identifier.
File System Procedures GETTRANSACTIONDETAILS TxHandle TypeFlags Phandle BeginTag At least one of TransID, TXID, TxHandle, TypeFlags, or Phandle must be passed as output parameter. If InputID = 1 It indicates that TransID is passed as input. In this case, the API retrieves the following details based on the TransID: TXID TxHandle TypeFlags Phandle BeginTag At least one of TXID, TxHandle, TypeFlags, or Phandle must be passed as output parameter.
GETTRANSACTIONDETAILS File System Procedures Phandle BeginTag At least one of TransID, TXID, TypeFlags, or Phandle must be passed as output parameter. input/output TransID FIXED .EXT:REF:1 or FIXED .EXT64:REF:1 TransID can be passed as an input parameter by setting the InputID to 1. TransID must be local when it is passed as an input parameter. This is an optional parameter.
GETTRANSACTIONDETAILS File System Procedures output TypeFlags FIXED .EXT:REF:1 or FIXED .EXT64:REF:1 This is an optional parameter. If this attribute is passed, one of the following is returned: The type flags of the transaction of the corresponding TransID, TXID, or TxHandle that is passed when InputID is set to 1, 2, or 3. The type flags of the current transaction when the InputID is set to 0. output Phandle INT .EXT:REF:10 or INT .EXT64:REF:10 This is an optional parameter.
GETTRANSID File System Procedures GETTRANSID This procedure returns the transaction identifier of the calling process’ current transaction.. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
GETTRANSID File System Procedures output transid INT:ref:4 or INT .EXT64:ref:4 is a four-word array into which GETTRANSID returns the transaction identifier of the current transaction. Its form is as follows: Transaction ID Description transid[0].<0:7> contains 1 plus the Expand system number of the system in which BEGINTRANSACTION was called (this field contains 0 if the originating system is not part of a network). The system number identifies the home node of the transaction. transid[0].
GETTRANSINFO File System Procedures GETTRANSINFO This procedure returns the exttransid and transaction type flags. Use GETTRANSINFO when the calling process wants to pass exttransid to another process in the same Expand network so that the process can call TMF_JOIN_EXT_. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
File System Procedures GETTRANSINFO output transid FIXED .EXT:ref:1 or FIXED .EXT64:ref:1 is the transaction identifier in internal format as obtained from GETTRANSID. type_flags output FIXED .EXT:ref:1 or FIXED .EXT64:ref:1 the transaction type flags for the current transaction. This parameter is optional. Note. EPTAL callers can pass 64-bit pointers by specifying the compiler directives __EXT64 and SETTOG _64BIT_CALLS before sourcing from the EXTDECS file.
INTERPRETTRANSID File System Procedures INTERPRETTRANSID This procedure converts the supplied transaction identifier from internal form to its individual external numeric parts. If the conversion fails (status <> 0), all output parameters are undefined. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
INTERPRETTRANSID File System Procedures is a TMF or file system error number: -2 Invalid internal transaction identifier (TMF). -1 Missing tm-flags parameter (TMF). 0 Successful completion. 22 Invalid reference parameter. 29 Missing parameter(s). 82 TMF not running. 84 TMF not configured. For a list of file system error numbers, refer to the Operator Messages Manual.
File System Procedures INTERPRETTRANSID input transid FIXED:value is the transaction identifier in internal format as obtained from GETTRANSID. output system INT(32) .EXT:ref:1 or INT(32) .EXT64:ref:1 is the system number. output cpu INT .EXT:ref:1 or INT .EXT64:ref:1 is the CPU number. output sequence INT(32) .EXT:ref:1 or INT .EXT64:ref:1 is a sequence number greater than 0. output tm-flags INT .EXT:ref:1 or INT .EXT64:ref:1 is a number representing flags used internally by TMF. Note.
File System Procedures RESUMETRANSACTION RESUMETRANSACTION This procedure sets the current transaction of the calling process either to the nil state or to the transaction identifier of the specified transaction. You identify the desired transaction by supplying the trans-begin-tag returned by a previous call to BEGINTRANSACTION.
RESUMETRANSACTION File System Procedures Syntax for TAL Programmers status := RESUMETRANSACTION ( trans-begin-tag ); ! i Parameters returned value status INT is a file system error number: 0 Successful completion. 76 Transaction ending or aborting. 78 Invalid or obsolete transaction identifier. 82 TMF not running. 84 TMF not configured. 90 Transaction’s parent process failed. 92 Path to a participating network node failed.
File System Procedures RESUMETRANSACTION When issued by the primary requester process of a process pair, RESUMETRANSACTION does not change the current transaction identifier of the backup process.
STATUSTRANSACTION File System Procedures STATUSTRANSACTION In addition to determining the status of a transaction, this procedure optionally accepts a transaction identifier as an input parameter. If you omit the transaction identifier from the call, STATUSTRANSACTION returns the status of the current transaction. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
STATUSTRANSACTION File System Procedures 78 Calling process’ current transaction in the nil state. 82 TMF not running. 84 TMF not configured. For a list of file system error numbers, refer to the Operator Messages Manual.
File System Procedures STATUSTRANSACTION trans-status output INT .EXT:* or INT .EXT64:ref:1 is the status of the transaction, as follows: 1 ACTIVE 2 PREPARED 3 COMMITTED 4 ABORTING 5 ABORTED 6 HUNG input transid FIXED:value is an optional transaction identifier (in internal form). If this parameter is omitted, STATUSTRANSACTION returns the status of the current transaction. Note.
File System Procedures TEXTTOTRANSID TEXTTOTRANSID This procedure converts a transaction identifier from external ASCII form to internal form. If the conversion fails (status <> 0), all output parameters are undefined. If the string pointed to by the text parameter does not include a system name or number and the local system is a named system, TEXTTOTRANSID uses the local Expand node number as the system number.
TEXTTOTRANSID File System Procedures is a TMF or file system error number: -6 Additional characters in transaction identifier (TMF). -5 text-byte-length out of range (TMF). -4 Invalid system name or number (TMF). -3 Invalid TMF flags value (TMF). -2 Invalid CPU (TMF). -1 Invalid sequence (TMF). 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 82 TMF not running. 84 TMF not configured. For a list of file system error numbers, refer to the Operator Messages Manual.
File System Procedures TEXTTOTRANSID Note. EPTAL callers can pass 64-bit pointers by specifying the compiler directives __EXT64 and SETTOG _64BIT_CALLS before sourcing from the EXTDECS file.
File System Procedures TMF_BEGINTAG_FROM_TXHANDLE_ TMF_BEGINTAG_FROM_TXHANDLE_ This procedure returns the begin-transaction-tag associated with the specified transaction handle. The returned tag matches the one returned by the BEGINTRANSACTION procedure, if the calling process began the transaction. It also matches the tag returned by AWAITIO[X] to indicate completion of a nowaited ENDTRANSACTION call.
TMF_BEGINTAG_FROM_TXHANDLE_ File System Procedures is a file system error number: 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 82 TMF not currently running. 84 TMF not configured. 715 Invalid transaction handle. For a list of file system error numbers, refer to the Operator Messages Manual.
File System Procedures TMF_BEGINTAG_FROM_TXHANDLE_ input tx-handle INT .EXT:ref:10 or INT .EXT64:ref:10 specifies the transaction handle associated with the transaction whose begintransaction-tag is to be returned. trans-begin-tag output INT(32) .EXT:ref:1 or INT(32) .EXT64:ref:1 returns the begin-transaction-tag associated with the supplied transaction handle. Note.
TMF_GETTXHANDLE_ File System Procedures TMF_GETTXHANDLE_ This procedure returns the transaction handle of the current transaction. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
TMF_GET_EXTTRANSID_ File System Procedures specifies the transaction handle of the current transaction of the calling process. The size of the returned handle is 20 bytes. Note. EPTAL callers can pass 64-bit pointers by specifying the compiler directives __EXT64 and SETTOG _64BIT_CALLS before sourcing from the EXTDECS file. TMF_GET_EXTTRANSID_ This procedure returns the exttransid associated with the current transaction of the process. Note. This procedure cannot be called by TNS applications.
File System Procedures TMF_GET_EXTTRANSID_ For a list of file system error numbers, refer to the Operator Messages Manual exttransid output FIXED .EXT:ref:2 or FIXED .EXT64:ref:2 the transactional identifier that can be used for a subsequent TMF_JOIN_EXT_ call, either in the calling process or in another process in the same EXPAND network. type_flags output FIXED .EXT:ref:1 or FIXED .EXT64:ref:1 the transaction type flags for the current transaction. This parameter is optional. Note.
TMF_GET_TX_ID_ File System Procedures TMF_GET_TX_ID_ This procedure extracts a transactional identifier (txid) from a transaction handle. The identifier is only valid within the lifetime of the calling process or until TMF is either shut down or crashes. The returned identifier can be used in calls to TMF_RESUME_ to specify the transaction to be resumed by the process. The same transactional identifier is returned by TMF_SUSPEND_. Syntax for C Programmers Note.
TMF_GET_TX_ID_ File System Procedures 82 TMF not running. 84 TMF not configured. 715 Invalid transaction handle. For a list of file system error numbers, refer to the Operator Messages Manual. input tx-handle INT .EXT:ref:10 or INT .EXT64:ref:10 specifies the transaction handle associated with the transaction whose transactional identifier is to be returned. output txid FIXED .EXT:ref:1 or FIXED .EXT64:ref:1 a transactional identifier to be used in a subsequent call to TMF_RESUME_ or TMF_JOIN_.
File System Procedures TMF_JOIN_ TMF_JOIN_ This procedure allows a process to participate in a transaction initiated by another process without taking over as the ENDTRANSACTION caller. TMF_JOIN_ can be called by more than one process in the same Expand node at the same time. The BEGINTRANSACTION caller need not call TMF_SUSPEND_ before another process calls TMF_JOIN_ and can participate in the transaction at the same time. Joining a transaction means: Making the transaction the current transaction.
TMF_JOIN_ File System Procedures Syntax for TAL Programmers status := TMF_JOIN_ ( txid ) CALLABLE, EXTENSIBLE; ! i Parameters returned value status INT is a file system error number: 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 76 Transaction ending or aborting. 78 Invalid transaction identifier or transaction not started on this EXPAND node. 82 TMF not running.
TMF_JOIN_EXT_ File System Procedures TMF_JOIN_EXT_ This procedure allows a process to participate in a transaction, initiated by another process, without taking over as the ENDTRANSACTION caller. TMF_JOIN_EXT_ can be called by more than one process in any node in the beginner’s Expand network at the same time. The BEGINTRANSACTION caller need not call TMF_SUSPEND_EXT_ before another process calls TMF_JOIN_EXT_ and can participate in the transaction at the same time.
Usage Considerations File System Procedures 76 Transaction ending or aborting. 78 Invalid transaction identifier. 82 TMF not running. 83 Too many transactions (a single-threaded requester tried to initiate a transaction while a transaction is in progress, or a multithreaded requester attempted to initiate more concurrent transactions than there were TFILE entries). 84 TMF not configured. 721 BEGINTRANSACTION not completed.
File System Procedures Usage Considerations to TMF_JOIN_EXT_ is issued, the call is rejected with file system error FETOOMANYTRANSBEGINS (too many transactions). If the calling process is the primary process of a process pair and the TFILE is being checkpointed, the calling process should checkpoint the TFILE after calling TMF_JOIN_EXT_ to modify the backup process' TFILE.
File System Procedures TMF_RESUME_ TMF_RESUME_ This procedure allows a process to resume a previously suspended transaction. Resuming a transaction means: 1. Making the transaction the current transaction 2. Taking over as the ENDTRANSACTION caller for the transaction After successfully resuming a transaction, the calling process can then issue an ENDTRANSACTION call.
TMF_RESUME_ File System Procedures Parameters returned value status INT is a file system error number: 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 76 Transaction ending or aborting. 78 Invalid transaction identifier or transaction not started on this EXPAND node. 82 TMF not running.
TMF_SETTXHANDLE_ File System Procedures TMF_SETTXHANDLE_ This procedure sets the current transaction to the one associated with the specified transaction handle. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
File System Procedures TMF_SETTXHANDLE_ input tx-handle INT .EXT:ref:10 or INT .EXT64:ref:10 specifies the transaction handle of the transaction that is to become the current transaction. Note. EPTAL callers can pass 64-bit pointers by specifying the compiler directives __EXT64 and SETTOG _64BIT_CALLS before sourcing from the EXTDECS file.
File System Procedures TMF_SUSPEND_ TMF_SUSPEND_ This procedure allows the calling process to relinquish its duties as ENDTRANSACTION caller for the current transaction, provided the transaction was begun by or resumed by the calling process. A successful call to TMF_SUSPEND_ is referred to as suspending the transaction.
TMF_SUSPEND_ File System Procedures Syntax for TAL Programmers status := TMF_SUSPEND_ ( txid ) CALLABLE, EXTENSIBLE; ! o Parameters returned value status INT is a file system error number: 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 75 No current transaction. 76 Transaction ending or aborting. 78 Invalid transaction identifier or transaction not started on this EXPAND node. 81 Outstanding nowaited I/O requests exist for the specified transaction.
File System Procedures TMF_SUSPEND_EXT_ TMF_SUSPEND_EXT_ This procedure allows the calling process to relinquish control of a transaction— the current transaction of the calling process. Applications that use TMF_JOIN_EXT_ must also use TMF_SUSPEND_EXT_.
TMF_SUSPEND_EXT_ File System Procedures Parameters returned value status INT is a file system error number: 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 75 No current transaction. 76 Transaction ending or aborting. 78 Invalid transaction identifier or transaction not started on this EXPAND node. 81 Outstanding nowaited I/O requests exist for the specified transaction. 82 TMF not running. 84 TMF not configured.
TMF_TXBEGIN_ File System Procedures TMF_TXBEGIN_ This procedure is the same as BEGINTRANSACTION except that it includes a new parameter to specify a timeout value. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
TMF_TXBEGIN_ File System Procedures 84 TMF not configured. 86 Audit trail at begin-trans-disable threshold, or operator has disabled the BEGINTRANSACTION procedure. 98 TFILE was opened using a nonzero sync-depth and all transaction control blocks (TCBs) within the caller’s CPU are currently occupied. For a list of file system error numbers, refer to the Operator Messages Manual.
TMF_TXHANDLE_FROM_BEGINTAG_ File System Procedures TMF_TXHANDLE_FROM_BEGINTAG_ This procedure returns the transaction handle associated with the specified begintransaction-tag. Syntax for C Programmers Note. This procedure can be called from 32-bit and 64-bit applications.
File System Procedures TMF_TXHANDLE_FROM_BEGINTAG_ For a list of file system error numbers, refer to the Operator Messages Manual. trans-begin-tag input INT(32) specifies the begin-transaction-tag associated with the transaction whose transaction handle is to be returned. output tx-handle INT .EXT:ref:10 or INT .EXT64:ref:10 returns the transaction handle associated with the supplied begin-transaction-tag. The size of the returned handle is 20 bytes. Note.
File System Procedures TRANSIDTOTEXT TRANSIDTOTEXT This procedure converts a transaction identifier from internal form to external ASCII form. If the conversion fails (status <> 0), all output parameters are undefined. Note. Attempts to pass a transactional identifier (txid) to the TransIdToText procedure instead of a transaction identifier (transid) will fail with a return code of -1. For information about txIds, see the TMF_GET_TX_ID_ procedure description.
TRANSIDTOTEXT File System Procedures Syntax for TNS/E Programmers #include short TRANSIDTOTEXT ( long long transid , char _ptr64 *text , short text-byte-length , short _ptr64 *bytes-used ); Syntax for TAL Programmers status := TRANSIDTOTEXT ( transid , text , text-byte-length , bytes-used ); ! ! ! ! i o i o Parameters returned value status INT is a TMF or file system error number: -2 String too short (TMF). -1 Invalid internal transaction identifier (TMF).
File System Procedures TMF_VERSION_EXT_ is the name of the string variable into which TRANSIDTOTEXT is to store the external ASCII form of the transaction identifier. input text-byte-length INT:value specifies the maximum number of bytes available in the string variable pointed to by the text parameter. Any value greater than 3 is acceptable. bytes-used output INT .EXT:ref:1 or INT .
TMF_VERSION_EXT_ File System Procedures Syntax for TNS/E Programmers #include short TMF_VERSION_EXT_ ( , , , , , , , , , , , short _ptr64* short _ptr64 * char _ptr64 * short char _ptr64 * short char _ptr64* short short _ptr64* short _ptr64 * short _ptr64 * short _ptr64 *); Syntax for TAL Programmers Error := TMF_VERSION_EXT_ ( Version , SubVersion , Platform_String:Platform_Max_Len , Release_String:Release_Max_Len , Release_Date_String:Release_Date_Max_Len , Platform_Re
File System Procedures TMF_VERSION_EXT_ Int .EXT64:REF:1 is an optional output parameter. Version returns the current version of the TMF installed on a NonStop system. For example, if TMF 3.7 is installed on a NonStop system, Version returns 3. SubVersion output Int .EXT:REF:1 or Int .EXT64:REF:1 is an optional output parameter. SubVersion returns the current subversion of the TMF installed on a NonStop system. For example, if TMF 3.7 is installed on a NonStop system, SubVersion returns 7.
File System Procedures TMF_VERSION_EXT_ is an optional input parameter. This option is required when Release_String is passed. Release_Max_Len must be set to the maximum length in bytes of the Release_String output buffer. Release_Date_String output String .EXT:REF:* or String .EXT64:REF:* is an optional output parameter. Release_Date_String returns the release date of the software product revision installed on a NonStop system.
File System Procedures TMF_VERSION_EXT_ Int .EXT64:REF:1 is an optional output parameter. This option is required when Release_Date_String is passed. Release_Date_Return_Len returns the length in bytes of the Release_Date_String output parameter. Error_Detail output Int .EXT:REF:1 or Int .EXT64:REF:1 is an optional output parameter. For a non-zero value of error, Error_Detail returns the position of the parameter, which caused the first error.
File System Procedures TMF_VERSION_EXT_ HP NonStop TMF Application Programmer’s Guide—540139-009 4-72
5 TMF ARLIB2 Audit-Reading Procedures This section describes the ARLIB2 audit-reading interface that is available in the H06.03 and later release version updates (RVUs) of the TMF product. The TMF ARLIB2 audit-reading interface allows you to programmatically examine TMF audit records for SQL/MX, SQL/MP, and Enscribe objects. The interface consists of two parts: a set of procedures that you bind into your program and a set of data definitions that describe the information returned by the procedures.
TMF ARLIB2 Audit-Reading Procedures ARLIB2 Compared to ARLIB Once TMF audit-reading procedures are bound into your program, you can use them to open an audit-trail file and read individual records from that file. Rather than return entire audit records, the procedures return only those fields that contain information useful to you from only those records useful to you. Fields and records that are only of use to TMF are not accessible.
TMF ARLIB2 Audit-Reading Procedures Cursors ARFETCHMXBEFOREDATA2 Copies the before-image field from an SQL/MX audit record to the application buffer (uses byte maps). ARFETCHMXAFTERDATA Copies the after-image field from an SQL/MX audit record to the application buffer (uses bit maps). ARFETCHMXAFTERDATA2 Copies the after-image field from an SQL/MX audit record to the application buffer (uses byte maps).
TMF ARLIB2 Audit-Reading Procedures Cursor Positioning Cursor Positioning You declare the location and direction of a cursor by using the ARPOSITION procedure. Each ARPOSITION call supplies the cursor number, the sequence number of the audit-trail file, an initial byte offset into the file, and the direction in which the cursor is to move for successive reads.
TMF ARLIB2 Audit-Reading Procedures Retrieving Information From Audit Records Retrieving Information From Audit Records Once you position a cursor, each call to ARREAD reads the audit record at the cursor position. ARREAD returns the fixed-length fields and common attributes in a record structure. The audit-trail file sequence number and RBA returned by ARREAD permit you to position the cursor directly at that record if you need to later.
TMF ARLIB2 Audit-Reading Procedures Error Reporting How you go about retrieving the key or record address of a data record whose modification is recorded in the audit trail depends upon the file type and the type of audit record. For key-sequenced files, the key of the record is present in the before-image and after-image of the record.
TMF ARLIB2 Audit-Reading Procedures Procedural Retrieval of Message Text Procedural Retrieval of Message Text When messages corresponding to error codes are printed on the operator terminal, the error information is normally remembered by the associated cursor. The text of the most recent message generated for a given cursor is available by calling the ARPRINTMESSAGE or ARGETMESSAGELINE procedures. ARPRINTMESSAGE copies the message text to a file whose filenumber is passed to the procedure.
TMF ARLIB2 Audit-Reading Procedures Reading Active Audit Files Reading Active Audit Files The TMF audit-reading procedures use large physical transfers when reading audit files from disk. The audit-trail file is read from the disk into cache memory and records are then retrieved from cache into your application buffer. Note. Updates belonging to different volumes might not be written to the audit trail in the same sequence as the updates happen in the actual transaction.
TMF ARLIB2 Audit-Reading Procedures Reading a Range of Audit-Trail Files 3. Retrieve successive audit records by repeatedly calling ARREAD. When reading forward, ARE-END-OF-AUDIT indicates that you have reached the end of the current active audit file. To retrieve newly added audit records, pause briefly and then issue another ARREAD. That call will return either a new audit record (if available) or an ARE-END-OF-AUDIT message. If the call returns a new audit record, issue another ARREAD.
TMF ARLIB2 Audit-Reading Procedures Reading a Merged Audit Trail With a MERGE Cursor 3. Retrieve successive audit records by repeatedly calling ARREAD. When reading forward, ARE-END-OF-AUDIT indicates that you have reached the end of the audit file specified by the max-seqno parameter in the AROPEN call. When reading in reverse, ARE-END-OF-AUDIT indicates that you have reached the beginning of the audit file specified by the min-seqno parameter in the AROPEN call.
TMF ARLIB2 Audit-Reading Procedures Reading a Merged Audit Trail Without a MERGE Cursor Reading a Merged Audit Trail Without a MERGE Cursor The procedure for reading the MAT and all configured auxiliary audit trails as a merged audit trail without using a MERGE cursor is as follows: 1. Open cursors for the MAT and all configured auxiliary audit trails by calling AROPEN. Within each call, use a fully qualified file name or the appropriate audit-trail ID (MAT, AUX01, AUX02, ...) as the generic-name.
TMF ARLIB2 Audit-Reading Procedures Reading Audit Records for SQL/MX Objects Reading Audit Records for SQL/MX Objects The general steps for processing SQL/MX audit records are as follows: 1. Read the audit record (ARREAD). 2. Verify that the audit record is for an SQL/MX object (OBJECTTYPE field in ARRECORD). 3. Obtain the before-image and after-image column format (ARGETMXCOLUMNINFO). 4. Obtain the before image (ARFETCHMXBEFOREDATA[2]).
Distributed Transactions TMF ARLIB2 Audit-Reading Procedures Figure 5-1. Basic Parent-Child Relationship Node \A Begin transaction r \B End transaction U U U U c1 C P Messages Audit Records Generated r request c1 commit phase 1 r1 reply to c1 c2 commit phase 2 C P U r1 c2 C commit network prepared update VST005.vsd In Figure 5-1, the transaction begins at node \A. The requestor running in node \A sends a work-request message to a server in node \B.
Distributed Transactions TMF ARLIB2 Audit-Reading Procedures Figure 5-2. Layered Offspring Relationships Node \A Begin transaction r r End transaction c1 U c1 P U \B r \C U c1 U \D C r1 Messages Audit Records Generated r c1 r1 c2 C P U request commit phase 1 reply to c1 commit phase 2 c2 r1 P P c2 C r1 C c2 C commit network prepared update VST006.vsd In Figure 5-2, the transaction again begins at node \A.
TMF ARLIB2 Audit-Reading Procedures Auxiliary Audit Trails Auxiliary Audit Trails Although most applications use only a master audit trail, the TMF audit-reading procedures support both master and auxiliary audit trails.
TMF ARLIB2 Audit-Reading Procedures NonStop SQL/MP Internal Field Formats NonStop SQL/MP Internal Field Formats Certain fields in NonStop SQL/MP records are represented on disk in a way that does not directly correspond to the external view of the data. Because TMF audit-reading procedures return record and field images as they are on disk, you must understand how the fields are represented on disk in order to interpret them.
TMF ARLIB2 Audit-Reading Procedures Variable-Length Character (VARCHAR) Fields However, the data record image on disk and in a before-image or after-image from the audit trail actually is as follows: [A] [B] [C] [0] [5] [0] [1] [Z] [0] [0] [0] [7] The offset of field B is fixed (namely, the length of field A). Although field B is a numeric field, it is not word-aligned relative to the beginning of the image.
DATETIME and INTERVAL Fields TMF ARLIB2 Audit-Reading Procedures DATETIME and INTERVAL Fields DATETIME and INTERVAL fields in NonStop SQL/MP tables store time-related information using varying units. DATETIME fields contain a value that designates a point in time. INTERVAL fields contain a value that represents a time interval or duration. Information is represented on disk depending on how the field is declared.
Audit Records TMF ARLIB2 Audit-Reading Procedures Null VARCHAR fields are stored using a 0-length character part. The field length is 4 bytes, consisting of the 2-byte null indicator (set to -1) and the 2-byte VARCHAR length (set to 0), as follows: [-1] [-1] [0] [0] Audit Records The various types of audit records that are accessible, and the particular fields from which you can retrieve them, are as follows.
Record Formats TMF ARLIB2 Audit-Reading Procedures Record Formats Included in each of the following record descriptions is the DDL representation of those fields that are returned by the ARREAD procedure and a list of any variable-length fields that you can access by using one of the ARFETCHxxx procedures. Each record has the following general form: record ARRECORD.
Record Formats TMF ARLIB2 Audit-Reading Procedures Within some of the record definitions, the EXTERNALNAME entry refers to the following DSMSMFILESPEC definition: definition DSMSMFILESPEC. 02 FILENAME 02 FILENAME-I end type character 36. ! \sys.$vdp.svol.file ! blank-filled on right type binary 16,0 occurs 18 times redefines FILENAME. ! of definition DSMSMFILESPEC. ABORT (1) This record is generated whenever a transaction is aborted. Abort records can occur only in the master audit trail.
Record Formats TMF ARLIB2 Audit-Reading Procedures It is also possible for TMF to be configured as a MAT-only environment and for the first auxiliary audit trail to be added after TMF is started. You must be able to handle and properly process an AUX POINTER record from the master audit trail, and retrieve audit, if deemed necessary, from a new auxiliary audit trail.
Record Formats TMF ARLIB2 Audit-Reading Procedures FILE ALTER (12) This record indicates that an attribute of an audited file (such as the file’s security, the audit attribute, or maxextents) was modified. No indication of which attribute was modified is returned. For Enscribe files, the value of transid is meaningless because attribute modifications are not done within a transaction. Variable-length fields: none 02 FILEALTERREC redefines BODY.
Record Formats TMF ARLIB2 Audit-Reading Procedures FILE PURGE (14) This record indicates that an audited file was purged. For Enscribe files, the value of transid is meaningless because file purging is not done within a transaction. Variable-length fields: none 02 FILEPURGEREC redefines BODY. 04 04 04 04 04 TRANSID DATAFILE EXTERNALNAME OBJECTTYPE UNDOFLAG type type type type type binary 64,0. FILESPEC. DSMSMFILESPEC. binary 16,0. ! to id SQL/MX objects binary 16,0.
Record Formats TMF ARLIB2 Audit-Reading Procedures INSERT (5) This record signifies the insertion of a new record into an audited file. Insert records can occur in either the master audit trail or an auxiliary audit trail. Variable-length fields: after-image 02 INSERTREC redefines BODY. 04 04 04 04 04 04 04 TRANSID DATAFILE EXTERNALNAME OBJECTTYPE UNDOFLAG HOMENODE AFTERLEN type type type type type type type binary 64,0. FILESPEC. DSMSMFILESPEC. binary 16,0. ! to id SQL/MX objects binary 16,0.
Record Formats TMF ARLIB2 Audit-Reading Procedures NETWORK-COMMIT (18) This record is generated whenever a network transaction commits, and it only appears in the master audit trail on the parent node. The record indicates that the parent node has released its locks while simultaneously delivering commit instructions to all child nodes. A subsequent commit record (FORGOTTEN) is then written after replies to the commit instructions have been received from all child nodes.
Record Formats TMF ARLIB2 Audit-Reading Procedures UPDATE (10) This record signifies the modification of an existing record in an audited file. An update record can occur in either the master audit trail or an auxiliary audit trail. When audit compression is enabled, update records are generated only for those records in the audited file, which are not compressed by DP2.
Field Descriptions TMF ARLIB2 Audit-Reading Procedures UPDATE FIELDCOMP (15) This record reflects the form of audit compression used by NonStop SQL/MP. Compression within this type of record is achieved by omitting fields that were not updated and that do not belong to the primary key of the file.
Field Descriptions TMF ARLIB2 Audit-Reading Procedures Aux Pointer This 16-byte structure specifies a range of audit in an auxiliary audit trail that is logically ordered at this point relative to the records in the master audit trail. When all aux pointer records are combined, they show the logical ordering of all audit records in all audit trails on a given system. The NUMAUXTRAILS field returned by the ARREAD procedure specifies the number of auxiliary audit ranges represented in the record.
TMF ARLIB2 Audit-Reading Procedures Field Descriptions DATAFILE This is the 12-word (24-character) local internal form of the name of the audited file upon which the action was performed (“$DATA JOB100 PARTS ”, for example). For files managed by the HP NonStop Storage Management Foundation (SMF) product, DATAFILE contains the logical name of the affected file. For files not managed by the SMF product, DATAFILE contains the physical filename.
TMF ARLIB2 Audit-Reading Procedures Field Descriptions For entry-sequenced, relative, or unstructured files, the record key field represents the two-word internal form of the data record address, which is not particularly useful. You can use the ARGETRECADDR procedure to copy the record address (in external form) from the audit record into your application buffer when you encounter an update auditcomp record for one of these file types. RECTYPE This field specifies the type of audit record that was read.
Procedure Calls TMF ARLIB2 Audit-Reading Procedures UNDOFLAG The UNDOFLAG field, when set to a nonzero value, indicates that the audit record was produced by a TMF recovery process (transaction backout, volume recovery, or file recovery) as it undid the effects of a transaction. You use the UNDOFLAG field to distinguish such records from those produced on behalf of an application program.
Procedure Calls TMF ARLIB2 Audit-Reading Procedures Table 5-2. TMF Audit-Reading Procedures (page 2 of 3) Procedure Name Function ARFETCHMXAFTERDATA Copies the after-image field from an SQL/MX audit record to the application buffer (uses bit maps). ARFETCHMXAFTERDATA2 Copies the after-image field from an SQL/MX audit record to the application buffer (uses byte maps). ARFETCHMXBEFOREDATA Copies the before-image field from an SQL/MX audit record to the application buffer (uses bit maps).
Procedure Calls TMF ARLIB2 Audit-Reading Procedures Table 5-2. TMF Audit-Reading Procedures (page 3 of 3) Procedure Name Function ARSETOPTIONS Sets several different options that control audit-record processing. ARSTART Initiates audit reading. ARSTOP Terminates audit reading. ARSTOPNETWORKRECS Disables the returning of network-related audit records when the ARREAD procedure is called.
TMF ARLIB2 Audit-Reading Procedures ARCLOSE ARCLOSE This procedure closes an open cursor. Closing a cursor ends its association with a particular audit trail and makes that cursor available for reassignment by a subsequent call to the AROPEN procedure. CALL ARCLOSE ( , , , return-code cursor-number [sub-system] [ar-error] ); ! ! ! ! o i o o output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes.
TMF ARLIB2 Audit-Reading Procedures ARCOMPLETEIO ARCOMPLETEIO This procedure is provided for compatibility only. AWAITIO will not complete any ARLIB2 nowait I/O. CALL ARCOMPLETEIO ( return-code , count-transferred , tag ); ! o ! o ! i output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes. Warnings (>0) None.
TMF ARLIB2 Audit-Reading Procedures ARFETCHAFTERIMAGE ARFETCHAFTERIMAGE This procedure copies the after-image field from the most recently read audit record into the application’s buffer. This procedure works with records of type Update (10) and Insert (5). This procedure cannot be used with audit records for SQL/MX objects. The object type can be determined by checking the OBJECTTYPE field in the ARRECORD.
TMF ARLIB2 Audit-Reading Procedures ARFETCHAFTERIMAGE should be substituted for [0].<0:7>. If the DCOMPRESS attribute is not set for the data file, or the warning .<14> is not returned by ARFETCHAFTERIMAGE, then the value returned in this parameter is meaningless.
ARFETCHAUXPOINTER TMF ARLIB2 Audit-Reading Procedures ARFETCHAUXPOINTER This procedure retrieves information about the ranges of audit in auxiliary audit trails that are logically ordered at this point relative to audit records in the master audit trail. Together, these ranges create a logical ordering among all audit records in all audit trails on a given system. CALL ARFETCHAUXPOINTER ( return-code , audit-trail-index , aux-trail-range ); ! o ! i ! o output return-code INT .
TMF ARLIB2 Audit-Reading Procedures ARFETCHBEFOREIMAGE ARFETCHBEFOREIMAGE This procedure copies the before-image field from the most recently read audit record into the application’s buffer. This procedure works with records of type Update (10) and Delete (3). This procedure cannot be used with audit records for SQL/MX objects. The object type can be determined by checking the OBJECTTYPE field in the ARRECORD.
TMF ARLIB2 Audit-Reading Procedures ARFETCHCHILDNODELIST ARFETCHCHILDNODELIST This procedure copies the child node list from the most recently read audit record into the application’s buffer. CALL ARFETCHCHILDNODELIST ( return-code , buffer , max-copy-length ); ! o ! o ! i output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes.
ARFETCHFIELDVALUE TMF ARLIB2 Audit-Reading Procedures ARFETCHFIELDVALUE This procedure retrieves both the before-image and after-image from a fieldcompressed update (UPDATE FIELDCOMP) record. These are SQL-only records. This procedure cannot be used with audit records for SQL/MX objects. The object type can be determined by checking the OBJECTTYPE field in the ARRECORD.
TMF ARLIB2 Audit-Reading Procedures ARFETCHFIELDVALUE is the maximum number of bytes to copy into before-image. This value must be supplied if before-image is present. ARFETCHFIELDVALUE returns an error for values of max-before-copy-len less than 1. actual-before-len output, optional INT .EXT:ref:1 returns the actual length of the retrieved before-image of the field. For a variablelength character (VARCHAR) field, this value includes the 2-byte length word of the field.
TMF ARLIB2 Audit-Reading Procedures ARFETCHFIELDVALUE output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error. Table 5-5 describes the error codes. Considerations The modified data file must be accessible.
TMF ARLIB2 Audit-Reading Procedures ARFETCHFRAGMENT ARFETCHFRAGMENT This procedure returns information about updated data record fragments from auditcompressed update records. Use the ARFETCHFRAGMENT procedure call after reading a record of type UPDATE AUDITCOMP to get the offset, length, before-image, and after-image of each data record fragment. This procedure works with records of type UPDATE AUDITCOMP (11).
TMF ARLIB2 Audit-Reading Procedures ARFETCHFRAGMENT before-image-buf output, optional INT .EXT:ref:* is a buffer in the application process in which the before-image of the updated data record fragment is returned. max-before-copy-len input, optional INT:value is the maximum number of bytes to copy into before-image. This must be supplied if before-image-buf is supplied. ARFETCHFRAGMENT will return an error for values of max-before-copy-len less than 1. actual-before-len output, optional INT .
ARFETCHMXAFTERDATA TMF ARLIB2 Audit-Reading Procedures ARFETCHMXAFTERDATA This procedure retrieves column data from the after image of audit records for SQL/MX objects. ARFETCHMXAFTERDATA can only be used with data-fork audit records for SQL/MX objects. The object type can be determined by checking the OBJECTTYPE field in the ARRECORD. ARFETCHMXAFTERDATA copies the data for all columns from the after image of the current audit record into a buffer specified by the application.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXAFTERDATA input bitmap-length INT(32):value specifies the length of request-bitmap and reply-bitmap in bytes, and must be mod 4. image-buffer output FIXED .EXT:ref points to a caller-allocated buffer where the image data is returned. The information is returned in a fixed format defined by SQL/MX with room for all the columns, regardless of how many are requested. VARCHAR columns have their maximum lengths allocated.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXAFTERDATA sub-system output, optional INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes. output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error.
ARFETCHMXAFTERDATA2 TMF ARLIB2 Audit-Reading Procedures ARFETCHMXAFTERDATA2 This procedure is the same as ARFETCHMXAFTERDATA except that it uses byte maps instead of bit maps. Byte maps are easier to use for languages that have difficulty checking and setting bits. This procedure retrieves column data from the after image of audit records for SQL/MX objects. ARFETCHMXAFTERDATA2 can only be used with data-fork audit records for SQL/MX objects.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXAFTERDATA2 corresponding to the missing bytes is not returned. request-bytemap and reply-bytemap must not overlap one another. input bytemap-length INT(32):value specifies the length of request-bytemap and reply-bytemap in bytes, and can be any length. image-buffer output FIXED .EXT:ref points to a caller-allocated buffer where the image data is returned.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXAFTERDATA2 If the return code is ARE-BUFFER-TOO-SMALL, this parameter contains the minimum length necessary for the image-buffer in bytes (adjusted to mod 8). For all other return-code values this parameter contains zero. sub-system output, optional INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes.
ARFETCHMXBEFOREDATA TMF ARLIB2 Audit-Reading Procedures ARFETCHMXBEFOREDATA This procedure retrieves column data from the before image of audit records for SQL/MX objects. ARFETCHMXBEFOREDATA can only be used with data-fork audit records for SQL/MX objects. The object type can be determined by checking the OBJECTTYPE field in the ARRECORD. ARFETCHMXBEFOREDATA copies the data for all columns from the before image of the current audit record into a buffer specified by the application.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXBEFOREDATA input bitmap-length INT(32):value specifies the length of request-bitmap and reply-bitmap in bytes, and must be mod 4. image-buffer output FIXED .EXT:ref points to a caller-allocated buffer where the image data is returned. The information is returned in a fixed format defined by SQL/MX with room for all the columns, regardless of how many are requested. VARCHAR columns have their maximum lengths allocated.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXBEFOREDATA sub-system output, optional INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes. output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error.
ARFETCHMXBEFOREDATA2 TMF ARLIB2 Audit-Reading Procedures ARFETCHMXBEFOREDATA2 This procedure is the same as ARFETCHMXBEFOREDATA except that it uses byte maps instead of bit maps. Byte maps are easier to use for languages that have difficulty checking and setting bits. This procedure retrieves column data from the before image of audit records for SQL/MX objects. ARFETCHMXBEFOREDATA2 can only be used with data-fork audit records for SQL/MX objects.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXBEFOREDATA2 corresponding to the missing bytes is not returned. request-bytemap and reply-bytemap must not overlap one another. input bytemap-length INT(32):value specifies the length of request-bytemap and reply-bytemap in bytes, and can be any length. image-buffer output FIXED .EXT:ref points to a caller-allocated buffer where the image data is returned.
TMF ARLIB2 Audit-Reading Procedures ARFETCHMXBEFOREDATA2 If the return code is ARE-BUFFER-TOO-SMALL, this parameter contains the minimum length necessary for the image-buffer in bytes (adjusted to mod 8). For all other return-code values this parameter contains zero. sub-system output, optional INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes.
TMF ARLIB2 Audit-Reading Procedures ARFETCHRECORDKEY ARFETCHRECORDKEY This procedure copies the record key field from the most recently read audit record into the application’s buffer. This procedure works with records of type UPDATE AUDITCOMP (11). CALL ARFETCHRECORDKEY ( return-code , buffer , [ max-copy-length ] ); ! o ! o ! i output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the various error codes.
TMF ARLIB2 Audit-Reading Procedures ARFETCHRECORDKEY Considerations The record key field only occurs in UPDATE AUDITCOMP audit records. The value of a record key is only meaningful if the audit (data) file is keysequenced. For other types of files (entry-sequenced, relative, or unstructured), the field contains the two-word internal form of the data record address.
ARGETANSINAME TMF ARLIB2 Audit-Reading Procedures ARGETANSINAME This procedure returns the ANSI name of an SQL/MX object. It also returns the ANSI partition name of the object (where pertinent) and the name space of the returned ANSI name. Using the ANSI name, the calling program can perform SQL/MX SELECT statements against the SQL/MX metadata to obtain additional information about that object not available from the ARGETMXCOLUMNINFO procedure.
TMF ARLIB2 Audit-Reading Procedures ARGETANSINAME If the ANSI name being returned is too long to fit in the caller-allocated ANSI-name buffer, or the partition name being returned is too long to fit in the caller-allocated partition-name buffer, or both, an ARE-BUFFER-TOO-SMALL error is returned. No name information is returned in either name buffer in such cases, but the minimum buffer lengths needed are returned in both the ansi-name-length and partition-name-length parameters.
TMF ARLIB2 Audit-Reading Procedures ARGETANSINAME The defined ANSI name spaces are as follows: TA = Base Table or View IX = Index IL = Log Table for Materialized Views (not returned in this interface) RL = Range Log Table for Materialized Views (not returned in this interface) TT = Trigger Temporary Table = Unknown Namespace partition-name output STRING .EXT:ref:1 is the corresponding partition name (in external format).
TMF ARLIB2 Audit-Reading Procedures ARGETANSINAME Considerations The optional parameters sub-system and ar-error must be passed in pairs. You must pass either both the parameters or none.
TMF ARLIB2 Audit-Reading Procedures ARGETAUDRECHEADERINFO ARGETAUDRECHEADERINFO This procedure returns certain information from the audit-record header. CALL ARGETAUDRECHEADERINFO , [ , [ , [ , [ ( return-code file-format ] blocksize ] rsn-rbn ] recnum-offset ] ) EXTENSIBLE; return-code ! ! ! ! ! o o o o o output INT .EXT:ref:1 indicates the outcome of the call. file-format output INT .EXT:ref indicates the file format (0 = format-1 files, 1 = format-2 files). output blocksize INT .
ARGETFIELDINFO TMF ARLIB2 Audit-Reading Procedures ARGETFIELDINFO This procedure returns information about the fields contained in a field-compressed update audit record. This procedure works only with SQL records of type UPDATE FIELDCOMP (15). This procedure cannot be used with audit records for SQL/MX objects (see the ARGETMXCOLUMNINFO procedure). The object type can be determined by checking the OBJECTTYPE field in the ARRECORD.
ARGETFIELDINFO TMF ARLIB2 Audit-Reading Procedures Value Field Type Literal Name 130 Signed 16-bit integer ARVALUE-SMALLINT-S 131 Unsigned 16-bit integer ARVALUE-SMALLINT-U 132 Signed 32-bit integer ARVALUE-INT-S 133 Unsigned 32-bit integer ARVALUE-INT-U 134 Signed 64-bit integer ARVALUE-LARGEINT-S 140 32-bit floating point number ARVALUE-FLOAT32 141 64-bit floating point number ARVALUE-FLOAT64 150 Unsigned decimal ARVALUE-DECIMAL-U 152 Decimal, leading sign embedded ARVALUE-D
TMF ARLIB2 Audit-Reading Procedures is-key-field ARGETFIELDINFO output, optional INT .EXT:ref:1 is a Boolean value indicating whether or not the field is an element of the primary key (either user-defined or system-defined) of the data file. The value returned is nonzero for a key field and 0 for all other types of fields. next-field output, optional INT .EXT:ref:1 is the ordinal field number of the next field (in ascending field number order) that is present in the audit record.
TMF ARLIB2 Audit-Reading Procedures ARGETFIELDINFO Considerations The file that was modified must be accessible. If a file that has the same name as the modified file, but different characteristics, exists on disk and is accessible, the results of ARGETFIELDINFO will probably be incorrect. The TMF audit-reading procedures cannot always detect this situation. If the specified field does not exist in the audit record, return-code is -17 (field not present).
ARGETMESSAGELINE TMF ARLIB2 Audit-Reading Procedures ARGETMESSAGELINE This procedure retrieves a line of text from the most recent error message for a particular cursor. The call indicates which line of the message to retrieve (the first line of text in each message is line number 1). If the indicated line does not exist, then line-length is set to 0.
TMF ARLIB2 Audit-Reading Procedures ARGETMESSAGELINE line-length output INT .EXT:ref:1 is a returned value indicating the byte length of the text line. The range is 0 through 72.
ARGETMXCOLUMNINFO TMF ARLIB2 Audit-Reading Procedures ARGETMXCOLUMNINFO This procedure returns column information for the SQL/MX object indicated by the current data-fork audit record (as long as the object exists on disk and has the same name). The information provided by this procedure is necessary to understand the format of the before-image and after-image data returned by the ARFETCHMXBEFOREDATA[2] and ARFETCHMXAFTERDATA[2] procedures.
TMF ARLIB2 Audit-Reading Procedures ARGETMXCOLUMNINFO The format of the information returned in this buffer is described by the IMAGEINFO and COLUMNINFO structures defined below. All offsets are zero-relative from the start of the image buffer. input info-buffer-length INT(32):value is the length in bytes of the caller-allocated info buffer. The performance of this procedure will be improved if this length is mod 4.
TMF ARLIB2 Audit-Reading Procedures ARGETMXCOLUMNINFO Considerations The optional parameters sub-system and ar-error must be passed in pairs. You must pass either both the parameters or none.
TMF ARLIB2 Audit-Reading Procedures ARGETMXCOLUMNINFO The definitions of IMAGEINFO and COLUMNINFO are shown in Example 5-1. They are declared in the ARDDL2 file (and the related AR* files). The values returned in all the length and offset fields in these structures are in bytes. The order of the columns reflects the order they were declared in, not their order in the on-disk record, which can differ from the declared order for SQL/MX objects. Example 5-1.
TMF ARLIB2 Audit-Reading Procedures ARGETMXCOLUMNINFO Example 5-1. IMAGEINFO and COLUMNINFO Definitions 02 PRECISION type binary 32,0 The precision (number of significant decimal digits) for numeric values. 02 SCALE type binary 32,0 The scale (decimal digits after the decimal point) for numeric values. For interval, time and timestamp columns, this is the "fraction precision", the precision of fractional seconds (a value between 0 for whole seconds and 6 for microsecond resolution).
ARGETNETWORKRECS TMF ARLIB2 Audit-Reading Procedures ARGETNETWORKRECS This procedure enables the returning of network-related audit records (NETWORKCOMMIT and NETWORK-ABORT) when the ARREAD procedure is called. CALL ARGETNETWORKRECS ( return-code ) ! o output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes. Warnings (>0) None.
ARGETNONDATACHNGRECS TMF ARLIB2 Audit-Reading Procedures ARGETNONDATACHNGRECS This procedure reverses the effect of the ARSTOPNONDATACHNGRECS procedure (it causes certain audit records that do not reflect changes to customer data to be returned instead of being discarded by the ARREAD procedure). Audit reading must be started before you call this procedure. CALL ARGETNONDATACHNGRECS ( return-code ); ! o output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure.
ARGETRECADDR TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR For format 1 and non-oversized format 2 entry-sequenced, relative, or unstructured files, this procedure computes and returns the 32-bit external (user-understood) record address of the data record whose modification is reflected in the current audit record. Format 1 is the default file format and supports file sizes up to 2 GB - 1MB. Format 2 is a disk format that supports large format files (big files).
TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error. Table 5-5 describes the error codes.
TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR Considerations You can use ARGETRECADDR after reading any type of data change audit record (insert, delete, or any form of update). The file that was modified must be accessible. If the file is a secondary partition of an Enscribe partitioned file, root-part must be present and the root partition of the file must also be accessible.
ARGETRECADDR64 TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR64 For format 1, format 2, and oversized format 2 entry-sequenced, relative, or unstructured files, this procedure computes and returns the 64-bit external (userunderstood) record address of the data record whose modification is reflected in the current audit record. Format 1 is the default file format and supports file sizes up to 2 GB - 1MB. Format 2 is a disk format that supports large format files (big files).
TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR64 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes. output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error. Table 5-5 describes the error codes.
TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR64 Considerations You can use ARGETRECADDR64 after reading any type of data change audit record (insert, delete, or any form of update). The file that was modified must be accessible. If the file is a secondary partition of an Enscribe partitioned file, root-part must be present and the root partition of the file must also be accessible.
TMF ARLIB2 Audit-Reading Procedures AROPEN AROPEN This procedure opens a cursor. You can specify bounds on the sequence number of the audit files to which the cursor refers. The number of the cursor assigned to the audit trail is returned for use in subsequent calls to other audit-reading procedures.
TMF ARLIB2 Audit-Reading Procedures AROPEN output cursor-number INT .EXT:ref:1 returns a number used to identify the cursor in subsequent calls. input, optional min-seqno INT(32):value is a double-word value, within the range 1 through 999999, specifying the minimum audit file sequence number that this cursor will accept. By including this value, you can prevent the cursor from reading or being positioned into any audit file whose sequence number is less than this value. The default value is one.
TMF ARLIB2 Audit-Reading Procedures trail-index-list AROPEN input, optional INT .EXT ref:trail-index-count is an integer array of trail-index-count size. Valid only if trail-indexcount is not zero. Each entry is the audit-trail index of an auxiliary audit trail to be read by this MERGE cursor. Each value must be 1 through 15, and may not be repeated. Each value must be that of a configured auxiliary audit trail. sub-system output, optional INT .
TMF ARLIB2 Audit-Reading Procedures ARPOSITION ARPOSITION This procedure positions a cursor within the audit trail to which it refers and specifies the direction in which subsequent calls to ARREAD traverse the audit. Cursors are positioned by the sequence number of the desired audit-trail file and a relative byte address (offset) within the file.
TMF ARLIB2 Audit-Reading Procedures ARPOSITION input audit-file-rba FIXED:value specifies the relative byte address (offset) within the audit file to which the cursor is being positioned. If the value specified is zero, the cursor is positioned at the beginning of the audit file. If the value specified is -1, the cursor is positioned at the end of the audit file. If this is a MERGE cursor, then this is the MAT rba. input aux-index INT:value This input parameter is used only for MERGE cursors.
TMF ARLIB2 Audit-Reading Procedures ARPOSITION ARPOSITION to 200, Read Forward returns Rec 2; Read Reverse returns Rec 1 ARPOSITION to 201, Read Forward returns Rec 3; Read Reverse returns Rec 2 ARPOSITION to 199, Read Forward returns Rec 2; Read Reverse return Rec 1 sub-system output, optional INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes.
ARPOSITION2 TMF ARLIB2 Audit-Reading Procedures ARPOSITION2 This procedure uses the aux-trail-range returned by an ARFETCHAUXPOINTER call to position the cursor for the specified auxiliary audit trail. An AUXPOINTERINFO Def structure may also be specified for the MAT. When reading forward, ARREAD returns audit records starting with the LOWPOS and returns ARE-END-OF-AUDIT when the HIGHPOS is reached.
TMF ARLIB2 Audit-Reading Procedures sub-system ARPOSITION2 output, optional INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes. output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error. Table 5-5 describes the error codes.
TMF ARLIB2 Audit-Reading Procedures ARPRINTMESSAGE ARPRINTMESSAGE This procedure writes, to a specified file, the message text associated with the most recent error condition for a particular cursor. CALL ARPRINTMESSAGE ( return-code , cursor-number , file-number ,[ max-line-length ] ); ! ! ! ! o i i i output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes.
ARREAD TMF ARLIB2 Audit-Reading Procedures ARREAD This procedure advances the cursor to the next audit record and copies the fixedlength fields and certain other attributes into the application’s buffer. The next audit record is the subsequent record (in the set of audit records externalized by this interface) in the cursor direction specified by the most recent call to ARPOSITION for the specified cursor.
TMF ARLIB2 Audit-Reading Procedures ARREAD is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case this value reports the subsystem that returned the error. Table 5-4 describes the subsystem codes. output, optional ar-error INT .EXT:ref:1 is a returned value valid only when return-code equals ARE-INTERNAL-ERROR (-1000), in which case the value indicates the specific error. Table 5-5 describes the error codes.
ARSETOPTIONS TMF ARLIB2 Audit-Reading Procedures ARSETOPTIONS This procedure sets several options that control audit-record processing. Rather than having multiple procedures to turn on and off the various options, this single procedure controls all of them. If a parameter is not specified, that option is not changed from its current setting.
TMF ARLIB2 Audit-Reading Procedures set-undoauditflag ARSETOPTIONS input INT:value controls the setting of UndoFlag in undo audit records. If this parameter is TRUE then the UndoFlag will differentiate between transaction-level and file-level undo audit. If it is transaction-level undo, the value of UndoFlag will be 1 and if it is filelevel undo then the value will be 2. If the parameter is FALSE then UndoFlag will indicate that it's a transaction-level undo audit.
TMF ARLIB2 Audit-Reading Procedures ARSTART ARSTART This procedure initializes the audit-reading programmatic interface. You must call ARSTART before you begin issuing calls to any other audit-reading procedure. CALL ARSTART ( , , , , , return-code [ number-of-cursors ] [ operator-term ] [ extended-seg-size ] [ sqlmx-cache-size ] ar-version ); ! ! ! ! ! ! o i i i i i output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure.
TMF ARLIB2 Audit-Reading Procedures sqlmx-cache-size ARSTART input, optional INT:value specifies the maximum size (in megabytes) of the cache used by SQL/MX for caching labels of objects. The minimum is 2, the maximum is 128, and the default is 5. The cache is maintained in a SQL/MX specific extended segment that is different from the main extended segment. Note that this value does not represent the limit on the total memory used by SQL/MX.
TMF ARLIB2 Audit-Reading Procedures ARSTOP ARSTOP This procedure does the appropriate cleanup and closes the programmatic interface. CALL ARSTOP ( return-code , [sub-system ] , [ar-error ] ); ! o ! o ! o output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes. Warnings (>0) None. sub-system output, optional INT .
ARSTOPNETWORKRECS TMF ARLIB2 Audit-Reading Procedures ARSTOPNETWORKRECS This procedure disables the returning of network-related audit records (NETWORKCOMMIT and NETWORK-ABORT) when the ARREAD procedure is called. CALL ARSTOPNETWORKRECS ( return-code ) ! o output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 describes the error codes. Warnings (>0) None.
TMF ARLIB2 Audit-Reading Procedures ARSTOPNONDATACHNGRECS ARSTOPNONDATACHNGRECS This procedure causes certain audit records that do not reflect changes to customer data to be discarded instead of being returned by the ARREAD procedure. Audit records filtered out after this procedure is called include the following: Audit records generated during SQL online DDL modification operations (SQL NonStop Availability operations).
Error Codes TMF ARLIB2 Audit-Reading Procedures Error Codes Table 5-3 lists all of the error codes returned by the TMF audit-reading procedures. Additional error codes will be defined in the future. You should design your error handling code so that it can be easily expanded to recognize and respond to error code values not documented in this table. Table 5-3. Error Codes by Class (page 1 of 4) Code DDL Name Meaning Successful 0 AR-OK Successful completion.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 2 of 4) Code DDL Name Meaning Successful -13 ARE-NOT-STARTED You tried to do something before starting the audit-reading interface (you must call ARSTART before calling any of the other audit-reading procedures). -14 ARE-DATA-FILE-NOT-FOUND The required data file is not available on disk. -15 ARE-DATA-FILE-TYPE The procedure you called cannot operate on the current type of data file.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 3 of 4) Code DDL Name Meaning Successful -103 ARE-BUFFER-TOO-SMALL The size of the output buffer is too small. The reply-hint variable contains the required size. -104 ARE-MUST-USE-SEPARATEBUFFERS The request and reply maps must not overlap. -105 ARE-ONLY-USEABLE-WITHDATAFORK The called procedure requires an SQL/MX data-fork record but the current record is not an SQL/MX data-fork record.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 4 of 4) Code DDL Name Meaning Successful -901 ARE-END-OF-AUDIT The cursor has reached the end of the audit file range specified when the cursor was opened. No further reads will be allowed for that cursor until it has been repositioned. A more detailed error message is printed on the operator terminal and is available programmatically by calling the ARGETMESSAGELINE audit-reading procedure.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-4. Subsystem Codes Code DDL Name Meaning -3000 ARE-TMF The subsystem is TMF. Table 5-5 describes the ar-error codes. -3001 ARE-SQLMX The subsystem is SQL/MX. For further information, see the HP NonStop SQL/MX Messages Manual. -3002 ARE-FILESYSTEM The subsystem is File Systems. For further information, see the Guardian Procedure Errors and Messages Manual. -3003 ARE-DP2 The subsystem is DP2.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-5. Errors returned in case return-code is -1000 Code DDL Name Meaning -27 ARE-PAGE-LIMITEXCEEDED The ARGetRecAddr procedure is called. The total number of pages or blocks for all the partitions in the FORMAT1 file exceeds or equals 2^33. Use a Format 1 file which does not exceed the page/block limit or use a Format2 file. -28 ARE-INVALIDFILETYPE The ARGetRecAddr procedure is called.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-5. Errors returned in case return-code is -1000 Code DDL Name Meaning -35 ARE-FIELD-NOTFOUND The requested field is not found in the audit record. -36 ARE-INVALIDCOLLATION-BASE The information of the character field you requested from the fieldcompressed audit record has a non-standard collation. -37 ARE-AUDITREADEXCEPTION A non-standard TMF audit reading exception has occurred.
TMF ARLIB2 Audit-Reading Procedures How to Include Audit Reading in an Application How to Include Audit Reading in an Application The TMF audit-reading procedures are contained in a set of files that are delivered with the TMF product. Table 5-6 summarizes the audit-reading procedure files. Using FUP LICENSE and FUP PROGID to a Super group user will allow users other than SUPER.SUPER users to run the program based on Guardian file security.
TMF ARLIB2 Audit-Reading Procedures Use of AWAITIOX Example of linking with TMFARLB2 and ZCLIDLL: ELD linkfile .. TMFARLB2 .. -o runfile -l ZCLIDLL .. other required DLL’s.. -libname $vol.subvol.TMFARUL2” ZCLIPDLL released in the H06.10 RVU and in subsequent releases, includes the required exported procedures, and can be used instead of ZCLIDLL. This avoids the use of C main. Example of linking with TMFARLB2 and ZCLIPDLL: ELD linkfile .. TMFARLB2 .. -o runfile -l ZCLIPDLL .. other required DLL’s..
TMF ARLIB2 Audit-Reading Procedures HP NonStop TMF Application Programmer’s Guide—540139-009 5-112 Use of AWAITIOX
Index A ABORT audit record 5-21 Aborting transactions 1-4, 2-13/2-14 ABORTTRANSACTION code 3-11 ABORTTRANSACTION TMF procedure description of 2-3 errors 2-4 statements used for invoking 1-4 syntax description 4-3 unlocking records 1-15 use and implications of 2-13 Access control block (ACB) 2-6 ACTIVATERECEIVETRANSID TMF procedure multithreaded heterogeneous processes 3-14 restoring current transaction 2-13 syntax description 4-5 After-image audit compression 5-7 field description 5-28 Applications, includi
B Index ARSETOPTIONS audit-reading procedure 5-96 ARSTART audit-reading procedure 5-98 ARSTOP audit-reading procedure 5-100 ARSTOPNETWORKRECS audit-reading procedure 5-101 ARSTOPNONDATACHNGRECS auditreading procedure 5-102 Audit compression 5-7 Audit dumps, restoring audit trail files from 5-4 Audit records description of fields 5-28/5-32 formats 5-20 retrieving information from 5-5 types 5-19 See also individual audit record names 5-21 See also Subset audit record 5-15 Audit trail files See also Auxiliar
D Index Committing transactions 1-4 COMPUTETRANSID TMF procedure 4-12 Concurrency See Database concurrency 1-11 Condition codes (CCL, CCE, CCG) 4-5 Consistency See Database consistency 1-11 Context-sensitive servers 2-15 Current transaction description of 1-7 manipulating 3-2 obtaining the transid 3-13 setting to nil 2-13 setting to nil state 1-10, 3-13 Cursor closing 5-35 declaration 5-3 positioning 5-4 Cursor, closing 5-65 D Database concurrency 1-11/1-19 Database consistency achieving maximum 1-11 des
F Index F M Field alignment, SQL/MP 5-16 Field descriptions in audit records 5-28/5-32 Field formats, internal 5-16 FILE ALTER audit record 5-23 FILE CREATE audit record 5-23 FILE PURGE audit record 5-24 FILE RENAME audit record 5-24 FILESPEC definition 5-20 FILE_OPEN_ system procedure opening the TFILE 2-7, 3-1 opening $RECEIVE 2-12, 3-12 Fragments field description 5-30 MAINLOOP code 3-9 Message system 1-6 Multithreaded heterogeneous processes 3-14 Multithreaded operation 1-6 Multithreaded requesters
O Index O OPEN system procedure, opening the server process 1-6 Operations, nowait 4-15 Operations, waited 4-15 P Parent nodes description of 5-12 relationship to child nodes 5-13/5-14 Parentnode field description 5-30 Performance decreasing by using Enscribe file locks 1-12 enhancing within a network environment 1-9 Procedure-call syntax See individual procedure names Processes, heterogeneous multithreaded 3-14 Programming languages for coding requesters 1-6 for coding servers 1-6 R RBA field descripti
T Index See also Single-threaded servers 2-11 SETMODE = 117 1-10 SETMODE = 4 description of 1-15 normal mode and reject mode options 1-17 Single-threaded requesters checkpointing strategy 2-6 delegating work to servers 2-2 description of 2-1 system and TMF procedures for 2-1 Single-threaded servers description of 2-11 file system procedures 2-11 SNOOP Dump/Restore (SNOOPDR) 5-4 SQL/MP See NonStop SQL/MP STABLE ACCESS, SQL/MP access options 1-13 Status descriptor 2-6 STATUSTRANSACTION TMF procedure 4-34 Su
U Index Transactions, distributed 5-12 Transactions, heterogeneous 1-5 Transactions, TMF 1-2 Transaction, current 1-7, 3-2 Transid field description 5-31 TRANSIDTOTEXT TMF procedure 4-68 multithreaded heterogeneous processes 3-14 opening 3-12 opening and closing 2-12 requester/server model 1-6 U Undoflag field description 5-32 Unilateral transaction aborts clearing TFILE entry 2-5 description of 2-4 UNLOCKFILE system procedure 1-15 UNLOCKREC system procedure 1-15 UPDATE audit record 5-27 UPDATE AUDITCOM
Special Characters Index HP NonStop TMF Application Programmer’s Guide—540139-009 Index-8
