db2VendorGetNextObj API - Get next object on device

This API is called after a query has been set up (using the sqluvint API) to get the next object (image or archived log file) that matches the search criteria. Only one search for either images or log files can be set up at one time.

Authorization

None

Required connection

Database.

API include file

db2VendorApi.h

API and data structure syntax

int db2VendorGetNextObj ( void                        * vendorCB,
                          struct db2VendorQueryInfo   * queryInfo,
                          struct Return_code          * returnCode);

typedef struct db2VendorQueryInfo
{
   db2Uint64 sizeEstimate;
   db2Uint32 type;
   SQL_PDB_NODE_TYPE dbPartitionNum;
   db2Uint16 sequenceNum;
   char db2Instance[SQL_INSTNAME_SZ + 1];
   char dbname[SQL_DBNAME_SZ + 1];
   char dbalias[SQL_ALIAS_SZ + 1];
   char timestamp[SQLU_TIME_STAMP_LEN + 1];
   char filename[DB2VENDOR_MAX_FILENAME_SZ + 1];
   char owner[DB2VENDOR_MAX_OWNER_SZ + 1];
   char mgmtClass[DB2VENDOR_MAX_MGMTCLASS_SZ + 1];
   char oldestLogfile[DB2_LOGFILE_NAME_LEN + 1];
} db2VendorQueryInfo;

db2VendorGetNextObj API parameters

vendorCB: Input. Pointer to space allocated by the vendor library.
queryInfo: Output. Pointer to a db2VendorQueryInfo structure to be filled in by the vendor library.
returnCode: Output. The return code from the API call.

db2VendorQueryInfo data structure parameters

sizeEstimate: Specifies the estimated size of the object.
type: Specifies the image type if the object is a backup image.
dbPartitionNum: Specifies the number of the database partition that the object belongs to.
sequenceNum: Specifies the file extension for the backup image. Valid only if the object is a backup.
db2Instance: Specifies the name of the instance that the object belongs to.
dbname: Specifies the name of the database that the object belongs to.
dbalias: Specifies the alias of the database that the object belongs to.
timestamp: Specifies the time stamp used to identify the backup image. Valid only if the object is a backup image.
filename: Specifies the name of the object if the object is a load copy image or an archived log file.
owner: Specifies the owner of the object.
mgmtClass: Specifies the management class the object was stored under (used by TSM).
oldestLogfile: Specifies the oldest log file stored with a backup image.

Usage notes

Not all parameters will pertain to each object or each vendor. The mandatory parameters that need to be filled out are db2Instance, dbname, dbalias, timestamp (for images), filename (for logs and load copy images), owner, sequenceNum (for images) and dbPartitionNum. The remaining parameters will be left for the specific vendors to define. If a parameter does not pertain, then it should be initialized to "" for strings and 0 for numeric types.

Return codes

The following table lists all possible return codes for this API.

Table 1. db2VendorGetNextObj API return codes
Number	Return code	Explanation
2	SQLUV_COMM_ERROR	Communication error with device - Failure.
4	SQLUV_INV_ACTION	Invalid action requested or combination of input parameters results in an operation that is not possible - Failure.
5	SQLUV_NO_DEV_AVAIL	No device is available for use at the moment - Failure.
6	SQLUV_OBJ_NOT_FOUND	No object found - Failure.
12	SQLUV_INV_DEV_HANDLE	Invalid device handle - Failure.
14	SQLUV_END_OF_DATA	No more query objects to return - Success.
18	SQLUV_DEV_ERROR	Device error - Failure.
19	SQLUV_WARNING	Warning, see return code - Success.
21	SQLUV_MORE_DATA	More query objects to return - Success.
25	SQLUV_IO_ERROR	I/O error - Failure.
30	SQLUV_UNEXPECTED_ERROR	A severe error encountered - Failure.