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
- X
- XBSA
- 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.