Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

UserLogEntry

Allows a user specified message to be written to the transaction logs.

Short Name

TRANUSR()

Declaration

The function declaration is as follows:

LONG UserLogEntry(FILNO filno, LONG poshw, LONG poslw, LONG offset,
LONG attribute, pVOID buffer, VRLEN bufsiz)

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

UserLogEntry() returns the low-order word of the transaction number associated with the log entry. A return value of zero indicates an error and uerr_cod contains the error number. The high-order word of the transaction number is returned by a call to ctGETHGH() after a successful call to UserLogEntry().

  • filno specifies a user file number or -1 if no file number.
  • poshw, poslw, and offset specify three 4-byte integers to be used as desired. By convention, poshw and poslw are the high and low-order words of a file position, and offset specifies the number of bytes this file position is from the beginning of a logical record. However there is no restriction on how the user interprets these three words.
  • attribute specifies a 4-byte integer stored in the tranatr word of the TRANDSC structure. It is intended to permit the user to specify the type of user log entry. There are two restrictions:
    1. The highest order three bits of the 4-byte integer cannot be used. Error BMOD_ERR () will result otherwise.
    2. If the attribute is an even integer, then the log entry is part of the user’s existing transaction, is subject to transaction save points, and may not appear in the log unless and until TRANEND() is called.

    Note: If the integer is odd, then the log entry is not part of a transaction, and it is assigned its own “transaction” number and is written immediately into the log buffer.

  • buffer points to an optional variable-length portion of the log entry. Its contents are completely arbitrary.
  • bufsiz is the length of buffer. It should be zero if buffer is NULL. It is not permitted to exceed a configurable limit. If bufsiz exceeds the limit, a PBAD_ERR (749) occurs. The limit prevents a malicious program from "swamping" the log. The server configuration keyword
    MAX_USER_LOG_ENTRY_BYTES < maximum number of bytes in variable region>
    overrides the default limit of 16KB.

TOCIndex