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.3 product. Product Version TMF H01 Supported Releases This manual supports H06.
Document History Part Number Product Version Published 540139-001 TMF H01 July 2005 540139-002 TMF H01 February 2006
HP NonStop TMF Application Programmer’s Guide Index Figures What’s New in This Manual vii Manual Information vii New and Changed Information Tables viii About This Manual ix Who Should Read This Manual ix How this Manual is Organized ix About the TMF Library ix Related Manuals x Notation Conventions x 1.
2. Designing Single-Threaded Processes Contents 2.
. TMF ARLIB2 Audit-Reading Procedures Contents RESUMETRANSACTION 4-18 STATUSTRANSACTION 4-20 TEXTTOTRANSID 4-22 TMF_BEGINTAG_FROM_TXHANDLE_ TMF_GETTXHANDLE_ 4-26 TMF_GET_TX_ID_ 4-27 TMF_JOIN_ 4-29 TMF_RESUME_ 4-31 TMF_SETTXHANDLE_ 4-33 TMF_SUSPEND_ 4-34 TMF_TXBEGIN_ 4-36 TMF_TXHANDLE_FROM_BEGINTAG_ TRANSIDTOTEXT 4-40 4-24 4-38 5.
5.
Index Contents ARSTART 5-86 ARSTOP 5-88 ARSTOPNETWORKRECS 5-89 ARSTOPNONDATACHNGRECS 5-90 Error Codes 5-91 How to Include Audit Reading in an Application Use of AWAITIOX 5-96 5-95 Index 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-002 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.3 product. Product Version TMF H01 Supported Releases This manual supports H06.
What’s New in This Manual New and Changed Information New and Changed Information This is the second edition of the HP NonStop TMF Application Programmer’s Guide. It has been updated to support the H06.05 release version update (RVU) of the TMF product, and to correct and clarify elements in the previous edition. The changes are as follows: • Section 4, “File System Procedures” Added the RESIDENT parameter to the TMF_TXBEGIN_ procedure.
About This Manual This manual describes the programming environment for the HP NonStop Transaction Management Facility (TMF) on HP NonStop servers. 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.3 programming environment.
Related Manuals About This Manual Related Manuals Other manuals that provide information about how TMF interfaces to HP software products are: • • • • • 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.
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).
Change Bar Notation About This Manual HP NonStop TMF Application Programmer’s Guide—540139-002 xiv
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 an error 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 therefore, 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-002 1- 20 Enscribe Capabilities
2 Designing Single-Threaded Processes Application program modules are often designed as single-threaded processes. Single-threaded 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.
Designing Single-Threaded Processes Checkpointing Strategy Table 2-2.
Designing Single-Threaded Processes Checkpointing Strategy To open the TFILE, a single-threaded requester uses an FILE_OPEN_ call of the following form (illustrated in TAL). CALL FILE_OPEN_ ( filename:4 , filenumber , , , nowait-depth ); filename is the name of a variable containing the logical device name of the TMF Management Process (TMP). The name is always $TMP. You can obtain the name programmatically by calling the GETTMPNAME procedure.
Designing Single-Threaded Processes Checkpointing Strategy backup requester. Data blocks are usually file buffers that are not checkpointed as part of the stack and they can be from any location within the user data area (but not an extended data area). Instead of CHECKPOINT, there are three other checkpointing procedures that you will sometimes need to use: • • • You use the CHECKPOINTMANY procedure when you need to checkpoint more than 13 items from the user data area.
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-002 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 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. When the requester issues a nowait ENDTRANSACTION call, TMF does not suspend the requester but rather allows it to continue working on other transactions as the ENDTRANSACTION processing proceeds.
Designing Multithreaded Processes Checkpointing Strategy 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. The major difference is that each thread in a multithreaded environment uses nowait procedure calls and, as a result, spends more time in a suspended state as the requester works on other concurrent transactions (threads).
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 When a primary-to-backup switch occurs, the backup process must determine which transactions were committed and which were aborted. The backup requester does this 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.
Designing Multithreaded Processes Checkpointing Strategy If the transaction requires another WRITEREAD call, control passes to the ISSUEWRITEREADTOSERVER code. 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.
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.
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 82 TMF not running. 84 TMF not configured. 97 Transaction already aborted. For a list of all possible 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].
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.
COMPUTETRANSID File System Procedures COMPUTETRANSID This procedure converts the individual numeric parts of an externally formatted transaction identifier to internal form. All output parameters are undefined unless a status of 0 (successful) is returned. If omitted, the tm-flags parameter defaults to 0.
File System Procedures COMPUTETRANSID output transid FIXED .EXT:ref:1 or INT .EXT: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. input tm-flags INT:value is a number representing flags used internally by TMF.
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 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. 92 Path to a participating network node failed. 93 TMF aborted the transaction because the transaction remained on the system long enough to span too many audit-trail files. 94 Transaction aborted by operator command.
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 #include short GETTMPNAME ( short _near *devname ); Syntax for TAL Programmers status := GETTMPNAME ( devname ); ! o Parameters returned value status INT is a file system error number: 0 Successful completion.
File System Procedures GETTMPNAME For single-threaded requesters, the first call to BEGINTRANSACTION implicitly opens the TFILE for you.
GETTRANSID File System Procedures GETTRANSID This procedure returns the transaction identifier of the calling process’ current transaction. Syntax for C Programmers #include short GETTRANSID ( short _near *transid ); Syntax for TAL Programmers status := GETTRANSID ( transid ); ! o Parameters returned value status INT is a file system error number: 0 Successful completion. 29 Missing parameter(s). 75 Current transaction in nil state.
GETTRANSID File System Procedures output transid INT: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].
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.
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 is the system number. output cpu INT .EXT:ref:1 is the CPU number. output sequence INT(32) .EXT:ref:1 is a sequence number greater than 0. output tm-flags INT .EXT:ref:1 is a number representing flags used internally by TMF.
RESUMETRANSACTION File System Procedures 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 90 Transaction’s parent process failed. 92 Path to a participating network node failed. 93 Transaction aborted because it was pinning a file on the MAT, and more than 45% of the MAT filled during the transaction’s lifetime. 94 Transaction aborted by operator command. 96 Transaction aborted by Autoabort threshold. 97 Transaction aborted by ABORTTRANSACTION call. For a list of all possible file system error numbers, refer to the Operator Messages Manual.
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.
File System Procedures STATUSTRANSACTION trans-status output INT .EXT:* 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.
TEXTTOTRANSID File System Procedures 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 29 Missing parameter(s). 82 TMF not running. 84 TMF not configured. For a list of all possible file system error numbers, refer to the Operator Messages Manual. input text STRING .EXT:ref:* is the name of a string variable containing the external ASCII transaction identifier in one of the following formats: \system-name(tm-flags).cpu.sequence \system-number(tm-flags).cpu.sequence \system-name.cpu.sequence \system-number.cpu.sequence cpu.
TMF_BEGINTAG_FROM_TXHANDLE_ File System Procedures 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.
File System Procedures TMF_BEGINTAG_FROM_TXHANDLE_ input tx-handle INT .EXT:ref:10 specifies the transaction handle associated with the transaction whose begintransaction-tag is to be returned. trans-begin-tag INT(32) output .EXT:ref:1 returns the begin-transaction-tag associated with the supplied transaction handle.
TMF_GETTXHANDLE_ File System Procedures TMF_GETTXHANDLE_ This procedure returns the transaction handle of the current transaction. Syntax for C Programmers #include short TMF_GETTXHANDLE_ ( short _far *tx-handle ); Syntax for TAL Programmers status := TMF_GETTXHANDLE_ ( tx-handle ) CALLABLE; ! 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.
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_.
File System Procedures TMF_GET_TX_ID_ output txid FIXED .EXT: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 C Programmers #include short TMF_JOIN_ ( long long txid ); 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.
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 #include short TMF_SETTXHANDLE_ ( short _far *tx-handle ); Syntax for TAL Programmers status := TMF_SETTXHANDLE_ ( tx-handle ) CALLABLE; !i Parameters returned value status INT is a file system error number: 0 Successful completion. 22 Bounds error. 29 Missing parameter(s).
TMF_SUSPEND_ File System Procedures 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 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.
File System Procedures TMF_TXBEGIN_ input timeout INT(32) the number of seconds that the transaction should be allowed to exist before it is aborted due to a timeout. If the specified value is greater than the configured AutoAbort attribute, the AutoAbort value takes precedence. This parameter is optional. If omitted, the configured AutoAbort value is used. trans-begin-tag output INT(32) .
TMF_TXHANDLE_FROM_BEGINTAG_ File System Procedures TMF_TXHANDLE_FROM_BEGINTAG_ This procedure returns the transaction handle associated with the specified begintransaction-tag.
File System Procedures TMF_TXHANDLE_FROM_BEGINTAG_ output tx-handle INT .EXT:ref:1 returns the transaction handle associated with the supplied begin-transaction-tag. The size of the returned handle is 20 bytes.
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 Parameters returned value status INT is a TMF or file system error number: -2 String too short (TMF). -1 Invalid internal transaction identifier (TMF). 0 Successful completion. 22 Bounds error. 29 Missing parameter(s). 82 TMF not running. 84 TMF not configured. For a list of all possible file system error numbers, refer to the Operator Messages Manual.
File System Procedures HP NonStop TMF Application Programmer’s Guide—540139-002 4- 42 TRANSIDTOTEXT
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 parameter to 999999, the audit-file-rba parameter to -1, and the cursor-direction parameter to any value greater than zero. 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.
TMF ARLIB2 Audit-Reading Procedures Reading a Merged Audit Trail With a MERGE Cursor value as the max-seqno parameter, the ARPOSITION rel-byte-addr parameter to -1D, and the ARPOSITION cursor-direction parameter to any value greater than zero. 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.
TMF ARLIB2 Audit-Reading Procedures Reading a Merged Audit Trail Without a MERGE Cursor another ARREAD. If the call returns an ARE-END-OF-AUDIT, then pause once again and issue another ARREAD, and so forth. Note that a MERGE cursor cannot determine that additional data is written to an auxiliary audit trail until the TMP writes an Aux Pointer record to the MAT.
TMF ARLIB2 Audit-Reading Procedures Reading Audit Records for SQL/MX Objects c. Call ARREAD until ARE-END-OF-AUDIT is returned. At that point call ARREAD for the MAT again. If max-seqno in the AROPEN call was 999999 and ARE-END-OF-AUDIT is returned for the MAT, you have read to the end of the merged audit trail. 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.
Distributed Transactions TMF ARLIB2 Audit-Reading Procedures Figure 5-1 and Figure 5-2 show relative time lines for two distributed transactions. Figure 5-1 shows the basic relationship between a parent node and a child node. 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.
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. Note that when audit compression is enabled, update records are not generated; instead, the disk process generates update autocomp records for Enscribe data files and update fieldcomp records for NonStop SQL/MP files.
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 ); ! o ! i output return-code INT .EXT:ref:1 is a returned value indicating the outcome of this procedure. Errors (<0) Table 5-3 (later in this section) describes the error codes. Warnings (>0) None.
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 (later in this section) 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 (later in this section) 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 ARFETCHFIELDVALUE returns an error for values of max-before-copy-len less than 1. actual-before-len output, optional INT:ref 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. For null fields, this count includes the two bytes occupied by the null indicator. after-image output, optional INT .
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 ARFETCHMXAFTERDATA2 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 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. 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 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 ARFETCHMXBEFOREDATA2 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 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. 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 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.
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 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. guardian-name input STRING .EXT specifies the Guardian name. This is a pointer to a buffer of type DSMSMFILESPEC that is allocated by the calling process. output ansi-name STRING .EXT is the corresponding ANSI name (in external format).
TMF ARLIB2 Audit-Reading Procedures partition-name ARGETANSINAME output STRING .EXT is the corresponding partition name (in external format). This is a pointer to a buffer of length partition-name-buffer-length bytes that is allocated by the calling process. A partition name is returned only when the specified Guardian name is for an SQL/MX base-table partition or index partition. Otherwise, when there is no associated partition name, zero is returned in partition-namelength.
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 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-DECIMAL-LSE 192 Datetime, date, time, timestamp ARVALUE-DATETIME 195 Interval years ARVALUE-I
TMF ARLIB2 Audit-Reading Procedures is-key-field ARGETFIELDINFO output, optional INT:ref 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:ref is the ordinal field number of the next field (in ascending field number order) that is present in the audit record.
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 INT:ref 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.
ARGETMXCOLUMNINFO TMF ARLIB2 Audit-Reading Procedures The definitions of IMAGEINFO and COLUMNINFO are shown below. 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. definition IMAGEINFO.
ARGETMXCOLUMNINFO TMF ARLIB2 Audit-Reading Procedures 02 NULLINDLENGTH type binary 32,0 Length in bytes of this column's NULL indicator. Value is 0 if the column is not nullable. Otherwise, the NULL indicator will occupy NULLINDLENGTH bytes, starting at offset NULLINDOFFSET. Note that the NULL indicator may or may not be adjacent to the data portion of the column. This value could be 0, 2, 4, or 8.
ARGETMXCOLUMNINFO TMF ARLIB2 Audit-Reading Procedures 02 CHARACTERSET type binary 32,0 Character set for a character column. See SQLCHARSETCODE_ literals in file sqlcli.h. 02 FUTURECOLLATION type binary 32,0 A literal identifying the collation of a character column, should collations be supported in Release 2. 02 end filler type pic x (20) ! of definition COLUMNINFO To ensure upward-compatibility, do not make assumptions about how information gets returned.
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.
TMF ARLIB2 Audit-Reading Procedures ARGETNONDATACHANGERECS ARGETNONDATACHANGERECS 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 ARGETNONDATACHANGERECS ( return-code ); ! o output return-code INT .
TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR 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 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.
TMF ARLIB2 Audit-Reading Procedures ARGETRECADDR64 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 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 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.
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 HP NonStop TMF Application Programmer’s Guide—540139-002 5- 81
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 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 (later in this section) describes the error codes.
TMF ARLIB2 Audit-Reading Procedures ARREAD 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.
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.
ARSTART TMF ARLIB2 Audit-Reading Procedures 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-ext-seg-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-ext-seg-size ARSTART input, optional INT:value specifies the maximum size (in megabytes) of another extended segment that will be used for caching labels for SQL/MX objects. The minimum is 2, the maximum is 128, and the default is 5. ar-version input INT:value specifies which version of the ARRECORD structure your program understands.
TMF ARLIB2 Audit-Reading Procedures ARSTOP ARSTOP This procedure does the appropriate cleanup and closes the programmatic interface. CALL ARSTOP ( 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 (later in section) describes the error codes. Warnings (>0) None.
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).
TMF ARLIB2 Audit-Reading Procedures Error Codes 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.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 1 of 4) Code DDL Name Meaning Successful 0 AR-OK Successful completion. User Errors -1 ARE-ALREADY-STARTED You called ARSTART, but audit reading is already started. -2 ARE-BAD-PARAM-COMBINATION There is a conflict between two or more parameters that are valid when taken individually. -3 ARE-CURSOR-NOT-ALLOCATED The specified cursor was not allocated in the call to ARSTART.
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 2 of 4) Code DDL Name Meaning -16 ARE-DATA-FILE-VERSION The data file on disk is not the same type or does not have the same attributes as the one whose modification generated the current audit record. -17 ARE-FIELD-NOT-PRESENT The specified field does not exist in the current field-compressed update audit record (the field was not updated and is not part of the record key).
Error Codes TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 3 of 4) Code DDL Name Meaning -107 ARE-NEED-NEWER-SQLMX The current version of SQL/MX is not new enough to understand the current audit record. -108 ARE-NEED-OLDER-SQLMX The current version of SQL/MX is too new to understand the current audit record. File Management Error -700 ARE-WRITE-ERROR An error occurred while attempting to write to the specified file.
TMF ARLIB2 Audit-Reading Procedures Table 5-3. Error Codes by Class (page 4 of 4) Code DDL Name Meaning -902 ARE-FILE-NOT-FOUND The cursor is positioned to a sequence number that does not correspond to an audit file on disk, and audit restore failed or is not enabled. This error condition can result either from explicit cursor positioning (ARPOSITION) or successive reads. No further reads will be allowed for the current cursor until it has been repositioned.
TMF ARLIB2 Audit-Reading Procedures Use of AWAITIOX A third party can use the ELD step to build the application file that is shipped to its customer, the -libname option is not required. Then the customer can do the FUP LICENSE and TACL RUN command with the LIB option to prepare the files for execution. The FUP LICENSE and TACL RUN commands must be executed each time either file is replaced or moved.
TMF ARLIB2 Audit-Reading Procedures HP NonStop TMF Application Programmer’s Guide—540139-002 5- 98 Use of AWAITIOX
Index A ABORT audit record 5-21 Aborting transactions considerations 2-13/2-14 description of 1-4 ABORTTRANSACTION code 3-11 ABORTTRANSACTION TMF procedure description of 2-3, 4-2 errors 2-4 statements used for invoking 1-4 unlocking records 1-15 use and implications of 2-13 Access control block (ACB) 2-6 ACTIVATERECEIVETRANSID TMF procedure description of 4-4 multithreaded heterogeneous processes 3-14 restoring current transaction 2-13 After-image audit compression 5-7 field description 5-28 Applications,
B Index ARSETOPTIONS audit-reading procedure 5-85 ARSTART audit-reading procedure 5-87 ARSTOP audit-reading procedure 5-89 ARSTOPNETWORKRECS audit-reading procedure 5-90 ARSTOPNONDATACHNGRECS auditreading procedure 5-91 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 see also individual audit record names see also Subset audit record types 5-19 Audit trail files cursors 5-3 reading active 5-8
D Index COMPUTETRANSID TMF procedure 4-8 Concurrency see Database concurrency 1-11 Condition codes (CCL, CCE, CCG) 4-4 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-59 D Database concurrency 1-11/1-19 Database consistency achieving maximum 1-11 considerations 1-11/1-19 Enscrib
F Index F M Field alignment, NonStop 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 re
O Index O OPEN system procedure, opening the server process 1-6 Operations, nowait 4-10 Operations, waited 4-10 P Parent nodes identifying 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 description
T Index Servers (continued) subordinate 2-13 SETMODE = 117 1-10 SETMODE = 4 locking modes 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 STABLE ACCESS NonStop SQL/MP access options 1-13 Status descriptor 2-6 STATUSTRANSACTION TMF procedure 4-20 Subset audit records 5-
U Index 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 AUDITCOMP audit record 5-27 UPDATE FIELDCOMP audit record 5-28 V Variable-length character fields 5-17 Variable-length fields, reading 5-5 Volatile resource manager files 1-5 Volume field description 5-32 Volume Recovery anomalies 2-14 W Waited operations 4-10 WRITE system procedure 1-15 WRITER
Special Characters Index HP NonStop TMF Application Programmer’s Guide—540139-002 Index -8
