db2adutl - Managing DB2 objects within TSM command

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:

1. <startPage> is an object page number that is object-relative.

For DMS table spaces:

  D <tbspID> <objType> <startPage> <numPages>

Note:

1. <objType> is only needed if verifying DMS load copy images.
2. <startPage> is an object page number that is pool-relative.

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.

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.

Usage notes

One parameter from each of the following groups can be used to restrict what backup images types are included in the operation:

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.

S0******.LOG

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.