Blocking Record Reads with the c-tree Server

FairCom is always searching for ways to make the developer’s life easier. c-tree Server V8.14 has multitudes of great new features for ease of data management. The new Blocking Record Read feature is one frequently recommended by FairCom engineers to developers.

Frequently, applications encounter situations where they must wait on new records to appear in a data file before continuing. Consider the case of new orders with an accounts receivable module processing those new records. It would be a design headache to constantly check for new records in a data file. A convenient process is for the accounts receivable module to “park” on the file and wait for new records to appear.

The c-tree Server’s blocking record read feature permits an application to attempt a record read with an optional blocking condition, and if no records satisfy the read request, to wait until such a record exists or the block times out. This feature provides a convenient way for an application to process specified records from a file as they become available.

Upgrade to c-tree Server V8.14 and take advantage of this great new feature today! Contact your nearest FairCom office should you need additional details about this convenient new feature. Read on for details to get started right away.

Blocking Record Reads in Your Applications

A blocking record read is performed by calling the BlockingISAMRead() c-tree API function. The BlockingISAMRead() function operates by performing the requested ISAM operation (FIRST(), NEXT(), etc.). If successful, it then checks if the optional blocking condition is satisfied. If no record was found or if the record does not satisfy the blocking condition, and a non-zero time-out is specified, then the read blocks (sleeps) for the specified time-out period. The sleep is interrupted if the target file is updated, and the process repeats.

Either a record is found that satisfies the condition, or the block times out. A time out condition is indicated by returning NTIM_ERR (156).

Function Reference

The function prototype for the BlockingISAMRead() function is shown below:

ctCONV COUNT ctDECL BlockingISAMRead(COUNT filno, NINT opcode, LONG timeoutsec,

                                     pTEXT blockcond, pVOID target, pVOID recptr,

                                     pVRLEN plen)

where:

• filno is a file number of an open c-tree data or index file.
• opcode specifies one of the following ISAM read operations:

  ISAM Read Operation	Explanation
  ctBLKIREC_FIRST	Read first record in physical or key order
  ctBLKIREC_NEXT	Read next record in physical or key order
  ctBLKIREC_PREV	Read previous record in physical or key order
  ctBLKIREC_LAST	Read last record in physical or key order
  ctBLKIREC_GT	Read record with key value greater than target key
  ctBLKIREC_GTE	Read record with key value greater than or equal to target key
  ctBLKIREC_EQL	Read record with key value equal to target key
  ctBLKIREC_LTE	Read record with key value less than or equal to target key
  ctBLKIREC_LT	Read record with key value less than target key

• timeoutsec specifies the number of seconds the blocking read will wait before returning if no record satisfies the optional blockcond argument or no record is found. Set timeoutsec to zero to return immediately.
• blockcond is an optional conditional expression which may be a logical expression of the same form as used for conditional index support or a function callback as in a SetDataFilter() call. Set blockcond to an empty string (“”) to specify no condition.
• target should be non-NULL only if filno specifies an index and the opcode requires a target value (for example, ctBLKIREC_GT).
• The record is read into the buffer pointed to by recptr.
• plen should be NULL for a fixed-length read, and should point to the length of the output buffer (recptr) for a variable length read. *plen is updated to the actual record length upon successful return.