db2ArchiveLog API - Archive the active log file

Closes and truncates the active log file for a recoverable database.

Authorization

One of the following authorities:
  • SYSADM
  • SYSCTRL
  • SYSMAINT
  • DBADM

Required connection

The db2ArchiveLog API automatically establishes a connection to the specified database. If a connection to the specified database already exists, then the db2ArchiveLog API returns an error.

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2ArchiveLog (
       db2Uint32 versionNumber,
       void * pDB2ArchiveLogStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2ArchiveLogStruct
{
   char *piDatabaseAlias;
   char *piUserName;
   char *piPassword;
   db2Uint16 iAllNodeFlag;
   db2Uint16 iNumNodes;
   SQL_PDB_NODE_TYPE *piNodeList;
   db2Uint32 iOptions;
} db2ArchiveLogStruct;

SQL_API_RC SQL_API_FN
  db2gArchiveLog (
       db2Uint32 versionNumber,
       void * pDB2ArchiveLogStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gArchiveLogStruct
{
   db2Uint32 iAliasLen;
   db2Uint32 iUserNameLen;
   db2Uint32 iPasswordLen;
   char *piDatabaseAlias;
   char *piUserName;
   char *piPassword;
   db2Uint16 iAllNodeFlag;
   db2Uint16 iNumNodes;
   SQL_PDB_NODE_TYPE *piNodeList;
   db2Uint32 iOptions;
} db2gArchiveLogStruct;

db2ArchiveLog API parameters

versionNumber
Input. Specifies the version and release level of the variable passed in as the second parameter, pDB2ArchiveLogStruct.
pDB2ArchiveLogStruct
Input. A pointer to the db2ArchiveLogStruct structure.
pSqlca
Output. A pointer to the sqlca structure.

db2ArchiveLogStruct data structure parameters

piDatabaseAlias
Input. A string containing the database alias (as cataloged in the system database directory) of the database for which the active log is to be archived.
piUserName
Input. A string containing the user name to be used when attempting a connection.
piPassword
Input. A string containing the password to be used when attempting a connection.
iAllNodeFlag
Applicable to partitioned database environment only. Input. Flag indicating whether the operation should apply to all nodes listed in the db2nodes.cfg file. Valid values are:
DB2ARCHIVELOG_NODE_LIST
Apply to nodes in a node list that is passed in piNodeList.
DB2ARCHIVELOG_ALL_NODES
Apply to all nodes. piNodeList should be NULL. This is the default value.
DB2ARCHIVELOG_ALL_EXCEPT
Apply to all nodes except those in the node list passed in piNodeList.
iNumNodes
Partitioned database environment only. Input. Specifies the number of nodes in the piNodeList array.
piNodeList
Partitioned database environment only. Input. A pointer to an array of node numbers against which to apply the archive log operation.
iOptions
Input. Reserved for future use.

db2gArchiveLogStruct data structure specific parameters

iAliasLen
Input. A 4-byte unsigned integer representing the length in bytes of the database alias.
iUserNameLen
Input. A 4-byte unsigned integer representing the length in bytes of the user name. Set to zero if no user name is used.
iPasswordLen
Input. A 4-byte unsigned integer representing the length in bytes of the password. Set to zero if no password is used.

Usage notes

  • The db2ArchiveLog API can be used to collect a complete set of log data, up to a known point. The log data can then be used to update a standby database.
  • If log data resides in the middle of a log file when the db2ArchiveLog API is run, then the log file is truncated. Logging continues on the next file.
  • The db2ArchiveLog API can be run only when the invoking application does not have a database connection to the specified database. This safeguard prevents a user from running the db2ArchiveLog API with uncommitted transactions. The db2ArchiveLog API does not forcibly commit the user's incomplete transactions. If the invoking application already has a database connection to the specified database, then the API returns an error. If another application has transactions in progress with the specified database when the db2ArchiveLog API is run, a slight performance degradation happens when the db2ArchiveLog API flushes the log buffer to disk. Any other transactions attempting to write log records to the buffer must wait until the flush is complete.
  • If the db2ArchiveLog API is used in a partitioned database environment, you can specify to run on all database partitions through the iAllNodeFlag parameter, or a subset of database partitions through the iNumNodes and piNodeList parameters.
  • Running the db2ArchiveLog API consumes a portion of the active log space, due to the truncation of the active log file. The active log space resumes its previous size when the truncated log becomes inactive. Frequent use of the db2ArchiveLog API can reduce the amount of the active log space available for transactions, and can generate an SQL0964C error if sufficient log space is unavailable.
  • The db2ArchiveLog API is asynchronous. It returns when the log is closed, making it available for archiving. The log is not archived immediately; A delay can happen between the time when the db2ArchiveLog API returns and the time when the log is archived. This delay is seen if you deactivate a database immediately after calling the db2ArchiveLog API, because the log might not archive until the next database activation.
  • The request is distributed to every member to which the database has access when the db2ArchiveLog API is used in a Db2® pureScale® environment. If a member is consistent, either online or offline, then the db2ArchiveLog API skips that member since the last log file of the member is already truncated from when the member last shut down cleanly. If an offline member is not consistent, then the db2ArchiveLog API waits for member crash recovery (MCR) to complete before truncation.