|
|
|
As outlined above, the output buffer contains the following information after a successful first search call or subsequent search call:
The TransactionHistory() header is an instance of the 40-byte HSTRSP structure, defined in ctport.h, composed of the following fields:
LONG tranno; /* transaction number */
LONG recbyt; /* log entry data record byte offset */
LONG lognum; /* the log number for the entry */
LONG logpos; /* the offset within the log for the entry */
LONG imglen; /* the length of the data or key value returned */
LONG trntim; /* the time stamp for the transaction */
LONG trnfil; /* the internal file number for the log entry */
LONG resrvd; /* reserved for future use */
UCOUNT membno; /* the index member number */
UCOUNT imgmap; /* details concerning the data returned */
COUNT trntyp; /* the type of transaction log entry */
COUNT trnusr; /* internal user number which made the entry */
Each data and index entry in a transaction log belongs to a particular transaction. Each such transaction is assigned a unique number. This transaction number is returned in tranno. Each data and index entry is for a particular file at a particular data record location. recbyt contains this data record location, expressed as a byte offset from the beginning of the file. trnfil contains the unique file number assigned to each data and index file upon their creation or actual opening. Each time a file is opened, it is assigned a new file number. trntim contains the commit time of the transaction. In the event that this commit time cannot be determined, it is set to zero.
It is very important to note that more than one actual log entry may be combined in order to return an image of a data record. Variable-length data records and resources are composed of a header and the actual data. These components are written to the log separately, and must be combined to generate a coherent data entry. Further, a scan of the log based on an index file returning the corresponding data information may require more than one log entry to generate the returned data entry. Therefore, the lognum, logpos, and trntyp fields in the history header reflect only one of possibly several log entries combined to create the return information.
The imglen field contains the length of the key value or data record image returned in the output buffer just following the 40-byte history header. imglen includes the length of an optional record header before the data or resource image, if it is present. imglen does not include the length of the user ID and/or file name appended to the end of the key value or data record image. These null terminated ASCII string fields follow immediately after the key or record image.
When a record header is present, the lowest order byte of imgmap contains the length of the record header. To determine the length of the record header, you must AND (‘&’) imgmap with ctHISTmapmask. When using ctHISTnet, if the transaction resulted in the delete of the data record in question, ctHISTkdel is set in imgmap, signifying that the deleted key value, not a data record image has been returned.
When filno equals 1 on a first search call, returning entries for all data or index files, one of the following bits of the imgmap field will be set:
In addition to one of these bits being set in imgmap, the file name of the index or data entry returned is appended to bufptr, see TransactionHistory() Output. If the appended file is an index file, membno contains the index member number for that file. The host index is member number zero.
The position of the log entry in the transaction logs is specified by the log number, lognum, and the offset, logpos, of the entry within the log.
Each log entry is made by a specified user. A non-unique user number is assigned to each logon until logoff. At logoff, the user number may be reassigned to another logon. trnusr contains this internal, non-unique user number.
Each log entry is assigned a transaction type. This type number determines how to interpret the contents of the transaction log entry and is returned in trntyp. The following transaction types relevant to TransactionHistory() are found in ctopt2.h:
Transaction Type |
Description |
LADDKEY |
add key value |
LDELKEY |
delete key value |
NEWLINK |
delete stack link |
NEWIMAGE |
new record image |
OLDFILL |
old image ff filled |
OLDIMAGE |
old record image |
DIFIMAGE |
old/new difference image |
LOGEXTFIL |
extend file |
NODEXTFIL |
extend file |
