Ingres CL LG
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - LG
Abstract
This is the specification of the LG facility provided by the compatibility library for DBMS logging.
Revision: 1.0, 4-Oct-91
Document History
- Revision 1.0, last modified 4-Oct-91.
- Fixed typos.
- Fixed error in LGCshow parameter list. It does take a CL_ERR_DESC.
- Major corrections to LGcnode_info, which was moved, and added missing LGCnode_names.
Specification
Introduction
LG provides log file operations required for support of transaction logging in the DBMS.
Library
Now part of DMF was part of CL
Intended Uses
The LG services are intended for use by the DMF code to manage the log file and its associated memory resident data structures. The log file contains a sequence of log records that describe the operations performed on database objects by the DMF code. These log file records are used to recover database objects which are left in an inconsistent state in the event of a software, hardware or user initiatated failure. The log records can also be used to represent a history of changes to the database.
Assumptions
It is assumed that the reader is familar with the basic concepts of a write-ahead log (WAL).
The host operating system needs to have the capability of guaranteeing that the log data has been safely written to the log file.
The actual log file can be implemented using a DI type file of the appropriate block size, or by a specific implementation for LG type files.
The performance of the LG routines is paramount to the performance of the transaction logging, archiving and recovery system. Special care should be taken to insure that the LG routines, especially LGwrite, are implemented in a efficent manner.
The log file can be mirrored (duplexed, shadowed) across multiple physical devices so as to eliminate a single point of failure, and the real threat of lost data. The log file contains the most recent state of the database. If the log file is lost the databases can be restored to a previous point in time, but some amount of work will be lost.
Definitions
| Archive | This describes the process of purging the log file of log records which are stale or that have been safely copied to secondary permanent storage. This secondary permanent storage is called a journal file and is managed by the JF CL routines. The program that performs these operations is called the 'archiver'. | |||||||||||||||
| Consistency point | A consistency point is a special set of log records that are written to the log file at periodic intervals. The consistency point is used in the crash recovery process to aid in locating the last log page written, the set of open databases, and the set of active transactions. Without a consistency point, the whole log file would have to be searched to locate the last page written, and to recalculate the set of databases and transactions.
The interval between consistency points can be set by the client. For example: the DMF recovery process sets the consistency point interval when it is started. | |||||||||||||||
| Database | The logging system maintains a small set of information about an object which it calls a database (equivalent to an INGRES database.) This information is used to track usage of a database, to tag log records with the database that they belong to, to find the disk location of the database for the recovery system.
An LG call exists to return all the internal information about a database. The structure LG_DATABASE describes the form of this information. | |||||||||||||||
| Database_id | The LG system assigns a unique identifer (LG_DBID) to every database it handles. This identifer is used by other LG calls to identify a specific database. | |||||||||||||||
| Event | The logging system remembers when certain events have occured that a client should handle. These events include: the need to write a consistency point, archivable data exists in the log file, a process terminated leaving a transaction in-progress. The client code is expected to handle the event and then clear the event with a call to LGalter(). For example: the DMF recovery process waits for the event associated with consistency point generation. The complete set of Logging System events, with event definitions, may be found in the LGevent() section of this chapter. | |||||||||||||||
| Log Address | When log records are written to the log file, the log record is assigned a number called the log address. The log address represents the location in the log file where the record was written. The log address points to the offset of the last log word containing data for this log record.
The log address is composed of three components: the log sequence number, the log page number, and the log word offset. The log sequence number counts the number of times that log addresses have wrapped around to the beginning of the circular log file. The log page number, is a number from 1 to the number of pages in the log file. The log word offset is a number from 0 to the size of a log page minus 4 (i.e. if log page size = 4096 then maximum log word offset would be 4092). The log address is designed to fit into a 64-bit word. The sequence number always uses 32-bits. The page number and the offset vary in size depending on the size of a log page. The offset uses as many bits as needed to represent an offset for a log page size of 4096..32768 bytes. The page uses the remaining bits after accounting for the number of bits in the offset.
| |||||||||||||||
| Log File | The log file is an operating system file that is used to contain the log pages. The log file if logically composed of two parts: the log file header and the log file data.
The log file header contains information about the log file. See 'Log Header'. The log file data area encompasses log pages 1 through the number of pages in the log file. When the last physical log page has been written, physical page 1 becomes the next log page (I.E. a circular file.) The log address has its sequence number field incremented when this wraparound occurs.
| |||||||||||||||
| Log Header | The first page (page 0) of the log file is called the log header. The log header contains information that describes the log file. This information includes: the log file format version, the log header checksum, the log page size, the number of log pages, the log file status indicators, the log address of the beginning of file, the log address of the end of file, and the log address of the last consistency point.
Various LG calls exist to read, change and write the log file header. The structure LG_HEADER describes the log header. | |||||||||||||||
| Log Page | A log page is composed of two components: the log page header and the log page data area. The log page header contains the following information: the log address of the last complete log record written to the page, the checksum of the log page, the number of bytes used on this log page, and an extra field that is initialized to zero.
The log address of the last full log record is used to position to a full record on an arbitary page. If the log address offset is zero then either nothing was written to the page or a very long log record that spans multiple pages was written to this page. The checksum is used to guarantee that the log was successfully written and subsequently read from the log file. The checksum includes the log page header and chunks of data from various sections of the log page. The contents of the whole log are not included because of the cost in CPU resources. The internal format of the log page is known to the client. The crash recovery code uses the log page header information to locate the last log page written. | |||||||||||||||
| Log Record | A log record is composed of two components: the log record header(LG_HEADER) and the log record data area.
The client log record is encapsulated in a log record header constructed by the LG routines. This header contains the following information: the length of the encapsulated log record, the database identifier for the database this log record was written for, the transaction identifer of the transaction which wrote the log record, the sequence number of this log record relative to the beginning of the transaction, the log address of the previous log record written by this transaction, the client log record, and again the length of the encapsulated log record. Both LRH and the length at the end are returned to the caller as well as the record. The length of the log record is stored on both ends of the log record to facilitate forward and backward traversal of the log records. This information is for use of the LG routines for reading forward or backward and for the use of the client. Encapsulated log records are always rounded up to a multiple of a log word (see below). Client log records have a maximum size denoted by the constant LG_MAX_RSZ (Currently 4096). The part of the log record header that occurs before the client data cannot span a log page. | |||||||||||||||
| Log Word | This is the minimum unit of allocation for a log page and is 4 bytes. All log records are padded to be a multiple of log words so that information is stored on aligned boundaries in the log file, thus allowing direct access to structures stored in the log file. This also guarantees that each of the length fields in a log record never spans a page. The pad bytes are sent back to the client. | |||||||||||||||
| Logging_id | The LG system assigns a unique identifer (LG_LGID) to every process that opens the log file. This identifer is used by other LG calls to determine which process is making the request. | |||||||||||||||
| Master | The logging system recognizes one process that has the log file open as the master process. The master process is given the ability to alter any of the logging system data structures.
The master is responsible for initializing the logging system and for determining the operational policies. | |||||||||||||||
| Position Context | Read operations from the log file require a context area to maintain position information between successive requests. The LGposition() call initializes a client supplied data area and successive LGread() calls update this context. The size of the context area is denoted by the constant LG_MAX_CTX. | |||||||||||||||
| Transaction | The logging system maintains a small set of information about transactions that are in progress. This information is used to track the progress of an active transaction. The information recorded about a transaction includes: the physical transaction identifier, the database the transaction is using, the number of log records written by this transaction, the log address of the first log record for the transaction, the log address of the last log record for the transaction.
An LG call exists to return all the internal information about a transaction. The structure LG_TRANSACTION describes the form of this information. | |||||||||||||||
| Transaction_id | The LG system assigns a unique identifer (LG_LXID) to every transaction that is started. This identifier is used by other LG calls to determine the transaction that is being referenced. This is different than the external transaction identifer (LG_TRAN_ID) that is also assigned at the same time. The external transaction identifer is used to remember the transactions at each site which comprise a distributed transaction. |
Concepts
The LG routines provide the low level support for maintaining the memory resident data structures associated with the log file. The actions that these routines perform handle the majority of the normal processing performed by the logging system. These actions include: reading the log file, writing the log file, writing the log file header, maintaining the logging system data structures.
The client is responsible for rare, time consuming, and complicated processing. This type of processing include; verifing the integrity of the log file, initializing the memory resident copy of the log file header, writing consistency points, resolving transactions that have been orphaned, initializing the log file. These actions require that decisions be made and the appropriate changes sent to the logging system.
The logging system notifies the client of certain events that the client may wish to handle. The logging system records that a specific event has occured. The client can recognize an event one of three ways: the client can wait for a specific event to occur, the client can wait for any event in a set of events to occur or the client can poll the current event settings.
In the following example, the division of labor between the client and the logging system is outlined.
- The client initializes the logging system and sets the beginning of file and the end of file addresses.
- The logging system will allow writes to occur to the log file as long as space exists in the log file.
- When the log file is full, the logging system posts an event (LG_E_LOGFULL) that signifies that the log file is full. All further writes to the log will be stalled until the enough free space has been obtained to bring the file below its full indicator. The recovery process and archiver are responsible for freeing up space in the log file.
- The client must free up space in the log file and reset the beginning of file address. Once the beginning of file address is changed, the logging system will restart any log writes in- progress and allow new log writes.
- When the client wishes to stop the logging system, the client sets the shutdown flag.
- When the logging system notices the shutdown flag has been set it disallows any new transactions from starting. When the last transaction has completed, the logging system will post the event signifying that shutdown is complete.
The logging system is the mechanism for manipulating the log file. The client is responsible for setting the policy on how the log file should be manipulated.
The logging system recognizes one process that has the log file open as a master process. The master process is the special process that is allowed to make any LGalter call. The master process is the process that sets the policy. The master process must exist before any other process can start. If the master process terminates, all other processes will receive errors from succeeding logging system calls.
The logging system data structures can be displayed by using the LGshow() routine. This routine can return any of the information that the logging system maintains.
The logging system data structures can be changed by using the LGalter() routine. This routine can change most of the information that the logging system maintains. For example the log page can be set to one of the following sizes: 4096, 8192, 16384, 32768.
The log file can be up to 4G bytes in size.
Consistency Point Protocol
The Consistency Point protocol is a complex protocol which synchronizes the actions of the RCP, the ACP, and any number of servers which are running with Fast Commit. Its main task is to flush dirty pages out of the DMF Buffer Manager at Consistency Points.
NOTE: This description of the Consistency Point Protocol is only valid when Online Backup and Shared Buffer Managers are NOT being used. When Online Backup is being used, the ACP process participates in this protocol as well.
Although Fast Commit uses two special threads (Fast Commit threads and Write Behind threads), only the Fast Commit thread is relevant to this discussion. The Protocol operates as follows:
- When the Logging System notices that a Consistency Point is needed, it signals the LG_E_BCP event to notify the RCP and ACP that a Consistency Point should be begun.
- When the RCP is ready for the Consistency Point to begin, it calls LGalter(LG_A_BCPDONE) to notify the Logging System that the CP may now start.
- In a Fast Commit environment, the start of a Consistency Point causes the Logging System to signal the LG_E_CPFLUSH event to all FC servers (all processes which added databases with LG_FCT enabled).
- (If Fast Commit is not being performed, the Logging System instead advances directly to step (8)).
- The LG_E_CPFLUSH event requests that the server flush all its dirty pages.
- When the server finishes flushing its dirty pages, it notifies the Logging System that it has done so by issuing LGalter(LG_A_CPFDONE).
- When ALL Fast Commit servers have flushed their dirty pages, the Logging System signals the LG_E_CPWAKEUP event to each server.
- The servers will then each acknowledge the LG_E_CPWAKEUP event by calling LGalter(LG_A_CPWAITDONE).
- When ALL Fast Commit servers have acknowledged the LG_E_CPWAKEUP event, the Logging System signals the LG_E_ECP event to notify the RCP and ACP that the Consistency Point may now be completed.
- When the RCP has completed its Consistency Point processing, it notifies the Logging System of the completion by calling LGalter(LG_A_ECPDONE).
To provide support for the multiple processor systems such as the VMSCluster within the logging system, special routines are included in the LG specification. These routines are:
- LGcluster
- LGcnode_info
- LGCread
- LGCwrite
- LGCopen
- LGCclose
- LGCposition
In all environments these routines must exist. In all environments except the multiprocessor implementation these routines (except for LGcluster) should do nothing but return OK. They will only be called if the LGcluster routine returns a positive value. For all environments except the multiprocessor implementation LGcluster must return a value of zero.
Under the current implementation of Multi-Server Fast Commit, when a server exits abnormally (without having called LGclose) while connected to a shared buffer manager, the system assumes that the shared buffer manager may be corrupted. For this reason a server crash will cause the death of all other servers which are sharing the same buffer manager.
Each server that connects to a shared buffer manager will register which buffer manager it is using by an LGalter call described below. Whenever a server exists abnormally while connected to a shared buffer manager, LG will kill any other servers which are connected to the same buffer manager.
LG will assure that recovery is done correctly on the open transactions and databases. REDO recovery on databases opened by the buffer manager cannot be done until all active transactions on those databases are recovered.
(Currently, when a server using Fast Commit fails, LG marks the open transactions as needing recovery, and the database as needing recovery. The recovery system will first recover the transactions, then execute redo recovery on the database. This was possible since only one Fast Commit server could have a database open at one time.)
Since now that multiple Fast Commit servers can open a database at one time (as long as they go through a common shared buffer manager), before LG can mark a database for REDO recovery, it must make sure that all transactions in all servers on that database are marked for recovery.
Header File <lg.h>
The header file <lg.h> must be included before using any of the functions provided. It defines the following.
LG_LA - log system log address
This structure describes the format of a log system record address.
typedef struct _LG_LA
{
u_i4 lga_high; /* Most significant part of LA. */
u_i4 lga_low; /* Least significant part of LA */
};
LG_TRAN_ID - Physical transaction identifier
This structure describes the format of a physical transaction identifier. This must be identical to the structure LK_UNIQUE and must match the beginning of the structure LK_VALUE. LK_UNIQUE requires that high cannot be zero.
typedef struct _LG_TRAN_ID
{
u_i4 lgt_high; /* Most significant part of tran_id */
u_i4 lgt_low; /* Least significant part of tran_id*/
};
LG_DBID - Log system database identifier
This structure is the database identifier returned by a call to LGadd().
typedef longnat LG_DBID;
LG_RECORD - Log system record header format
This structure describes the format of a log record header that is returned from a call to LGread(). This is a variable structure. The sized is rounded up to the next higher multiple of 4.
typedef struct _LG_RECORD
{
i4 lgr_length; /* Length of log record. */
LG_DBID lgr_dbid; /* Database identifier. */
i2 lgr_sequence; /* Record sequence number. */
i2 lgr_extra; /* dummy for alignment */
LG_TRAN_ID lgr_tran_id; /* Transaction identifier. */
LG_LA lgr_prev; /* Previous LG_RECORD. */
char lgr_record[4]; /* The actual record. */
};
LG_HEADER - LG log file header information.
This structure can be passed to LGshow() and LGalter() to inquire about the contents of the header, or to change the contents of the header in memory. LGforce actually writes the changed header page to disk.
The lgh_status field is used primarily during startup processing by the RCP, ACP and CSP. While the logging system (& RCP) are up and running, the header status is LGH_VALID.
The various LGH_* values for lgh_status have the following meaning:
| LGH_VALID | The logging system is up and running. The RCP (or the CSP) has completed machine failure recovery. If the header is in this state when the RCP starts up, the RCP must have crashed, so the logging system scans from the last CP to find the correct EOF. |
| LGH_RECOVER | Machine failure recovery is needed, but the BOF, EOF and last-CP addresses in the log file header have all been verified. This value is set by the RCP if it is shutdown with rcpconfig imm_shutdown and is also set during machine failure recovery after the RCP has scanned backward and verified the last Consistency Point in the log file (dmr_get_cp()). |
| LGH_EOF_OK | The logging system has scanned the log file and has located the true EOF position. The RCP can now proceed to verify the BOF and last-CP addresses. |
| LGH_BAD | The log file is unusable. An error occurred while reading the log file header, or an error occurred while scanning backward to find the last CP. The only thing that can be done with this log file is to re-initialize it. |
| LGH_OK | The RCP is not (yet) up, but the log file has been recovered and archived, if necessary. This state is similar to LGH_VALID, but indicates a certainty that no recovery action is needed. This state is set by the RCP during normal shutdown. It is also set by LGerase() after erasing the log file. Finally, it is set by the CSP in two different ways: 1) After startup processing and performed both recovery AND archiving of this node's log, and 2) After performing node-failure recovery of this node's log. |
LGH_OK is the only log file state (other than LGH_BAD) in which rcpconfig init is allowed. During typical recovery from a system failure, the log file progresses through its various stages as follows:
- log file is in LGH_VALID state at startup.
logging system scans forward from last CP and determines true EOF. Logging system sets status to LGH_EOF_OK.
RCP notices that state is EOF_OK and scans backward from EOF to find last Consistency Point. RCP then sets state to LGH_RECOVER.
RCP performs machine failure recovery, and then sets LGH_VALID, and system is now ready for use again.
typedef struct _LG_HEADER
{
i4 lgh_version; /* Version of log file format. */
#define LGH_VERSION 0x10001
i4 lgh_checksum; /* Checksum of file header. */
i4 lgh_size; /* Size of a log page. */
i4 lgh_countf; /* Number of log pages. */
i4 lgh_status; /* Current status. */
#define LGH_VALID 1
#define LGH_RECOVER 2
#define LGH_EOF_OK 3
#define LGH_BAD 4
#define LGH_OK 5
i4 lgh_l_logfull; /* When to stall everyone for logfull
** event. */
i4 lgh_l_abort; /* When to abort. */
i4 lgh_l_cp; /* When to generate a cp. */
i4 lgh_cpcnt; /* Maximum CP interval for invoking
** archiver. */
LG_TRAN_ID lgh_tran_id; /* Last Transaction Id used. */
LG_LA lgh_begin; /* Last begin of file. */
LG_LA lgh_end; /* Last end of file. */
LG_LA lgh_cp; /* Last consistency point. */
};
LG_STAT - Statistics information
This structure describes the statistics return structure as returned by the LGshow() call.
typedef struct _LG_STAT
{
i4 lgs_add; /* Database adds. */
i4 lgs_remove; /* Database removes. */
i4 lgs_begin; /* Begin transaction. */
i4 lgs_end; /* End transaction. */
i4 lgs_readio; /* Read I/O's. */
i4 lgs_writeio; /* Write I/O's. */
i4 lgs_write; /* Write record calls. */
i4 lgs_force; /* Force calls. */
i4 lgs_wait; /* Waits. */
i4 lgs_split; /* Log record splits. */
i4 lgs_group; /* Number of group commits. */
i4 lgs_group_count; /* Group commit count. */
i4 lgs_inconsist_db; /* Number of nconsistent database
** occurs. */
i4 lgs_check_timer; /* Number of group commits
** initiated */
i4 lgs_timer_write; /* Number of times the group commit
** protocol was run */
i4 lgs_kbytes; /* Number of 512 bytes chunks
** written */
};
LG_DATABASE - Database description
This structure is returned by the LGshow() call to describe an active database.
LG_DBINFO_MAX
Maximum database info size. This defines the maximum size database info that LGadd will accept. The size is based on the maximum legal path/filename/owner combination. These are determined by DB_MAXNAME and DB_AREA_MAX, but since those cannot be referenced by the CL, we must define them here.
This constant allows room for the following information in the add database info block.
| Database Name | DB_MAXNAME |
| Database Owner | DB_MAXNAME |
| Database Path | DB_AREA_MAX |
| Length of pathname | |
| Database ID |
The following value is recommended for all CL implementations:
#define LG_DBINFO_MAX 200
Constants:
| DB_INVALID | LDB control block is invalid. |
| DB_JOURNAL | Database is journaled. |
| DB_NOTDB | LDB control block does not describe an actual database - rather it is used as an administrative control block to allow a session to connect to the logging system and make LG/LK calls without actually opening a database. This is done by the RCP, ACP, as well as DMF utility functions. |
| DB_PURGE | Log records for this database are being purged to the journal files. This operation is normally signaled when a database is closed. When the ACP finishes purging the log records, then a CLOSE operation will probably be signaled. |
| DB_OPENDB_PEND | There is an OPENDB operation pending on this database. The RCP should recognize this event and process the open. Until the RCP finishes the open, no transactions can update the database. |
| DB_CLOSEDB_PEND | There is a CLOSEDB operation pending on this database. The RCP should recognize this event and process the close. If the database is journaled then all log records must be flushed to the jnl files before the close can be completed. Some utility operations (such as DESTROYDB, CHECKPOINT, ROLLFORWARD) must wait for the close to be completed before runnning. |
| DB_RECOVER | The database is being recovered. |
| DB_FAST_COMMIT | The database is open with Fast Commit. If a server with this database open crashes, then REDO recovery must be performed. Also, all other servers with this database open must be shut down in order for REDO recovery to be performed. |
| DB_PRETEND_CONSISTENT | The database is open even though it is inconsistent. This is used by destroydb and rollforward in order to do work on an inconsistent database. |
| DB_CLOSEDB_DONE | The database close operation has been completed. |
| DB_BACKUP | The database is undergoing online backup. |
| DB_STALL | The database is undergoing online backup and is currently stalled until all active transactions complete so that the Start Backup log record can be written. As soon as the SBACKUP record is written, all stalled transactions will continue. |
| DB_EBACKUP | The database is undergoing online backup and is in the EBACKUP state. This means that the backup copy of the database has been made, the End Backup log record has been written, and the archiver must now move all log records between the SBACKUP and EBACKUP to the dump files. |
| DB_FBACKUP | The database is undergoing online backup and is in the FBACKUP (Final Backup) state. All work backup work has been performed and all that is left is for the checkpoint process to update the config file marking the checkpoint complete. |
| DB_CKPDB_PEND | A CKPDB (Checkpoint) operation is pending. |
| DB_ONLINE_PURGE | The current database is in online backup and the LG_A_PURGEDB call has been made. The archiver, (when the LG_E_PURGEDB event is raised), will purge all journal records associated with this database to the journal file. This state is reached once online checkpoint has stalled all users, laid down a start backup record, and subsequently forced a CP. |
| DB_PRG_PEND | This state is enabled at the same time DB_ONLINE_PURGE is enabled. It is turned off during the ACP's LGshow(LG_S_PURJNLDB) of the database. The checkpoint process waits for this status to be turned off before proceeding with the backup. |
Definition:
typedef struct _LG_DATABASE
{
LG_DBID db_id; /* Database identifier. */
i4 db_l_buffer; /* Length of database information. */
char db_buffer[LG_DBINFO_MAX]; /* Database information buffer. */
i4 db_status; /* Status of the database. */
#define DB_INVALID 0x00000001
#define DB_JNL 0x00000002
#define DB_NOTDB 0x00000004
#define DB_PURGE 0x00000008
#define DB_OPENDB_PEND 0x00000010
#define DB_CLOSEDB_PEND 0x00000020
#define DB_RECOVER 0x00000040
#define DB_FAST_COMMIT 0x00000080
#define DB_PRETEND_CONSISTENT 0x00000100
#define DB_CLOSEDB_DONE 0x00000200
#define DB_BACKUP 0x00000400
#define DB_STALL 0x00000800
#define DB_EBACKUP 0x00001000
#define DB_FBACKUP 0x00002000
#define DB_CKPDB_PEND 0x00004000
#define DB_ONLINE_PURGE 0x00008000
#define DB_PRG_PEND 0x00010000
LG_LA db_f_jnl_cp; /* First CP with journal record. */
LG_LA db_l_jnl_cp; /* Last CP with journal record. */
struct
{
i4 trans; /* Active transaction count. */
i4 read; /* Read I/O for this database. */
i4 write; /* Write records for this database. */
i4 begin; /* Begin transactions for this db. */
i4 end; /* End transaction for this db. */
i4 force; /* Forces for this db. */
i4 wait; /* Waits for this db. */
} db_stat;
};
LG_LGID - Logging process id
This structure is returned by the LGopen() call to identify a process to the logging system.
typedef longnat LG_LGID;
LG_LXID - logging transaction id
This structure is returned by the LGbegin() call to identify a transaction to the logging system.
typedef longnat LG_LXID;
LG_TRANSACTION - transaction description
This structure is returned by the LGshow() call to describe an active transaction.
Constants:
| TR_INACTIVE | Transactions are marked inactive until the |
| TR_ACTIVE | first log record is written. The first log record must be a begin transaction record. The tran is then marked as TR_ACTIVE. NONPROTECT transactions are never marked ACTIVE. |
| TR_SPLIT | If there is not enough room in the current log buffer an entire log record being written, then the log record is split across log buffers. If the writer must wait for a new log buffer in order to complete writing the log record, the transaction is marked in TR_SPLIT state. |
| TR_PROTECT | Transaction is protected from the Archiver. The archiver will not advance the BOF past this begin transaction record for this transaction until the transaction has ended. |
| TR_JOURNAL | Records for this transaction should be archived to the journal file. |
| TR_READONLY | No database changes will be made inside this transaction. There should be no log writes made on behalf of it. |
| TR_NOABORT | This transaction will never be chosen as the oldest transaction to force abort. Only used in special places (archiver) where we know we will not need to force abort the transaction. |
| TR_RECOVER | Transaction needs recovery (usually because the server has died). |
| TR_FORCE_ABORT | Transaction has been chosen as the oldest tran to abort when the log has become full. |
| TR_SESSION_ABORT | Transaction is marked SESSION_ABORT when RCP is going to be signalled to abort the single transaction. |
| TR_SERVER_ABORT | The server has begun aborting this transaction. |
| TR_PASS_ABORT | The server failed to abort this transaction, and has asked the RCP to abort it. |
| TR_DBINCONST | If the database becomes inconsistent while a transaction is active, it is marked DBINCONST. |
| TR_WAIT | Transaction is currently waiting for something (NOTE: This flag was erroneously named TR_SAVEABORT in earlier versions of the system). |
| TR_DISTRIBUTED | This is a distributed transaction. |
| TR_WILLING_COMMIT | This distributed transaction is now in Willing Commit state. |
| TR_REASSOC_WAIT | This distributed transaction is now waiting for re-association with the distributed owner. |
| TR_RESUME | This distributed transaction has been resumed. |
| TR_MAN_ABORT | The LARTOOL user has requested a manual abort of this transaction. |
| TR_MAN_COMMIT | The LARTOOL user has requested a manual commit of this transaction. |
| TR_CKPDB_PEND | This transaction is being delayed because the database is in checkpoint pending state and no new transactions can log work until the database SBACKUP record has been written. |
Definition:
typedef struct _LG_TRANSACTION
{
i4 status; /* Transaction status. */
#define TR_INACTIVE 0x0001
#define TR_ACTIVE 0x0002
#define TR_SPLIT 0x0004
#define TR_PROTECT 0x0008
#define TR_JOURNAL 0x0010
#define TR_READONLY 0x0020
#define TR_NOABORT 0x0040
#define TR_RECOVER 0x0080
#define TR_FORCE_ABORT 0x0100
#define TR_SESSION_ABORT 0x0200
#define TR_SERVER_ABORT 0x0400
#define TR_PASS_ABORT 0x0800
#define TR_DBINCONST 0x1000
#define TR_WAIT 0x2000
#define TR_DISTRIBUTED 0x4000
#define TR_WILLING_COMMIT 0x8000
#define TR_REASSOC_WAIT 0x10000
#define TR_RESUME 0x20000
#define TR_MAN_ABORT 0x40000
#define TR_MAN_COMMIT 0x80000
#define TR_CKPDB_PEND 0x100000
LG_LXID tr_id; /* Internal transaction id. */
LG_TRAN_ID tr_eid; /* External transaction id. */
LG_DBID tr_db_id; /* Database for this transaction. */
LG_DBID tr_pr_id; /* Process for this transaction. */
i4 tr_lpd_id; /* Process database reference for this
** transaction. */
LG_LA tr_first; /* First log record address. */
LG_LA tr_last; /* Last log record address. */
LG_LA tr_cp; /* CP interval of first log record. */
struct
{
i4 write; /* Write records. */
i4 split; /* Write splits. */
i4 force; /* Force log. */
i4 wait; /* Log waits. */
} tr_stat;
i4 tr_sess_id; /* session id for this transaction */
};
LG_PROCESS - process description
This structure is returned by LGshow to describe a process attached to the logging system.
Constants:
| PR_MASTER | process is master recovery process (RCP) |
| PR_ARCHIVER | process is archiver process (ACP) |
| PR_FCT | process is a fast commit server |
| PR_RUNAWAY | process is a server that has died abnormally and therefore may require recovery |
| PR_SLAVE | process is a server |
| PR_CKPDB | process is checkpoint process |
| PR_VOID | process is dead and recovered, but there is still some transaction stuff left to resolve, so we need to leave the Process block around. |
| PR_SHARED_BUFMGR | process is a server that is connected to a shared buffer manager. |
| PR_IDLE | process is idle : used when process is connected to a shared buffer manager to indicate that the process can exit without causing the buffer manager to be corrupted. |
| PR_DYING | process has been killed by logging system but its rundown routine has not been run yet. |
| PR_DEAD | process has died : used when logging system is waiting for some other event (normally the death of another server) before recovering the process. |
Definition:
typedef struct _LG_PROCESS
{
i4 pr_id; /* Process identifier. */
i4 pr_pid; /* Process id. */
i4 pr_type; /* Status information. */
#define PR_MASTER 0x001
#define PR_ARCHIVER 0x002
#define PR_FCT 0x004
#define PR_RUNAWAY 0x008
#define PR_SLAVE 0x010
#define PR_CKPDB 0x020
#define PR_VOID 0x040
#define PR_SBM 0x080
#define PR_IDLE 0x100
#define PR_DEAD 0x200
#define PR_DYING 0x400
struct
{
i4 database; /* Open databases. */
i4 write; /* Writes. */
i4 force; /* Force log. */
i4 wait; /* Log waits. */
i4 begin; /* Begin transactions. */
i4 end; /* End transactions. */
} pr_stat;
};
LG_PURGE - information about a purged database
This structure is used to pass information about a purged database. Currently, this information is the last successful archived CP address.
typedef struct _LG_PURGE
{
LG_DBID lgp_dbid; /* Database identification. */
LG_LA lgp_f_cp; /* First journaled CP address. */
};
LG_OBJECT - describes Object being passed to LG_WRITE to be logged
This structure is used to describe an object to be logged in an LG_WRITE call. An array of LG_OBJECT structs is passed to LG_WRITE giving the size and address of a number of objects which together make up a log record.
typedef struct _LG_OBJECT
{
i4 lgo_size; /* Length of the data section. */
PTR lgo_data; /* Pointer to data section. */
};
Executable Interface
The following functions are provided.
LGadd - Add database
This routine adds a database to the logging system. This service is used to inform the logging system that records recorded in the log file should be associated with this database. A database can be marked as journalled by setting the LG_JOURNAL flag. The fact that a database is journalled is used by the logging system to recognize the need to copy log records from the log file to a journal file.
The size of the database information buffer must be at most LG_DBINFO_MAX bytes. That is, LG_DBINFO_MAX specifies the largest database info buffer that can be given to the CL.
Inputs:
| lg_id | Log identifer. | |
| flag | The of access desired for this database. The value may be a combination of the values: | |
| LG_NOT_DB | This is not really a database being added. | |
| LG_ADDONLY | Used to obtain an LG_DBID. | |
| LG_PRETEND_CONSISTENT | Used for recovery. | |
| LG_FCT | Fast commit will be used. | |
| LG_JOURNAL | This database is journalled. | |
| LG_WILLING_COMMIT | To add a database to the WILLING COMMIT transaction. | |
| buffer | Pointer to database information. No interpretation is performed by this routine. The client controls this. | |
| l_buffer | Length of buffer. |
Outputs:
| db_id | Database identifier. Unique identifier associated with this instantiation of the logging/locking server. After logging/locking restarted, a database can have a different id. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| LG_EXCEED_LIMIT | A logging system internal limit exceeded. |
Definition:
STATUS LGadd(lg_id, flag, buffer, l_buffer, db_id, sys_err) LG_LGID lg_id; i4 flag; char *buffer; i4 l_buffer; LG_DBID *db_id; CL_ERR_DESC *sys_err;
LGalter - alter the log information
This routine informs the log system of a requested change to a logging system information variable. The behavior of this routine changes dramatically depending on the value passed in 'flag', and so each different flag value is specified below.
Flag constants:
| LG_A_BCNT | Change block count of the number of log buffers in memory. buffer should be a longnat by reference containing the number of log buffers desired; l_buffer should be sizeof(longnat). The number of buffer can only be set at logging system initialization time, and only after the log file page size has been set. This call may fail if there is insufficient memory. |
| LG_A_BLKS | Change small control block limit. The Logging System uses small control blocks to keep track of processes, transactions, and process-database references. Thus the number of small control blocks establishes a limit on the total number of processes, transactions, and databases which may be active at once (typically the number of transactions is the dominant factor). buffer should be a longnat by reference containing the maximum number of small control blocks allowed; l_buffer should be sizeof(longnat). The number of small control blocks can only be set at logging system initialization time, and may fail if there is insufficient memory. |
| LG_A_LDBS | Change large control block limit. The Logging System uses large control blocks to keep track of the currently open databases. Thus the number of large control blocks establishes a limit on the total number of databases which may be active at once. buffer should be a longnat by reference containing the maximum number of large control blocks allowed; l_buffer should be sizeof(longnat). The number of large control blocks can only be set at logging system initialization time, and may fail if there is insufficient memory. |
| LG_A_HEADER | Change the content of the log header. The log header contains a number of important pieces of information about the log file itself, such as the log file's block size, and logical EOF position. In most environments, only the RCP will alter the log header; however, in a VMS Cluster the ACP may alter the header as well, using LGCalter(). buffer should be the address of an LG_HEADER structure; the contents of the pointed-to structure replace the current values for those fields in memory. l_buffer should be sizeof(LG_HEADER). NOTE: This call ONLY updates an in-memory copy of the log header; to ensure that the log file itself is updated the LGforce() call must be used. |
| LG_A_BOF | Change logical Begin of File file header. The log file is circular, and maintains a logical BOF and EOF. This LGalter() code is used to change the logical BOF position. For example, the ACP uses this call to notify the logging system that the ACP has successfully copied all needed information to the journal files. Typically the BOF is reset by the archiver when it has completed archiving the contents of a consistency point. buffer should be an LG_LA structure by reference, containing the log address which should become the new logical BOF position; l_buffer should be sizeof(LG_LA). NOTE: This call only changes the in-memory BOF position; LGforce() must be used to ensure the change is force to disk. NOTE: The logging system may change the BOF position automatically; this call is used by client code to request the change. |
| LG_A_EOF | Change logical End of File in file header. This call is not currently used; rather, the logical EOF position is advanced automatically by the LGwrite() call. |
| LG_A_DB | Mark database inconsistent. This call is used by the RCP to notify the Logging System that recovery of transactions for this database has failed. The database is marked inconsistent in the logging system, and the logging system will not allow the database to be opened. buffer should be a LG_DBID by reference, containing the database identifier of the inconsistent database. l_buffer should be sizeof(LG_DBID). |
| LG_A_CPA | Update the address of the last consistency point. The consistency point is used in the crash recovery process to aid in locationg the last log page written, the set of open databases, and the set of active transactions. buffer should be an LG_LA by reference, containing the log address of the current consistency point; l_buffer should be sizeof(LG_LGA). |
| LG_A_ONLINE | This call is used to alter the online/offline status of the Logging System. When the logging system is offline, only the Log Master (RCP) is allowed to use the Logging System. The Log Master will set the logging system online when it is prepared for other users of the Logging System to begin operation. buffer should be a longnat by reference, containing 0 if the logging system is to be set offline, and any non-zero value if the logging system is to be set online. l_buffer should be sizeof(longnat). |
| LG_A_RECOVERDONE | Acknowledge receipt of LG_E_RECOVER event. The RCP uses this LGalter() call to acknowledge the receipt of the LG_E_RECOVER event. Subsequent to this, the next recovery situation will generate a new LG_E_RECOVER event. In addition, the RCP uses this call to notify the Logging System that the RecoverDone portion of the Consistency Point protocol should now be invoked. buffer should be a longnat by reference, containing 0 if the CP protocol is NOT needed, and any non-zero value if the CP protocol IS needed. l_buffer should be sizeof(longnat). If buffer is non-zero, then a new Consistency Point is signalled by the Logging System. This CP will be processed after recovery is complete. If a CP is already in progress, then a new one will be started as soon as this one completes. The new BCP will prevent us from having to re-process recover work that we have just completed. |
| LG_A_SHUTDOWN | Start the Logging System shutdown. This call is used by rcpconfig to request a Logging System shutdown. The shutdown may be graceful or immediate. buffer should be a longnat by reference, containing 0 if the shutdown is to be immediate, and any non-zero value if the shutdown is to be graceful. A graceful shutdown proceeds by setting the Logging System into a shutdown state, waiting for all servers to exit, notifying the ACP that it should shutdown, and then taking the Logging System down. An immediate shutdown is immediate. l_buffer should be size of(longnat). |
| LG_A_ARCHIVE | This LGalter() call is used by the ACP to indicate that it has been awoken, but has no work to do. This call acknowledges the receipt of the LG_E_ARCHIVE event in the special case when the archive has no work to do. buffer should be a longnat by reference, and should always have the value 0. l_buffer should be sizeof(longnat) |
| LG_A_STAMP | This call is used to set the cluster log sequence stamp. It should probably not be here, but should instead be an LGCalter() call only. |
| LG_A_CPFDONE | This LGalter() call is part of the Fast Commit Consistency Point protocol. This call is used by the Fast Commit Thread in each FCT Server to indicate that all dirty pages have been flushed from that server's cache. When ALL FCT Servers have flushed their dirty pages, the Logging System signals the LG_E_CPWAKEUP event to each such server. buffer should be an LG_LGID by reference, containing the logging system ID of this server. l_buffer should be sizeof(LG_LGID). |
| LG_A_CPWAITDONE | This call is part of the Fast Commit Consistency Point protocol. This call is issued by the Fast Commit thread in each FCT server to acknowledge the receipt of the LG_E_CPWAKEUP event. When ALL FCT servers have acknowledged the receipt of the LG_E_CPWAKEUP event, the Logging System signals the LG_E_ECP event to notify the RCP and ACP that this Consistency Point may now be completed. buffer should be an LG_LGID by reference, containing the logging system ID of this server. l_buffer should be sizeof(LG_LGID). |
| LG_A_FORCE_ABORT | This call allows each server to specify a handler which can be called to request that a transaction belonging to that server is to be aborted. That is, if the Logging System decides that it must abort the oldest transaction in the log file in order to reclaim space in the log file, then it will asks the owning server to perform the abort by calling this handler. Each server is required to provide the address of its handler after it calls LGopen and before it calls the first LGbegin for the first transaction. buffer should be an LG_LGID by reference, containing the logging system ID of this server. l_buffer should be the address of the handler, typecast to a longnat. That is, l_item is actually of type (VOID (*)()), but has been cast to longnat. Hopefully function pointers on your machine fit in longnats! |
| LG_A_DBRECOVER | This routine is called by the RCP when it completes recovery processing for a database which needed recovery. While recovery was in progress for this database, the Logging System may have been stalling various other processes which were waiting for this database to become available. These processes may now be allowed to continue. If none were waiting, then once the database recovery is complete, the database is automatically removed from the Logging System. buffer should be an LG_DBID by reference, containing the database ID of the database which has now been recovered. l_buffer should be sizeof(LG_DBID). |
| LG_A_OPENDB | This call is used by the RCP to acknowledge the first addition of a database to the Logging System. That is, the first time that a particular database is added to the Logging System (through LGadd), the RCP must e consulted, as it must determine whether the database is accessible and internally consistent. When it has so determined, it calls LGalter(LG_A_OPENDB) and the Logging System allows all users of the database to proceed. There is a slight catch here in that the RCP may decide that recovery is needed for this database. If this is the case, the users of the database cannot be allowed to proceed until the RCP completes recovery for the database and calls LGalter(LG_A_DBRECOVER). buffer should be an LG_DBID by reference, containing the database ID of the database which has now been opened. l_buffer should be sizeof(LG_DBID). |
| LG_A_CLOSEDB | This call is used by the RCP to acknowledge the last removal of a database from the Logging System. That is, the last time that a particular database is removed from the Logging System (through LGremove), the RCP must be consulted, as it must update its own tables and confirm that the database is internally consistent. When it has so determined, it calls LGalter(LG_A_CLOSEDB) and the Logging System removes all information about the database from its internal structures, reclaiming the space for use by other databases. If recovery is in progress, the database cannot be removed, however, until the RCP completes recovery for the database and calls LGalter(LG_A_DBRECOVER). buffer should be an LG_DBID by reference, containing the database ID of the database which has now been closed. l_buffer should be sizeof(LG_DBID). |
| LG_A_PURGEDB | This call is used by the ACP to notify the Logging System of the 'purge status' of a database. When a database is journalled, the ACP has the responsibility of archiving the log records for changes to that database off to the journal files. In addition to acknowledging the receipt of the LG_E_PURGEDB event, this call also informs the Logging System of the log address of the first journalled consistency point for this database. buffer should be an LG_PURGE structure by reference, containing the LG_DBID of the database being archived and the LG_LA of the first journalled consistency point. l_buffer should be sizeof(LG_PURGE). |
| LG_A_ACPOFFLINE | If the ACP shuts down due to an error, it calls LGalter(LG_A_ACPOFFLINE) to notify the Logging System that it shut down unwillingly. The Logging System then changes the global log status to indicate that the ACP should be restarted. buffer should be a longnat by reference, containing any non-zero value, to indicate that the ACP is now going offline. l_buffer should be sizeof(longnat). |
| LG_A_BCPDONE | This call is used by the RCP to indicate that a Consistency Point may now begin. This call has two different forms, because the actions taken by the Logging System depend on whether the BCP is starting or ending. LGalter(LG_A_BCPDONE) is called twice, once with a 0 value to indicate the logging system should stall all users other than the RCP until the RCP has written the set of Consistency Point log records, and a second time with a non-zero value to indicate that the RCP has completed the writing of the BCP records. The actions taken by the Logging System at BCP completion depend on whether there are any databases with Fast Commit being accessed. If there are FCT databases, then the Logging System proceeds with the Fast Commit Consistency Point Protocol by signalling the LG_E_CPFLUSH event to request that the dirty pages be flushed. If there are NOT any FCT databases, then the Logging System proceeds directly to request the completion of the Consistency Point by signalling the LG_E_ECP event. buffer should be a longnat by reference, containing 0 when the RCP acknowledges receipt of the LG_E_BCP event, and any non-zero value when the RCP completes the BCP processing. l_buffer should be sizeof(longnat). |
| LG_A_ECPDONE | This call is used by the RCP to communicate with the Logging System about the completion of a Consistency Point. Similarly to the LG_A_BCPDONE call, this call is made twice, once to acknowledge the receipt of the LG_E_ECP event, and a second time to notify the Logging System of the completion of the Consistency Point processing. The first LGalter(LG_A_ECPDONE) call should be made with a 0 value, and acknowledges receipt of the LG_E_ECP event. The second LGalter(LG_A_ECPDONE) should be made with a non-zero values, and indicates that the Logging System can now resume any users which were waiting for the Consistency Point to be completed. The Logging System may immediately begin the next Consistency Point if recovery was performed while this CP was being taken. The Logging System may also immediately begin the next Consistency Point if the log file filled up while this CP was being taken. Buffer should be a longnat by reference, containing 0 when the RCP acknowledges receipt of the LG_E_ECP event, and any non-zero value when the RCP completes the ECP processing. l_buffer should be sizeof(longnat). |
| LG_A_PASS_ABORT | This call is used by a server to transfer control of a failed transaction to the RCP. If a server attempts to abort one of its own transactions and encounters errors while doing so, it issues a LGalter(LG_A_PASS_ABORT) call to notify the Logging System that this transaction needs attention by the RCP. The Logging System will mark the transaction as needing recovery by the RCP and will signal the LG_E_RECOVER event so that the RCP can perform the recovery. buffer should be an LG_LXID by reference, containing the transaction id which is to be transferred to the RCP. l_buffer should be sizeof(LG_LXID). |
| LG_A_SERVER_ABORT | This call is used by the server to notify the Logging System that the server has begun aborting this transaction. This causes the Logging System NOT to choose this transaction for Force Abort processing, and also allows the Logging System to update its own tables to indicate that the transaction is being aborted. buffer should be an LG_LXID by reference, containing the transaction id which is now being aborted. l_buffer should be sizeof(LG_LXID). |
| LG_A_OFF_SERVER_ABORT | This call is used by the server to notify the Logging System that the server is abandoning its attempts to abort this transaction due to errors. This call allows the server to relinquish control over the transaction so that the RCP will be able to assume control over the transaction when it aborts it. That is, when a server aborts a transaction it should follow this protocol:
LGalter(LG_A_SERVER_ABORT) to indicate that it is starting to abort the transaction. If it fails to abort the transaction, next should come LGalter(LG_A_OFF_SERVER_ABORT) to allow the RCP to assume control over the transaction. After LG_A_OFF_SERVER_ABORT, the server should call LGalter(LG_A_PASS_ABORT) to notify the Logging System that the transaction should be given to the RCP for abort processing. &buffer should be an LG_LXID by reference, containing the transaction id which could not be aborted. l_buffer should be sizeof(LG_LXID). |
| LG_A_NODEID | This call is used by the VMS Cluster process to control the cluster nodeid. It probably should not be legal for LGalter, and should be usable only be LGCalter. |
| LG_A_CKPERROR | ACP had an error on dump file. |
| LG_A_SONLINE_PURGE | Server requests that ACP start an online purge. |
| LG_A_JCP_ADDR_SET | |
| LG_A_BUFMGR_ID | Servers using a shared buffer manager must call LGalter (LG_A_BUFMGR_ID) to register the id of the buffer manager they are using. This enables LG to track which servers are connected to common buffer managers. |
| LG_A_IDLE_SERVER | Added for fast commit. |
| LG_A_NOTIDLE_SERVER | Added for fast commit. |
| LG_A_DMU | Added to pass in some new parameters relating to handling logfull situations with DMU operations, which require additional reserved log space. |
| LG_A_RCPRECOVER | Added to allow the RCP to notify the logging system when it is performing recovery--this way the servers can tell (by examining the undocumented LGshow system status bits) whether the RCP is currently performing recovery or not. |
| LG_A_SBACKUP | Notify Logging System to start backup of a database. |
| LG_A_EBACKUP | Notify Logging System that CKPDB has completed backing up a database. |
| LG_A_RESUME | Notify Logging System to resume the exact pending on the stall queue. |
| LG_A_FBACKUP | Notify Logging System that ACP has moved needed data to ii_dump and ii_journal. |
| LG_A_DBACKUP | Notify Logging System to remove backup status from the idb data structure. |
| LG_A_WILLING_COMMIT | Alter the status of a transaction to WILLING COMMIT. |
| LG_A_CONTEXT | Restore the context of a transaction to WILLING COMMIT. |
| LG_A_REASSOC | Alter the state of a transaction to WAIT FOR THE RE-ASSOCIATION |
| LG_G_ABORT | Alter the state of a transaction to MANUAL ABORT. |
| LG_A_COMMIT | Alter the state of a transaction to MANUAL COMMIT. |
| LG_A_OWNER | Alter the owner of a transaction from RCP to a server. |
| LG_A_M_ABORT | Acknowledge the completion of a manual abort operation. |
| LG_A_M_COMMIT | Acknowledge the completion of a manual commit operation. |
Inputs:
| flag | Item number to alter. This field must have exactly one of the values listed above. |
| buffer | Pointer to buffer containing new value based on the flag setting. |
| l_buffer | Length of the buffer. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
| Many. See description for details. |
Definition:
STATUS LGalter(flag, buffer, l_buffer, sys_err) i4 flag; PTR buffer; i4 l_buffer; CL_SYS_ERR *sys_err;
LGbegin - begin a transaction
This routine informs the logging system to begin a transaction against a particular database. The logging system initializes information about the transaction and returns a transaction identifier which is used in calls to LGwrite.
The transaction can be marked as being journalled. This implies that the log record for this transaction should be copied to the journal file.
The transaction can also be marked as not-protected. A normal transaction is marked as protected. Protected means that on abnormal termination the transaction is considered to be outstanding and must be terminated by the recovery mechanism before the logging system will delete information about the transaction. A non-protected transaction has all of its logging system information deleted when the transaction is terminated abnormally.
A non-readonly transaction is inactive until it does its first call to LGwrite().
Inputs:
| flag | Either zero or a combination of | |
| LG_NOPROTECT | No consistent checks. | |
| LG_READONLY | Read only transactions. | |
| LG_JOURNAL | Journaled transaction. | |
| LG_NOABORT | Don't pick this transaction for force abort. | |
| db_id | Database Identifier. | |
| l_user_name | The length of the user name. | |
| user_name | The name of the user who starts the transaction. |
Outputs:
| tran_id | External transaction identifier. |
| lx_id | Internal transaction identifier. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| LG_EXCEED_LIMIT | A logging system internal limit has been exceeded. |
Definition:
STATUS LGbegin(flag, db_id, tran_id, lx_id, l_user_name, user_name, sys_err) i4 flag; LG_DBID db_id; LG_TRAN_ID *tran_id; LG_LXID *lx_id; i4 l_user_name; char *user_name; CL_ERR_DESC *sys_err;
LGclose - close log file
This routine will close the log file for the current process. If the caller specified LG_MASTER at LGopen time, then closing the file will affect all other processes that also have the file open. These other processes will be denied all further access to the logging system. This is the same as a shutdown call if the master is requesting a close. If a shutdown is in process, then all LG calls should be rejected with LG_BADPARAM.
Inputs:
| lg_id | The log indentifer for the file. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGclose(lg_id, sys_err) LG_LGID lg_id; CL_ERR_DESC *sys_err;
LGcluster - determine if you are running a VMSCluster
Can be called before LGinitialize. This routine returns a value not a DB_STATUS. The value must be zero for all environments other than VMS. The value can be non-zero for a VMS if the logical exists for the installation indicating that the installation is a cluster installation. The symbol is II_CLUSTER.
Inputs:
| None |
Outputs:
| None |
Returns:
| Zero | if the installation is NOT a VMSCluster |
| "positive number" | if the installation is a VMSCluster |
Definition:
i4 LGcluster()
LGcnode_info - Gives information on VMSCluster
Can be called before LGinitialize. This routine returns the name and the node id for a VMSCluster. This routine is only called if LGcluster returns a positive value indicating we are running on a cluster. Other environments must code this routine os a NULL routine that returns OK.
Inputs:
| name | buffer where name is to be stored |
| l_name | max size of 'name' buffer |
Outputs:
| name | VMSCluster name |
| sys_err | Operating system error value. |
Returns:
| OK | If information was available |
| other | system-specific error status. |
Definition:
STATUS LGcnode_info(name,l_name, sys_err) char *name; i4 l_name; CL_ERR_DESC *sys_err;
LGend - end transaction
This routine informs the logging system that this transaction is no longer active.
Inputs:
| lx_id | Transaction identifier. | |
| flag | 0, LG_ABORT_SESSION, LG_START or LG_RCP. | |
| 0 | normal termination of the transaction. i.e remove lxb from the logging system. | |
| LG_ABORT_SESSION | abort the transaction because the session where it belongs was aborted. The lxb_status of the transaction is marked as LXB_SESSION_ABORT and the recovery process is signaled to recover the transaction. | |
| LG_RCP | The transaction is termindated by the recovery process. Lxb, lpd, ldb and lpb are removed from the logging system if possible. | |
| LG_RCP or LG_SESSION_ABORT | The transaction is aborted by the recovery process. Lxb, lpd, and ldb are removed from the logging system if possible. The lpb where the transaction belongs to is removed only when the lpb is inactive. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGend(lx_id, flag, sys_err) LG_LXID lx_id; u_i4 flag; CL_ERR_DESC *sys_err;
LGerase - zero out the log file
This routine erases the log file to contain only null data. The file cannot be open when this call is made. Used only when LG_MASTER and LG_NOHEADER are passed to LGopen().
Inputs:
| lx_id | Transaction id. |
| bcnt | Buffer count in terms of block size. |
| bsize | block size. |
| force_init | Force erase the log file even if there are outstanding transactions. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGerase(lx_id, bcnt, bsize, force_init, sys_err) LG_LXID lx_id; i4 bcnt; i4 bsize; bool force_init; CL_ERR_DESC *sys_err;
LGevent - wait for logging event
This routine will wait for a specified logging system event to occur, or will return the current logging system events. If the flag is set to LG_NOWAIT, the current event mask is returned.
Inputs:
| flag | ||
| LG_NOWAIT | return immediately | |
| LG_INTRPTABLE | request interruptable | |
| lx_id | Logging system transaction id. | |
| event_mask | Mask of any event to wait for. Any set of the following values: | |
| LG_E_ARCHIVE | ||
| LG_E_BCP | ||
| LG_E_CPFLUSH | ||
| LG_E_ECP | ||
| LG_E_ECPDONE | ||
| LG_E_CPWAKEUP | ||
| LG_E_RECOVER | ||
| LG_E_LOGFULL | ||
| LG_E_IMM_SHUTDOWN | ||
| LG_E_ACP_SHUTDOWN | ||
| LG_E_FCSHUTDOWN | ||
| LG_E_PURGEDB | ||
| LG_E_ONLINE | ||
| LG_E_OPENDB | ||
| LG_E_CLOSEDB | ||
| LG_E_BACKUP_FAILURE | ||
| LG_E_1PURGE_ACTIVE | ||
| LG_E_2PURGE_COMPLETE | ||
| LG_E_M_ABORT | event to manually abort a transaction. | |
| LG_E_M_COMMIT | event to manually commit a transaction. |
Outputs:
| events | The current set of events. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGevent(flag, lx_id, event_mask, events, sys_err) u_i4 flag; LG_LXID lx_id; u_i4 event_mask; u_i4 *events; CL_ERR_DESC *sys_err;
LGforce - force log file
This routine guarantee's that a specific log record has been safely forced to disk. The flag arguments interpreted as follows:
| LG_HDR | Force the log file header to disk. |
| LG_LAST | Force the last log page of the logging system to disk. |
| 0 | Force the record denoted by the value in lga. |
- This assumes an immediate write. That is the call should not return until the data is on disk. If no transaction is specified (lx_id = 0) then this routine should try the operation nowait. That is the force should be started but not waited for. If the record has not already been written, set a timer to wait a little bit, then try the force nowait again. Repeat this until the record has been written. The time delay should be 100 milliseconds.
Inputs:
| flag | Optional LG_HDR, LG_LAST or 0. |
| lx_id | Transaction identifier. |
| lga | Optional pointer to specific log record to guarantee is on disk. |
Outputs:
| nlga | Pointer to location to receive new log address. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGforce(flag, lx_id, lga, nlga, sys_err) i4 flag; LG_LXID lx_id; LG_LA *lga; LG_LA *nlga; CL_ERR_DESC *sys_err;
LGinitialize - initialize the logging system
LGinitialize() must be called prior to any other LG calls except LGcluster().
Inputs:
| None |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGinitialize(sys_err) CL_ERR_DESC *sys_err;
LGopen - open log file
This routine opens the log file for the current process establishing a connection to the logger. If the caller specifies the LG_MASTER flag, then the log file can be initialized by the caller and the number of allocated blocks in the log file is returned. Otherwise if the file has not been initialized the caller will be returned an error.
The lg_id returned by this call is used in further calls to LGclose and LGadd.
Inputs:
| flag | This may be a combination of LG_MASTER, LG_ARCHIVER, LG_SLAVE, LG_FCT or LG_NOHEADER. |
| filename | Pointer to file name. |
| l_filename | Length of file name. |
Outputs:
| lg_id | Log file identifier. |
| blks | Number of blocks allocated if called by the master, dmfrcp. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| LG_EXCEED_LIMIT | A logging system internal limit has been exceeded. |
Definition:
STATUS LGopen(flag, filename, l_filename, lg_id, blks, sys_err) u_i4 flag; char *filename; u_i4 l_filename; LG_LGID *lg_id; i4 *blks; CL_ERR_DESC *sys_err;
LGposition - position for reading log file
This routine initializes and positions a read context buffer for a call to LGread().
When the position is LG_P_PAGE, the log addresses given have the lga_high field set to zero.
Positioning Constants:
The caller is given the following positioning options to start with:
| LG_P_PAGE | Position the file for access by page number. |
| LG_P_LGA | Position file by given log address. |
| LG_P_FIRST | Position to first record in log file. |
| LG_P_LAST | Position to last record in log file. |
| LG_P_TRANS | Position to last record for given transaction. |
Direction Constants:
| LG_D_FORWARD | Read forward for next object. |
| LG_D_BACKWARD | Read backward for next object. |
| LG_D_PREVIOUS | Read backward by previous log address. |
Inputs:
| lx_id | Transaction identifier. |
| position | Read position. One of LG_P_* above. |
| direction | Read direction. One of LG_D_* above. |
| lga | Optional log record address. |
| context | Pointer to context. |
| l_context | Length of context. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGposition(lx_id, position, direction, lga, context, l_context, sys_err) LG_LXID lx_id; i4 position; i4 direction; LG_LA *lga; PTR context; i4 l_context; CL_ERR_DESC *sys_err;
LGread - read record from log file
Reads the next record or page from the log file. The context that was initialized in a previous call to LGposition() contains the information used to read the next record. The log address of the record is returned, along with a pointer to the location of the stored record. If reading pages, then the record pointer actually points to a page. The LG_RECORD is part of the record returned as well as the record length.
Note, the context is allocated by the client at position time and it is up to the client to free it.
Inputs:
| lx_id | Transaction identifier. |
| context | Pointer to context. |
| l_context | Length of context. |
Outputs:
| record | Address of buffer containing record. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGread(lx_id, context, l_context, record, lga, lps, sys_err) LG_LXID lx_id; PTR context; i4 l_context; LG_RECORD **record; LG_LA *lga; i4 lps[2]; CL_ERR_DESC *sys_err;
LGremove - remove a database from the logging system
This routine deletes a database description from the logging system. The calling process is stating that it will not be logging to this database anymore. When the last process deletes a database the description is removed from the log system data structures.
When a transaction aborts abnormally, the database that it was processing against is also in a state of flux. Until the transaction can be resolved, the database information must be maintained.
Inputs:
| db_id | Database identifier. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGremove(db_id, sys_err) LG_DBID db_id; CL_ERR_DESC *sys_err;
LGshow - show log information
This routine allows the call to get information about the log system. The size of the return buffer must be at least as large as the size of the object being returned.
Inputs:
| flag | The information requested. Any one of the following constants: | |
| LG_S_STAT | Show the statistics information of the logging system. | |
| LG_A_HEADER | Show the content of the log file header. | |
| LG_S_DATABASE | Show the information of database(s) in the logging system. | |
| LG_N_DATABASE | Show the information of the next database in the logging system. | |
| LG_S_ADATABASE | Show the information of a particular database in the logging system. | |
| LG_S_TRANSACTION | Show the information of transaction(s) in the logging system. | |
| LG_N_TRANSACTION | Show the information of the next transaction in the logging system. | |
| LG_S_ATRANSACTION | Show the information of a particular transaction in the logging system. | |
| LG_S_PROCESS | Show the information of process(es) in the logging system. | |
| LG_S_APROCESS | Show the information of a particular process in the logging system. | |
| LG_N_PROCESS | Show the information of the next process in the logging system. | |
| LG_A_BOF | Show the beginning address of the log file. | |
| LG_A_EOF | Show the end of file log address. | |
| LG_A_CPA | Show the address of the last consistency point. | |
| LG_A_LDBS | Show the number of LBK entries. | |
| LG_S_FJNLCP | ||
| LG_S_LJNLCP | ||
| LG_S_LGSTS | ||
| LG_A_BCNT | ||
| LG_A_NODEID | ||
| LG_S_JNLDB | ||
| LG_S_PURJNLDB | ||
| LG_S_OPENDB | ||
| LG_S_CLOSEDB | ||
| LG_S_FORCE_ABORT | ||
| LG_S_STAMP | Return the time stamp of a transaction. | |
| LG_S_DIS_TRAN | Show if a distributed transaction already exists in the logging system. | |
| LG_S_M_COMMIT | Show the next transaction that needs to be manually committed. | |
| LG_A_CONTEXT | Show the context of a distributed transaction. | |
| LG_S_CDATABASE | Given lpd_id, return ldb_id. | |
| LG_S_LDATABASE | Given lpd_id, return ldb information. | |
| LG_S_BACKUP | Find out information about backup databases. | |
| LG_S_ABACKUP | Find out information about a specified backup database. | |
| buffer | Pointer to buffer to return value. | |
| l_buffer | Length of the buffer. |
Outputs:
| length | Resulting length. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGshow(flag, buffer, l_buffer, length, sys_err) i4 flag; PTR buffer; i4 l_buffer; i4 *length; CL_ERR_DESC *sys_err;
LGwrite - write record to log file
Writes a record to the log file. The log address for this record is returned. This address can be used to read a record from the log file, or it can be used in a call to LGforce to insure that the record has made it to disk safely. Setting the flag to LG_FORCE will guarantee that the log record has safely made it to disk before the LGwrite call completes. This can save a call to LGforce. Setting the flag to LG_LAST to indicate the last log record written for the current transactoin. This will remove the transaction context, lxb, from the logging system and thus save a call to LGend.
The log record is passed in as an array of LG_OBJECT structs. Each of these entries gives the size and ptr to a data block. When all of these data blocks are written contiguously, they make up a log record.
Inputs:
| flag | Zero or combination of the following: | |
| LG_FORCE | Current log buffer should be force to disk after writing this record. | |
| LG_LAST | This is the last record for this transaction and it should be removed from the logging system. | |
| LG_FIRST | This is the first record for this transaction. It is an error to write a non LG_FIRST record for a transaction marked LXB_INACTIVE. | |
| lx_id | Transaction identifier. | |
| num_objects | Number of entries in the objects array. | |
| objects | Array of size,data entries that make up log record. |
Outputs:
| lga | Log address assigned to record. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Side Effects:
Definition:
STATUS LGwrite(flag, lx_id, num_objects, objects, lga, sys_err) u_i4 flag; LG_LXID lx_id; i4 num_objects; LG_OBJECT *objects; LG_LA *lga; CL_ERR_DESC *sys_err;
LGCalter - alter log information for VMSCluster
Alter information stored in the log system. The type of information can be altered includes: The size of various tables, the size and number of log buffers, and the contents of the log file header.
Inputs:
| flag | Item to change. See LGalter() for the possible values. |
| item | Pointer to item. |
| l_item | Length of the item. |
Outputs:
| None |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGCalter(flag, item, l_item) u_i4 flag; PTR item; i4 l_item;
LGCclose - Close Named log file (VMSCluster Only)
Note: This routine should return OK for all environments except VMSCluster/VMS. This routine will close the log file.
Inputs:
| lg_id | The log indentifer for the file. |
Outputs:
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGCclose(lg_id, sys_err) LG_LGID lg_id; CL_ERR_DESC *sys_err;
LGCforce - force log file (VMSCluster only)
Note: This routine should return OK for all environments except VMSCluster/VMS. This routine guarantee's that a specific log record has been safely forced to disk.
This assumes an immediate write. That is the call should not return until the data is on disk.
Inputs:
| flag | Optional LG_HDR, LG_LAST or 0. | |
| LG_HDR | Force the log file header to disk. | |
| LG_LAST | Force the last log page of the logging system to disk. | |
| 0 | Force the record denoted by the value in lga. | |
| lga | Optional pointer to specific log record to guarantee is on disk. |
Outputs:
| nlga | Pointer to location to receive new log address. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS LGCforce(flag, lga, nlga, sys_err) i4 flag; LG_LA *lga; LG_LA *nlga; CL_ERR_DESC *sys_err;
LGCnode_names - Return node names for given node id's.
This routine is called with a bitmask of node id's. Each bit in the mask represents a cluster node id. The node name that is stored in the cluster config file is returned in the node_names buffer.
A node id can be obtained by calling LGshow(LG_A_NODEID). This returns a node number. To get the corresponding node name, the node number must be changed into a bitmask value:
- LGshow(LG_A_NODEID, &node_id, sizeof(node_id), &sys_err);
- node_mask = (1 << node_id);
- LGCnode_names(node_mask, node_names, sizeof(node_names), &sys_err);
The node names are formatted into the node_names buffer into a comma separated list. The list is null terminated. If the node_names buffer is too small, then all of the names will not be formatted. This routine is only called if LGcluster returns a positive value indicating we are running on a cluster. Other environments must code this routine as a NULL routine that returns OK.
Inputs:
| node_mask | Bitmask of node id's. |
| node_names | Buffer for node names. |
| length | Length of node_names buffer. |
Outputs:
| node_names | comma-separated list of node names. |
Returns:
| OK | |
| other | system-specific error status. |
Definitions:
STATUS LGCnode_names(node_mask, node_names, length, sys_err) i4 node_mask; char *node_names; i4 length; CL_SYS_ERR *sys_err;
LGCopen - open log file (for VMSCluster)
Note: This routine should return OK for all environments except VMSCluster/VMS. This routine opens the log file. The lg_id returned by this call is used in further calls to LGclose.
Inputs:
| flag | This may be a combination of LG_MASTER, LG_ARCHIVER, LG_SLAVE, LG_FCT or LG_NOHEADER. |
| filename | Pointer to file name. |
| l_filename | Length of file name. |
Outputs:
| lg_id | Log file identifier. |
| blks | Number of blocks allocated if called by the master, dmfrcp. |
| sys_err | Reason for error return status. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
| LG_EXCEED_LIMIT | A logging system internal limit has been exceeded. |
Definition:
STATUS LGCopen(flag, filename, l_filename, lg_id, blks, sys_err) u_i4 flag; char *filename; u_i4 l_filename; LG_LGID *lg_id; i4 *blks; CL_ERR_DESC *sys_err;
LGCposition - position for reading log file (VMSCluster)
Note: This routine should return OK for all environments except VMSCluster/VMS.
This routine initializes and positions a read context buffer for a call to LGread().
When the position is LG_P_PAGE, the log addresses given have the lga_high field set to zero.
Position constants:
| LG_P_PAGE | Position the file for access by page number. |
| LG_P_LGA</ |