|
|
|
TransactionHistory
Permit scanning backward or forward through transaction logs.
Short Name
CTHIST()
Type
Low-Level function
Declaration
COUNT TransactionHistory(FILNO filno, pVOID target,
pVOID bufptr, LONG recbyt, VRLEN bufsiz, UCOUNT mode)
Description
In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering
A complete single-function API to access the audit logs of transaction controlled files for the purpose of putting valuable historical capabilities in any application. Determine who deleted a record; page back through all the changes to a specific record; see who performed write operations to a specific file during a qualified time frame. These are but a few examples of this powerful feature.
The history function, TransactionHistory(), permits an application to scan backward or forward through transaction logs, returning either key values or data records and optionally the user ID and node name of the process which performed the update. When scanning backward, TransactionHistory() will look for both active log files, ending with .FCS, and for inactive log files, ending with .FCA. The information extracted from the transaction logs can be based on:
On the first search call, set filno to the open data or index file number, or to -1 to return any file satisfying the search criteria. When filno specifies an index file, mode indicates whether TransactionHistory() returns a key value or the associated data record.
On the first search call, target points to a key value, a user ID and/or node name, or NULL, depending on the search request. On other calls, set target to NULL.
bufptr specifies the address where a search call returns log entries satisfying the search criteria. On non-search calls, set bufptr to NULL.
Set recbyt to the starting log number on a preliminary log call, to -1L on a terminating call, to zero or a particular data record location on a first search call, or to zero on subsequent search calls. bufsiz specifies the length of bufptr, the output buffer. If the buffer is too small to hold all the output requested, only bufsiz bytes are returned. If bufsiz is less than 40, error HSIZ_ERR (620) will be returned.
mode specifies the type of call, how to interpret the search criteria, and what to return to the output buffer. The following mode constants are found in ctport.h. Each represents a bit to be OR-ed into mode.
Mode Bit |
Usage |
|---|---|
ctHISTlog |
Signify preliminary log or terminate call. |
ctHISTfirst |
Signify first search call. |
ctHISTnext |
Signify subsequent search call. |
ctHISTfrwd |
Scan logs forward (default is back). |
ctHISTuser |
Match user ID. |
ctHISTnode |
Match node name. |
ctHISTpos |
Match byte offset (record position). |
ctHISTkey |
Match key value. |
ctHISTdata |
Return data record entries. |
ctHISTindx |
Return key value entries. |
ctHISTnet |
Return net change. |
ctHISTinfo |
Return User ID and node name info. |
Return
When TransactionHistory returns a non-zero value:
Value |
Symbolic Constant |
Explanation |
|---|---|---|
0 |
NO_ERROR |
No error occurred. |
610 |
HNUL_ERR |
NULL target not permitted for this request. |
611 |
HLOG_ERR |
Could not access/find transaction log. |
612 |
HSTR_ERR |
Must make a first search call (ctHISTfirst). |
613 |
HONE_ERR |
Can only return data OR index entries. |
614 |
HMAP_ERR |
Could not find ISAM map from specified index file to a data file. |
615 |
HIDX_ERR |
Cannot return index entries from a specified data file. |
616 |
HACT_ERR |
TransactionHistory() cannot be called during an application’s own active transaction. |
617 |
HNOT_ERR |
Did not find target. |
618 |
HENT_ERR |
No more transaction log entries. |
619 |
HZRO_ERR |
Zero recbyt not permitted on this request. |
620 |
HSIZ_ERR |
Bufsiz too small. |
621 |
HTYP_ERR |
Transaction type found in log not expected. |
622 |
HMID_ERR |
Must reset TransactionHistory() through a terminate call or preliminary log call. |
623 |
HMEM_ERR |
Not enough memory for TransactionHistory(). |
624 |
HNET_ERR |
Net change only applies to specific match of key or record position. |
625 |
HMTC_ERR |
Must specify exactly one matching criteria: ctHISTpos or ctHISTkey or one or both of ctHISTuser and ctHISTnode. |
626 |
HUND_ERR |
Encountered an UNDTRAN (undo committed transaction) going forward: must completely restart this set of history calls. Repeat the first search call and subsequent search calls: the undone transaction will be ignored. |
627 |
HUNK_ERR |
Unknown type of request. |
628 |
HFIL_ERR |
Must specify filno. |
629 |
HTFL_ERR |
Could not initialize internal file ID: preserve files and contact FairCom. |
See c-tree Error Codes for a complete listing of valid c-tree error values.
Example
See TRNHIS.C in the \ctree\samples directory.
Limitations
When a client on a heterogeneous network calls TransactionHistory(), it only converts the history header to match the client’s byte ordering. It does not convert the optional record header or the actual data or key image from the log. It returns them in their native form as they exist on the FairCom Server.
TransactionHistory() requires transaction logs, so it only works in single-user, transaction processing applications, or in client-server applications. Files created without the ctTRNLOG file mode are not included in the transaction logs, and are not accessible to TransactionHistory().
See also Record Offsets Under Huge File Support.
