db2Prune API - Delete the history file entries or log files from the active log path

Deletes entries from the history file or log files from the active log path.

Authorization

One of the following authorities:

SYSADM
SYSCTRL
SYSMAINT
DBADM

Required connection

Database. To delete entries from the history file for any database other than the default database, a connection to the database must be established before calling this API.

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2Prune (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2PruneStruct
{
  char *piString;
  db2HistoryEID iEID;
  db2Uint32 iAction;
  db2Uint32 iOptions;
} db2PruneStruct;

SQL_API_RC SQL_API_FN
  db2gPrune (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gPruneStruct
{
  db2Uint32 iStringLen;
  char *piString;
  db2HistoryEID iEID;
  db2Uint32 iAction;
  db2Uint32 iOptions;
} db2gPruneStruct;

db2Prune API parameters

versionNumber: Input. Specifies the version and release level of the structure passed in as the second parameter, pParmStruct.
pParmStruct: Input. A pointer to the db2PruneStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2PruneStruct data structure parameters

piString

Input. A pointer to a string specifying a time stamp or a log sequence number (LSN). The time stamp or part of a time stamp (minimum yyyy, or year) is used to select records for deletion. All entries equal to or less than the time stamp will be deleted. A valid time stamp must be provided; a NULL parameter value is invalid.

This parameter can also be used to pass an LSN, so that inactive logs can be pruned.

iEID

Input. Specifies a unique identifier that can be used to prune a single entry from the history file.

iAction

Input. Specifies the type of action to be taken. Valid values (defined in db2ApiDf header file, located in the include directory) are:

DB2PRUNE_ACTION_HISTORY: Remove history file entries.
DB2PRUNE_ACTION_LOG: Remove log files from the active log path. This value is deprecated and might be removed in a future release. For more details, see PRUNE LOGFILE command is deprecated.

Note: This value is not supported in Db2® pureScale® environments.

iOptions

Input. Valid values (defined in db2ApiDf header file, located in the include directory) are:

DB2PRUNE_OPTION_FORCE: Force the removal of the last backup.
DB2PRUNE_OPTION_DELETE: Delete log files that are pruned from the history file.
If you set the auto_del_rec_obj database configuration parameter to ON, calling db2Prune with DB2PRUNE_OPTION_DELETE also causes the associated backup images and load copy images to be deleted.
DB2PRUNE_OPTION_LSNSTRING: Specify that the value of piString is an LSN, used when a caller action of DB2PRUNE_ACTION_LOG is specified.

Note: This value is not supported in Db2 pureScale environments.

db2gPruneStruct data structure specific parameters

iStringLen: Input. Specifies the length in bytes of piString.

Usage notes

You can use the DB2HISTORY_STATUS_DO_NOT_DELETE status to prevent key database history file entries from being pruned or deleted. You can set the status of database history file entries to DB2HISTORY_STATUS_DO_NOT_DELETE by running the UPDATE HISTORY command, the ADMIN_CMD procedure with UPDATE_HISTORY, or the db2HistoryUpdate API. For Db2 versions prior to 11.5.9, only log files, backup images, and load copy images can be marked with the DB2HISTORY_STATUS_DO_NOT_DELETE status.

If the latest full database backup is deleted from the media (in addition to being pruned from the history file), the user must ensure that all table spaces, including the catalog table space and the user table spaces, are backed up. Failure to do so may result in a database that cannot be recovered, or the loss of some portion of the user data in the database.

You can prune snapshot backup database history file entries using db2Prune, but you cannot delete the related physical recovery objects using the DB2PRUNE_OPTION_DELETE parameter. The only way to delete snapshot backup object is to use the db2acsutil command.

REXX API syntax

PRUNE RECOVERY HISTORY BEFORE :timestamp [WITH FORCE OPTION]

REXX API parameters

timestamp: A host variable containing a time stamp. All entries with time stamps equal to or less than the time stamp provided are deleted from the history file.
WITH FORCE OPTION: If specified, the history file will be pruned according to the time stamp specified, even if some entries from the most recent restore set are deleted from the file. If not specified, the most recent restore set will be kept, even if the time stamp is less than or equal to the time stamp specified as input.