Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

TransactionHistory Basic Operation

TransactionHistory() can be used on-line, interrogating current files and transaction logs as part of an active application. It can also be used off-line, examining a set of data, index, and log files saved from a single-user or client-server application. When scanning backward, TransactionHistory() looks for both active log files, ending with .FCS, and for inactive log files, ending with FCA.

TransactionHistory() makes four types of calls. The first two are search calls returning log entries. The third specifies a beginning log number, and the last resets the history state, permitting a new set of history calls. These calls can be characterized as follows:

First search call

Specifies the search characteristics and the return information type. This call returns the first entry in the log satisfying the search criteria.

Subsequent search calls

Returns the next entry satisfying the search criteria. Do not specify the search criteria or the return information type. These are specified in the first search call. Specify an output buffer address and length on every search call.

Preliminary log call

Only specifies a beginning log number.

Terminating call

Cleans up the current history set permitting a new set of history calls starting with a new first search call.

For on-line use, make a first search call, then make subsequent search calls. An on-line search works backward through the files, beginning with the current log position.

For an off-line utility, use TransactionHistory() almost the same as an on-line search, except an optional preliminary log call can specify the starting log number. Off-line searches may be either forward or backward through the logs. While backward searches are the most common, if additional log files have accumulated since the data and index files were saved, a forward search can be meaningful.

Beginning with V6.7, the file create, open, and close entries in the log carry a time stamp permitting TransactionHistory() to locate the appropriate position in the log to begin off-line searches. However, when not specifying an explicit file, the beginning log number, set with a preliminary log call, helps narrow the TransactionHistory() search.

When TransactionHistory() returns a non-zero error code, it automatically frees internal memory allocated to the current history set and resets the history status to allow a new history set. No terminating call is required. When no more information in the transaction logs satisfies the search criteria, TransactionHistory() returns HENT_ERR (618). A first search call made before the log entries for the current history set are exhausted and before a terminating call is made returns HMID_ERR (622).

To switch to a new set of history calls before exhausting all log entries in the current history set, either terminate the existing history set, or use multiple history sets. See Multiple History Sets under Advanced Operations.

Preliminary log calls and terminate calls appear as follows:

TransactionHistory(-1, (pVOID)0, (pVOID)0, recbyt, (VRLEN)0, ctHISTlog);

Where recbyt is set to the beginning log number on a preliminary log call, or where recbyt is set to 1L to terminate the current history set.

Subsequent search calls appear as follows:

TransactionHistory(-1, (pVOID)0, bufptr, (LONG)0, bufsiz, ctHISTnext);

Where bufptr points to the output buffer and bufsiz specifies the length of bufptr.

A first search call mode includes ctHISTfirst. If searching forward through the logs, ctHISTfrwd must be OR-ed into mode, otherwise it defaults to backward. The three types of matching or search criteria include:

ctHISTpos

Matches the data record position, with a recbyt of zero matching all data record positions.

ctHISTkey

Matches the key value, with a null target matching all key values.

ctHISTuser and/or ctHISTnode

Matches user ID or node name respectively, with an empty string target matching all user ID’s.

A first search call must use exactly one of these three matching criteria: (1) ctHISTpos, (2) ctHISTkey, or (3) one or both of ctHISTuser and ctHISTnode. Any of the three can be used to specify the search criteria over specific files, signified by a non-negative filno). In a search over all files, signified by a filno of -1, ctHISTpos and ctHISTkey are not used, but one or both of ctHISTuser and ctHISTnode must OR-ed in. In all cases, either ctHISTdata or ctHISTindx must specify the return type. The following table gives the interpretation of mode, filno, target, and recbyt in the first search call:

Note: The first 6 column headings in the following table should be prefaced with ctHIST, i.e., pos is ctHISTpos, key is ctHISTkey, etc.

Possible First Search Call Combinations

p
o
s

k
e
y

u
s
e
r

n
o
d
e

d
a
t
a

i
n
d
x

filno

target

recbyt

interpretation

 

 

a

a

x

 

-1

userID

zero

Return all data entries for all data files updated by matching user.

 

 

a

a

 

x

-1

userID

zero

Return all index entries for all index files updated by matching user.

x

 

 

 

x

 

Data

NULL

zero

Return all data entries for specified data file.

x

 

 

 

x

 

Data

NULL

non-zero

Return data entries matching recbyt for specified data file.

 

 

a

a

x

 

Data

userID

zero

Return all data entries for specified data file made by matching user.

 

 

a

a

x

 

Data

userID

non-zero

Return data entries matching recbyt for specified data file made by matching user.

 

x

 

 

x

 

Indx

key

zero

Return all data entries with index matching key*.

 

x

 

 

x

 

Indx

key

non-zero

Return all data entries with index matching key and recbyt**.

 

x

 

 

 

x

Indx

NULL

zero

Return all index entries for specified index file.

 

x

 

 

 

x

Indx

NULL

non-zero

Return all index entries for specified index file which match recbyt.

x

 

 

 

x

 

Indx

NULL

non-zero

Return all data entries with index matching recbyt for specified index file.

 

 

a

a

 

x

Indx

userID

zero

Return all index entries for specified index file made by matching user.

 

 

a

a

 

x

Indx

userID

non-zero

Return all index entries for specified index file that match recbyt and made by matching user.

Note:

x

Indicates the bit is turned on in mode.

a

(active) indicates one or more of these bits is turned on.

*

Index matching key means the key value for the data record matches target for the specified index file.

**

an index entry matching recbyt means the index entry points to a record offset matching recbyt.

Two additional mode bits may be OR-ed in: ctHISTinfo and ctHISTnet.

  1. ctHISTinfo returns the user ID and node name of the process which made the log entries in the form of a null terminated ASCII string with a vertical bar (‘|’) preceding the node name, if present. This user information is in addition to the data or index information requested.
  2. For searches of specific files with specific matching criteria, i.e., a non-null target for an index or a non-zero recbyt for a data file, ctHISTnet returns only the net affect of each transaction, not each individual update within the transaction.

When mode includes ctHISTuser or ctHISTnode, pass the user ID in target as a null terminated ASCII string. If only ctHISTuser is on, target is case insensitive, corresponding to the user ID’s specified during logon to a FairCom Server. If only ctHISTnode is on, target is case sensitive, corresponding to the node name set by SETNODE(). If both ctHISTuser and ctHISTnode are on, target is a single null-terminated composite string beginning with a case insensitive user ID, a vertical bar (‘|’), and a case sensitive node name. To match all users, turn on ctHISTuser and set target to an empty string (“”), not a null pointer. If no user ID exists, TransactionHistory() appends a null byte to the data or index information.

The Transaction History feature is enabled by default, but may be disabled by adding #define NO_HISTORY to ctoptn.h/ctree.mak.

TOCIndex