Allows users to query, extract, verify, and delete backup images, logs, and load copy images that are saved using Tivoli® Storage Manager (TSM). Also allows users to grant and revoke access to objects on a TSM server.
On UNIX operating systems, this utility is located in the sqllib/adsm directory. On Windows operating systems, it is located in sqllib\bin.
Authorization
None
Required connection
None
Command syntax
>>-db2adutl--+-| db2-object-options |-----+-------------------->< '-| access-control-options |-' db2-object-options |--+-| QUERY-options |---+--------------------------------------> +-| EXTRACT-options |-+ +-| UPLOAD-options |--+ +-| DELETE-options |--+ '-| VERIFY-options |--' >--+---------------------------------+--------------------------> '-COMPRLIB--decompression-library-' >--+----------------------------------+--+---------+------------> '-COMPROPTS--decompression-options-' '-VERBOSE-' >--+-----------------------------+------------------------------> '-+-DATABASE-+--database_name-' '-DB-------' >--+-------------------------------------+----------------------> +-DBPARTITIONNUM--db-partition-number-+ '-LOGSTREAM--log-stream-number--------' >--+----------------------+--+--------------------+-------------> '-OPTIONS--tsm_options-' '-PASSWORD--password-' >--+---------------------+--+--------------+--------------------> '-NODENAME--node_name-' '-OWNER--owner-' >--+-------------------+----------------------------------------| '-WITHOUT PROMPTING-' QUERY-options |--QUERY--------------------------------------------------------> >--+-----------------------------------------------------------+--| +-+-+------------+--+----------------+-+--+---------------+-+ | | +-TABLESPACE-+ +-NONINCREMENTAL-+ | '-SHOW INACTIVE-' | | | '-FULL-------' +-INCREMENTAL----+ | | | | '-DELTA----------' | | | '-LOADCOPY---------------------------' | '-LOGS--+------------------------+--+----------+------------' '-BETWEEN--sn1--AND--sn2-' '-CHAIN--n-' EXTRACT-options |--EXTRACT------------------------------------------------------> >--+------------------------------------------------------------------------------------------------+--| +-+-+------------+--+----------------+-+--+---------------+--+--------+--+---------------------+-+ | | +-TABLESPACE-+ +-NONINCREMENTAL-+ | '-SHOW INACTIVE-' '-SUBSET-' '-TAKEN AT--timestamp-' | | | '-FULL-------' +-INCREMENTAL----+ | | | | '-DELTA----------' | | | '-LOADCOPY---------------------------' | '-LOGS--+------------------------+--+----------+-------------------------------------------------' '-BETWEEN--sn1--AND--sn2-' '-CHAIN--n-' UPLOAD-options |--UPLOAD--+------------+---------------------------------------> '-AND REMOVE-' >--+-------------------------------------+----------------------> '-IMAGES--+-------------------------+-' +-+-TAKEN AT--timestamp-+-+ | '-WITH LOGS-----------' | '-filename----------------' >--+----------------------------------------------------------------------------+--> '-LOGS--+------------------------+--+----------+--+------------------------+-' +-BETWEEN--sn1--AND--sn2-+ '-CHAIN--n-' | .-LOGARCHMETH1-. | '-OLDER THAN--sn1--------' '-FROM--+-LOGARCHMETH2-+-' >--+----------------------+--+-----------------------+----------> '-MGMTCLASS--mgmtclass-' '-DB2USER--db2_username-' >--+---------------------------+--------------------------------| '-DB2PASSWORD--db2_password-' DELETE-options |--DELETE-------------------------------------------------------> >--+----------------------------------------------------------------------------+--| +-+-+------------+--+----------------+-+--+--------------------------------+-+ | | +-TABLESPACE-+ +-NONINCREMENTAL-+ | +-KEEP--n------------------------+ | | | '-FULL-------' +-INCREMENTAL----+ | +-OLDER--+------+--+-timestamp-+-+ | | | '-DELTA----------' | | '-THAN-' '-n--days---' | | | '-LOADCOPY---------------------------' '-TAKEN AT--timestamp------------' | '-LOGS--+----------------------------+--+----------+-------------------------' '-+-BETWEEN--sn1--AND--sn2-+-' '-CHAIN--n-' '-OLDER THAN--sn1--------' VERIFY-options |--VERIFY-------------------------------------------------------> >--+--------------------------------------------------------------------------------------------------------+--| '-| verify-options |--+-+------------+--+----------------+-+--+---------------+--+---------------------+-' | +-TABLESPACE-+ +-NONINCREMENTAL-+ | '-SHOW INACTIVE-' '-TAKEN AT--timestamp-' | '-FULL-------' +-INCREMENTAL----+ | | '-DELTA----------' | '-LOADCOPY---------------------------' verify-options |--+-ALL-------------+------------------------------------------| +-CHECK-----------+ +-CHECKDMS--------+ +-DMS-------------+ +-HEADER----------+ +-LFH-------------+ +-TABLESPACES-----+ +-SGF-------------+ +-HEADERONLY------+ +-TABLESPACESONLY-+ +-SGFONLY---------+ +-OBJECT----------+ '-PAGECOUNT-------' access-control-options |--+------------------------------------------------------------------------------------------------+--> +-GRANT--+-ALL-------------+--ON--+-ALL-----------------+--FOR--+-DATABASE-+--database_name------+ | '-USER--user_name-' '-NODENAME--node_name-' '-DB-------' | +-REVOKE--+-ALL-------------+--ON--+-ALL-----------------+--FOR--+-ALL-------------------------+-+ | '-USER--user_name-' '-NODENAME--node_name-' '-+-DATABASE-+--database_name-' | | '-DB-------' | '-QUERYACCESS--FOR--+-ALL-------------------------+----------------------------------------------' '-+-DATABASE-+--database_name-' '-DB-------' >--+--------------------+---------------------------------------| '-PASSWORD--password-'
Command parameters
QUERY
Queries the TSM server for DB2® objects.
EXTRACT
Copies DB2 objects from the TSM server to the current directory on the local machine.
UPLOAD
Uploads backup images or archived logs stored on disk to the TSM server. You must specify the database name when this option is used.
DELETE
Either deactivates backup objects or deletes log archives on the TSM server.
VERIFY
Performs consistency checking on the backup copy that is on the server. This parameter causes the entire backup image to be transferred over the network.
ALL
Displays all available information.
CHECK
Displays results of checkbits and checksums.
CHECKDMS
Performs additional DMS and AS tablespace page validation. This option is not implied or enabled by the ALL option.
DMS
Displays information from headers of DMS table space data pages.
HEADER
Displays the media header information.
HEADERONLY
Displays the same information as HEADER but only reads the 4 K media header information from the beginning of the image. It does not validate the image.
LFH
Displays the log file header (LFH) data.
OBJECT
Displays detailed information from the object headers.
PAGECOUNT
Displays the number of pages of each object type found in the image.
SGF
Displays the automatic storage paths in the image.
SGFONLY
Displays only the automatic storage paths in the image but does not validate the image.
TABLESPACES
Displays the table space details, including container information, for the table spaces in the image.
TABLESPACESONLY
Displays the same information as TABLESPACES but does not validate the image.
TABLESPACE
Includes only table space backup images.
FULL
Includes only full database backup images.
NONINCREMENTAL
Includes only non-incremental backup images.
INCREMENTAL
Includes only incremental backup images.
DELTA
Includes only incremental delta backup images.
LOADCOPY
Includes only load copy images.
LOGS
Includes only log archive images
BETWEEN sn1 AND sn2
Specifies that the logs between log sequence number 1 and log sequence number 2 are to be used.
CHAIN n
Specifies the chain ID of the logs to be used.
SHOW INACTIVE
Includes backup objects that have been deactivated.
SUBSET
Extracts pages from an image to a file. To extract pages, you will need an input and an output file. The default input file is called extractPage.in. You can override the default input file name by setting the DB2LISTFILE environment variable to a full path. The format of the input file is as follows:
For SMS table spaces:
S <tbspID> <objID> <objType> <startPage> <numPages>Note:
For DMS table spaces:
D <tbspID> <objType> <startPage> <numPages>Note:
For log files:
L <log num> <startPos> <numPages>For other data (for example, initial data):
O <objType> <startPos> <numBytes>The default output file is extractPage.out. You can override the default output file name by setting the DB2EXTRACTFILE environment variable to a full path.
<objType> is only needed if verifying DMS load copy images.
<startPage> is an object page number that is pool-relative.
<startPage> is an object page number that is object-relative.
TAKEN AT timestamp
Specifies the timestamp of the backup image to be uploaded to TSM.
KEEP n
Deactivates all objects of the specified type except for the most recent n by time stamp.
OLDER THAN timestamp or n days
Specifies that objects with a time stamp earlier than timestamp or n days will be deactivated.
OLDER THAN sn1
Specifies that objects with a sequence number less than sn1 are to be deleted.
AND REMOVE
Specifies that backup images and log files are to be removed after they are successfully uploaded to TSM.
IMAGES
Specifies backup images that are to be uploaded to TSM. Even if you specify an image filename, db2adutl still attempts to query the history file. If a corresponding entry is found in the history file, db2adutl uploads the image only if the filename given matches the location in the history file. If a corresponding entry is not found, the image will be uploaded directly from the specified path and no history file update will be performed upon completion. If you specify the IMAGES with the UPLOAD option, you must specify the database name.
WITH LOGS
Specifies that archived logs are to be used along with the backup image.
filename
Specifies the image file name. If you do not specify this option, you must specify the database name.
LOGARCHMETH1 or LOGARCHMETH2
Specifies the archive location for the log files to be uploaded. LOGARCHMETH1 is the default.
MGMTCLASS mgmtclass
Specifies a TSM management class where the upload should occur
DB2USER db2_username
Specifies userid to be used for the DB2 connection that must be made to update the recovery history file.
DB2PASSWORD db2_password
Specifies password for userid to be used for the DB2 connection that must be made to update the recovery history file.
COMPRLIB decompression-library
Indicates the name of the library to be used to perform the decompression. The name must be a fully qualified path referring to a file on the server. If this parameter is not specified, DB2 will attempt to use the library stored in the image. If the backup was not compressed, the value of this parameter will be ignored. If the specified library cannot be loaded, the operation will fail.
COMPROPTS decompression-options
Describes a block of binary data that will be passed to the initialization routine in the decompression library. DB2 will pass this string directly from the client to the server, so any issues of byte reversal or code page conversion will have to be handled by the decompression library. If the first character of the data block is '@', the remainder of the data will be interpreted by DB2 as the name of a file residing on the server. DB2 will then replace the contents of the data block with the contents of this file and will pass this new value to the initialization routine instead. The maximum length for this string is 1024 bytes.
DATABASE database_name
Considers only those objects associated with the specified database name.
DBPARTITIONNUM db-partition-number
Considers only those objects created by the specified database partition number.
LOGSTREAM log-stream-number
Considers only those objects created by the specified logstream number.
OPTIONS "tsm_options"
Specifies options to be passed to the TSM server during the initialization of the TSM session. OPTIONS is passed to the to the TSM server exactly as it was entered, without the double quotation marks. When you use the OPTIONS parameter, the db2adutl command returns any errors generated by the TSM server.
PASSWORD password
Specifies the TSM client password for this node, if required. If a database is specified and the password is not provided, the value specified for the tsm_password database configuration parameter is passed to TSM; otherwise, no password is used.
NODENAME node_name
Considers only those images associated with a specific TSM node name.
Important: The NODENAME parameter and the OPTIONS parameter with the -asnodename value are not compatible and cannot be used at the same time. You should use the OPTIONS "-asnodename"parameter for TSM environments supporting proxy nodes configurations, and use the NODENAME parameter for other types of TSM configurations.
OWNER owner
Considers only those objects created by the specified owner.
Important: The OWNER parameter and the OPTIONS parameter with the -asnodename value are not compatible and cannot be used at the same time. You should use the OPTIONS "-asnodename"parameter for TSM environments supporting proxy nodes configurations, and use the OWNER parameter for other types of TSM configurations.
WITHOUT PROMPTING
The user is not prompted for verification before objects are deleted.
VERBOSE
Displays additional file information.
GRANT ALL | USER user_name
Adds access rights to the TSM files on the current TSM node to all users or to the users specified. Granting access to users gives them access for all current and future files related to the database specified.
REVOKE ALL | USER user_name
Removes access rights to the TSM files on the current TSM node from all users or to the users specified.
QUERYACCESS
Retrieves the current access list. A list of users and TSM nodes is displayed.
ON ALL | NODENAME node_name
Specifies the TSM node for which access rights will be changed.
FOR ALL | DATABASE database_name
Specifies the database to be considered.
Examples
The following example is sample output from the command db2 backup database rawsampl use tsm
Backup successful. The timestamp for this backup is : 20031209184503The following example is sample output from the command db2adutl query issued following the backup operation:
Query for database RAWSAMPL Retrieving FULL DATABASE BACKUP information. 1 Time: 20031209184403, Oldest log: S0000050.LOG, Sessions: 1 Retrieving INCREMENTAL DATABASE BACKUP information. No INCREMENTAL DATABASE BACKUP images found for RAWSAMPL Retrieving DELTA DATABASE BACKUP information. No DELTA DATABASE BACKUP images found for RAWSAMPL Retrieving TABLESPACE BACKUP information. No TABLESPACE BACKUP images found for RAWSAMPL Retrieving INCREMENTAL TABLESPACE BACKUP information. No INCREMENTAL TABLESPACE BACKUP images found for RAWSAMPL Retrieving DELTA TABLESPACE BACKUP information. No DELTA TABLESPACE BACKUP images found for RAWSAMPL Retrieving LOCAL COPY information. No LOCAL COPY images found for RAWSAMPL Retrieving log archive information. Log file: S0000050.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.46.13 Log file: S0000051.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.46.43 Log file: S0000052.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.47.12 Log file: S0000053.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.50.14 Log file: S0000054.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.50.56 Log file: S0000055.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.52.39The following example is sample output from the command db2adutl delete full taken at 20031209184503 db rawsampl
Query for database RAWSAMPL Retrieving FULL DATABASE BACKUP information. Taken at: 20031209184503 Log stream: 0 Sessions: 1 Do you want to delete this file (Y/N)? y Are you sure (Y/N)? y Retrieving INCREMENTAL DATABASE BACKUP information. No INCREMENTAL DATABASE BACKUP images found for RAWSAMPL Retrieving DELTA DATABASE BACKUP information. No DELTA DATABASE BACKUP images found for RAWSAMPLThe following example is sample output from the command db2adutl query issued following the operation that deleted the full backup image. Note the timestamp for the backup image.
Query for database RAWSAMPL Retrieving FULL DATABASE BACKUP information. 1 Time: 20031209184403, Oldest log: S0000050.LOG, Sessions: 1 Retrieving INCREMENTAL DATABASE BACKUP information. No INCREMENTAL DATABASE BACKUP images found for RAWSAMPL Retrieving DELTA DATABASE BACKUP information. No DELTA DATABASE BACKUP images found for RAWSAMPL Retrieving TABLESPACE BACKUP information. No TABLESPACE BACKUP images found for RAWSAMPL Retrieving INCREMENTAL TABLESPACE BACKUP information. No INCREMENTAL TABLESPACE BACKUP images found for RAWSAMPL Retrieving DELTA TABLESPACE BACKUP information. No DELTA TABLESPACE BACKUP images found for RAWSAMPL Retrieving LOCAL COPY information. No LOCAL COPY images found for RAWSAMPL Retrieving log archive information. Log file: S0000050.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.46.13 Log file: S0000051.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.46.43 Log file: S0000052.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.47.12 Log file: S0000053.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.50.14 Log file: S0000054.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.50.56 Log file: S0000055.LOG, Chain Num: 0, Log stream: 0, Taken at 2003-12-09-18.52.39The following example is sample output from the command db2adutl queryaccess for all
Node User Database Name type ------------------------------------------------------------------- bar2 jchisan sample B <all> <all> test B ------------------------------------------------------------------- Access Types: B - Backup images L - Logs A - bothThe following example is sample output that is displayed from a backup image of 3 members in a DB2 pureScale® environment.
BufAddr MemberNum PoolID Token Type Offset FileSize ObjectSize OrigSize Object Name -------- --------- ------ ----- ---- ------ -------- ---------- -------- ----------- 00000000: 0 0 0 19 0 268 268 0 "BACKUP.START.RECORD.MARKER" numTbspsInDB : 3 numTbspsInImg : 3 Total members : 3 Member numbers: 0,1,2
Usage notes
One parameter from each of the following groups can be used to restrict what backup images types are included in the operation:
Granularity:
FULL - include only database backup images.
TABLESPACE - include only table space backup images.
Cumulativeness:
NONINCREMENTAL - include only non-incremental backup images.
INCREMENTAL - include only incremental backup images.
DELTA - include only incremental delta backup images.
When using proxy nodes in TSM environments, in order to see the backup images or the log archives taken when the proxy node was used, you must specify the OPTIONS parameter with the shared TSM proxy node value using the asnodename option (for example OPTIONS "-asnodename=cluster1" ). The OPTIONS parameter is available starting in Version 9.8 Fix Pack 3 and later fix packs.
TSM grants delete access to the owner of the object or to the root user. It might restrict delete access to other users.
Each log file name has the following format:
S0******.LOG
Before Version 9.8 Fix Pack 3, the log files on the TSM server were written to the ./NODE0***/TESTLOG/C0******/ directory. In Version 9.8 Fix Pack 3 and later fix packs, the log files on the TSM server are written to the ./NODE****/LOGSTREAM****/C0******/ directory.
If the db2adutl utility encounters errors with TSM the actual TSM return code is displayed and the TSM documentation should be referred for troubleshooting steps.
