TransactionHistory

Permit scanning backward or forward through transaction logs.

Short Name

CTHIST()

Type

Low level function

Declaration

COUNT TransactionHistory(COUNT filno, pVOID target,

               pVOID bufptr, LONG recbyt, VRLEN bufsiz, UCOUNT mode)

Description

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:

• A particular record position of a specified data file.
• A particular key value of a specified unique index.
• All updates to a specified file.
• Updates made by a particular user ID and/or node name.
• Some combination of the above.

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.

Return

When TransactionHistory returns a non-zero value:

1. The current history set is canceled.
2. Memory associated with the set is freed.
3. To make additional TransactionHistory calls, make a new first search call.

   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 Plus Error Codes for a complete listing of valid c-tree Plus 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 c-tree 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().