db2HistoryUpdate API - Update a database history records entry

Updates the location, device type, or comment in a database history records entry.

Note: This API is only supported in C, C++, or Java™ programming languages. It is no longer supported in COBOL, FORTRAN and REXX programming languages. You can issue a query to access database history records by using the DB_HISTORY administrative view.

Authorization

One of the following authorities:

SYSADM
SYSCTRL
SYSMAINT
DBADM

Required connection

Database. To update entries in the database history records for a 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
  db2HistoryUpdate (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2HistoryUpdateStruct
{
   char *piNewLocation;
   char *piNewDeviceType;
   char *piNewComment;
   char *piNewStatus;
   db2HistoryEID iEID;
} db2HistoryUpdateStruct;

typedef SQL_STRUCTURE db2HistoryEID
{
   SQL_PDB_NODE_TYPE ioNode;
   db2Uint32 ioHID;
} db2HistoryEID;

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

typedef SQL_STRUCTURE db2gHistoryUpdateStruct
{
   char *piNewLocation;
   char *piNewDeviceType;
   char *piNewComment;
   char *piNewStatus;
   db2Uint32 iNewLocationLen;
   db2Uint32 iNewDeviceLen;
   db2Uint32 iNewCommentLen;
   db2Uint32 iNewStatusLen;
   db2HistoryEID iEID;
} db2gHistoryUpdateStruct;

db2HistoryUpdate 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 db2HistoryUpdateStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2HistoryUpdateStruct data structure parameters

piNewLocation

Input. A pointer to a string specifying a new location for the backup, restore, or load copy image. Setting this parameter to NULL, or pointing to zero, leaves the value unchanged.

piNewDeviceType

Input. A pointer to a string specifying a new device type for storing the backup, restore, or load copy image. Setting this parameter to NULL, or pointing to zero, leaves the value unchanged. Valid device types are:

D: Disk
K: Diskette
T: Tape
F: Snapshot backup
A: Tivoli® Storage Manager
U: User exit
P: Pipe
N: Null device
Q: SQL statement
O: Other

piNewComment

Input. A pointer to a string specifying a new comment to describe the entry. The string cannot exceed 30 ASCII characters in length. Setting this parameter to NULL, or pointing to zero, leaves the comment unchanged.

piNewStatus

Input. A pointer to a string specifying a new status type for the entry. Setting this parameter to NULL, or pointing to zero, leaves the status unchanged. Valid values are:

A: Active. The backup image is on the active log chain. Most entries are active.
I: Inactive. Backup images that no longer correspond to the current log sequence, also called the current log chain are flagged as inactive.
E: Expired. Backup images that are no longer required because there are more than num_db_backups active images are flagged as expired.
D: Deleted. Backup images that are no longer available for recovery should be marked as having been deleted.
X: Do_not_delete. Recovery history entries that are marked as do not delete will not be pruned or deleted by calls to the PRUNE HISTORY command, running the ADMIN_CMD procedure with PRUNE HISTORY, calls to the db2Prune API, or automated recovery database history records pruning. You can use the do_not_delete status to protect key recovery file entries from being pruned and the recovery objects associated with them from being deleted.

iEID

Input. A unique identifier that can be used to update a specific entry in the database history records.

db2HistoryEID data structure parameters

ioNode: This parameter can be used as either an input or output parameter.
Indicates the node number.
ioHID: This parameter can be used as either an input or output parameter.
Indicates the local database history records entry ID.

db2gHistoryUpdateStruct data structure specific parameters

iNewLocationLen: Input. Specifies the length in bytes of the piNewLocation parameter.
iNewDeviceLen: Input. Specifies the length in bytes of the piNewDeviceType parameter.
iNewCommentLen: Input. Specifies the length in bytes of the piNewComment parameter.
iNewStatusLen: Input. Specifies the length in bytes of the piNewStatus parameter.

Usage notes

This is an update function, and all information before the change is replaced and cannot be re-created. These changes are not logged.

The primary purpose of the database history records is to record information, but the data contained in the history is used directly by automatic restore operations. During any restore where the AUTOMATIC option is specified, the history of backup images and their locations will be referenced and used by the restore utility to fulfill the automatic restore request. If the automatic restore function is to be used and backup images have been relocated since they were created, it is recommended that the database history record for those images be updated to reflect the current location. If the backup image location in the database history is not updated, automatic restore will not be able to locate the backup images, but manual restore commands can still be used successfully.