log_ctx

NAME: log_ctx - standard log abstraction

SYNOPSIS

#include <log_ctx.h>

typedef struct log_entry_type_ {
    char          *type;
    a2c_module    *module;
    UINT4          selector;
} *log_entry_type;

int LOG_delete(ctxp)
  log_ctx    *ctxp;

int LOG_read(ctx, type, entry, time)
  log_ctx           ctx;       /* IN */
  log_entry_type    type;      /* IN */
  VOID             *entry;     /* IN */
  time_t            date;      /* OUT, may be 0 */

int LOG_write(ctx, type, entry)
  log_ctx           ctx;       /* IN */
  log_entry_type    type;      /* IN */
  VOID             *entry;     /* IN */

DESCRIPTION

log_ctx is a log abstraction that allows SETREF to maintain information about previous transactions, primarily to fulfill idempotency requirements.

LOG_delete() deletes the log_ctx. A log_ctx is no longer usable following a call to LOG_delete().

LOG_read() obtains the log entry timestamp from the log. If the requested entry doesn't exist, LOG_CTX_WARN_NO_LOG_ENTRY is returned.

LOG_write() places a log entry into the log.

PARAMETERS: If LOG_read is given a 0 pointer for the date parameter, the timestamp is not put into date. However, LOG_read will still report whether or not the entry exists in the log.

RETURN VALUES

On success, LOG_delete() returns NO_ERROR. On failure, LOG_delete() returns LOG_CTX_ERR_BAD_PARAMETER.

When the requested state is not in the log, LOG_read() returns LOG_CTX_WARN_NO_ENTRY.

See Return Values for descriptions of individual error codes. For documentation on displaying or logging return values, see error_ctx.

SEE ALSO: log_ctx_db

NOTES: The ctx argument must be initialized prior to use. See log_ctx_db for information on creating a log_ctx.
LOG_read(), LOG_write(), and LOG_delete() are macros, but only the ctx argument appears more than once in the macro expansion. Therefore, it is safe to use arguments with side effects (in particular, those using the ++ or -- operator), for all arguments except ctx. These macros should always be used to invoke the underlying functions, rather than invoking the functions directly.

EXAMPLE

int
add_XID_to_log(xid)
    asn1set__XID   *xid;
{
    log_ctx         history;       /* past-transaction data */


    /*  Open the log. */  
    status = create_log_ctx_db(&history, "history.log");
    assert(status == NO_ERROR);

    /*  Insert the XID into the log. */
    status = LOG_write(history, LOG_ENTRY_XID, xid);
    assert(status == NO_ERROR);

    /*  Delete the log object.  If other messages associated
     *  with this transaction are going to be processed, the
     *  log should remain open.
     *
     *  In this case, LOG_delete does not delete the underlying
     *  log (which is the semantics of log_ctx_db, a log_ctx
     *  that uses a database for persistence). */

    status = LOG_delete(&history)
    assert(status == NO_ERROR);

    return NO_ERROR;
}

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.