Examples of the dbfhadmin Command Line Utility

CAS processes

Use the following commands to view the enterprise server processes that may be in error after an abnormal termination, and to recover such processes.

  • The following command lists the CAS processes still running for the svr-mydb database server instance:
    dbfhadmin -casprocess -list -usedb:svr-mydb

    The command will return a table, similar to that below, containing the name, host name, process ID, region name, last heartbeat time, and status for each enterprise server process

    Status  Host      Region    Region Id  H/B (s)  Name    PID    TID
    ------  ----      ------    ---------  -------  ----    ---    ---
    Ok      svr-mydb  ESDEMODB  ESDEMODB   0        cassi   1780   812
    Ok      svr-mydb  ESDEMODB  ESDEMODB   0        cassi   9140   28524
    Ok      svr-mydb  ESDEMODB  ESDEMODB   1        casmgr  10204  19392
    Ok      svr-mydb  ESDEMODB  ESDEMODB   0        cassi   19324  28792
    Ok      svr-mydb  ESDEMODB  ESDEMODB   2        castsc  19840  29036
    Ok      svr-mydb  ESDEMODB  ESDEMODB   1        cassi   26048  26300

    If a process has died, or has lost connectivity to the cross-region database for at least 10 seconds, the status indicates 'in doubt'. When 'in doubt', there could be associated resource locks (ENQs) outstanding.

  • The following command lists the CAS processes still running for the svr-mydb database server instance, on the host MYHOST:
    dbfhadmin -casprocess -list -usedb:svr-mydb -host:MYHOST
    Warning: Using the following commands to force DEQ'ing of resource locks should be used with caution. You need to ensure that the associated ES regions have actually stopped (and if they haven't, whether the process is still running; although, this is unlikely as ES recovery processing should have detected this), or that the cross-region database connection has been lost. The ENQs that get removed by this command will be those that are explicitly associated with the given process.
  • The following command recovers the CAS process (DEQs all ENQs) for process ID 12345, for the svr-mydb database server instance on svr-01:
    dbfhadmin -casprocess -recover -usedb:svr-mydb -host:svr-01 -pid:12345
    Note: Before the recovery process, the validity of the region/cross-region database is checked. If the check finds orphaned records, the recovery process is halted, and you are prompted to run the dbfhadmin -verify command to restore database integrity before continuing.
  • The following command recovers all CAS processes for the svr-mydb database server instance on svr-01:
    dbfhadmin -casprocess -recover -usedb:svr-mydb -host:svr-01
    Note: Before the recovery process, the validity of the region/cross-region database is checked. If the check finds orphaned records, the recovery process is halted, and you are prompted to run the dbfhadmin -verify command to restore database integrity before continuing.

Database creation

Use the following commands to create databases from a script file. Running these commands ahead of time ensures processing is not delayed when access is required and the databases are yet to be created.

  • The following command creates an ANSI-encoded MSSQL datastore database by running the mydb.sql script file:
    dbfhadmin -createdb -file:mydb.sql -type:datastore -provider:ss
  • The following command creates an EBCDIC-encoded Db2 datastore database by running the mydb.sql script file:
    dbfhadmin -createdb -file:mydb.sql -type:datastore -provider:db2 -ebcdic
  • The following command creates a PostgreSQL datastore database, on the MYREMOTEHOST server/port, by running the mypgdb.sql script file:
    dbfhadmin -createdb -file:mypgdb.sql -type:datastore -provider:pg -host:MYREMOTEHOST -port:33445
    [8]

Data files

Use the following commands to view data files still open after an abnormal termination of an enterprise server, and to recover/release them. Also, there are a number of commands to administer the column types of indexed keys.

  • The following command lists the data files still open for the VSAM datastore hosted on svr-mydb. For each file, there could be associated outstanding record locks:

    dbfhadmin -openfiles -list -datastore:sql://svr-mydb/VSAM -host:svr-01

    The command will return a table, similar to that below, containing the status, host name, file and folder name, and process ID:

    Status    Host        Name         Folder   PID
    ------    ----        ----         ------   ---
    Inactive  svr-mydb    catalog.dat  /ESDEMO  27180
    Inactive  svr-mydb    SPLDSN.dat   /ESDEMO  27180
    Inactive  svr-mydb    SPLJOB.dat   /ESDEMO  34132
    Inactive  svr-mydb    SPLMSG.dat   /ESDEMO  27180
    In doubt  svr-brs     catalog.dat  /ESDEMO  20300
    In doubt  svr-brs     SPLDSN.dat   /ESDEMO  20300
    In doubt  svr-brs     SPLJOB.dat   /ESDEMO  20300
    In doubt  svr-brs     SPLMSG.dat   /ESDEMO  20300
    Ok        svr-sdn     catalog.dat  /ESDEMO  34144
    Ok        svr-sdn     SPLDSN.dat   /ESDEMO  34144
    Warning: Caution should be exercised with the following two commands as files are forced closed. You should ensure that the process(es) on the associated host are no longer running before deciding to close files associated with them - refer to the Status column displayed as the result of the previous command:
    • OK: the file is open within an active process.
    • Inactive: the file had been opened by a process on the same machine as the one running dbfhadmin, but is no longer running.
    • In doubt: the file has been opened by a process on a remote machine. You should check these manually before deciding on a course of action.
  • The following command recovers the data files with an Inactive or In doubt status, by closing them and then removing any associated record locks for all processes, for the VSAM datastore hosted on svr-mydb:
    dbfhadmin -openfiles -recover -datastore:sql://svr-mydb/VSAM -host:svr-01

    Files with an Ok status are left untouched - to also close files with an Ok status, include the -force option. [19]

  • The following command is similar to that above but removes any associated record locks for the specified process (5983), for the VSAM datastore hosted on svr-mydb:
    dbfhadmin -openfiles -recover -datastore:sql://svr-mydb/VSAM -host:svr-01 -pid 5983
  • The following command specifies that the column type for the primary key of the MYFILE.dat file is alphanumeric, and the column type for the first alternate key is signed COMP-X:
    dbfhadmin -keytypes -add -file:sql://svr-mydb/VSAM/MYFILE.dat -types:AN,SCOMPX
  • The following command replaces existing key types for the specified data file:
    dbfhadmin -keytypes -add -replace -file:sql://svr-mydb/VSAM/MYFILE.dat -types:AN,SCOMPX
  • The following command deletes the key types that have been specified for MYFILE.dat, and the column types for indexed keys revert to type BINARY:
    dbfhadmin -keytypes -delete -file:sql://svr-mydb/VSAM/MYFILE.dat
  • The following command exports the list of key types for the VSAM datastore to the MYKEYTYPES.xml file:

    dbfhadmin -keytypes -export:MYKEYTYPES.xml -datastore:sql://svr-mydb/VSAM
  • The following command imports a list of key types to the VSAM datastore from the MYKEYTYPES.xml file:
    dbfhadmin -keytypes -import:MYKEYTYPES.xml -datastore:sql://svr-mydb/VSAM
  • The following command imports a list of key types to the VSAM datastore from the MYKEYTYPES.xml file, replacing any existing types that correspond to the ones in the file:
    dbfhadmin -keytypes -import:MYKEYTYPES.xml -datastore:sql://svr-mydb/VSAM -replace
  • The following command lists the key types set for each data file in the datastore:
    dbfhadmin -keytypes -list -datastore:sql://svr-mydb/VSAM

Script file creation

Use the following commands to create script files that can be used to create databases.

  • The following command creates a script file (createdb.sql) that can be run to create a Db2 cross-region database:
    dbfhadmin -script -type:crossregion -provider:db2 -file:createdb.sql
  • The following command creates a script file (createdb.sql) that can be run to create a Db2 cross-region database using the SYSTEM_1252_US Windows collating sequence:
    dbfhadmin -script -type:crossregion -provider:db2 -file:createdb.sql -collate:SYSTEM_1252_US
  • The following command creates a script file (createdb.sql) that can be run to create a PostgreSQL datastore called MYFILES:
    dbfhadmin -script -type:datastore -name:MYFILES -provider:pg -file:createdb.sql
  • The following command creates a script file (createdb.sql) that can be run to create an MSSQL region database called ESDEMO:
    dbfhadmin -script -type:region -name:ESDEMO -provider:ss -file:createdb.sql
  • The following command creates a script file (createinmydb.sql) that can be run to create a Db2 datastore called mySEQ, which will be stored in the existing Db2 database called masterSEQDB:
    dbfhadmin -script -type:datastore -name:mySEQ -provider:db2 -file:createinmydb.sql -existdb:masterSEQDB

Resource recovery

Use the following commands if you are receiving console log error messages that indicate resources are not available during startup. There is an automated recovery process that, in the event of a system failure, attempts to recover resources, but if not all were able to, you may be able to free them using these commands.

  • The following command lists each region associated with the DBHOST database server instance, the number of ENQs associated with processes and the number of ENQs that are associated with the region (that is, those which do not have process affinity).:
    dbfhadmin -region -list -usedb:DBHOST
  • The following command lists any region resources that are locked for the ESDEMO region, on the DBHOST database server instance:
    dbfhadmin -region -list -usedb:DBHOST -name:ESDEMO
  • Following on from the previous example, this command additionally displays the region name in hexadecimal:
    dbfhadmin -region -list -usedb:DBHOST -name:ESDEMO -hex
  • The following command releases the locks (that is, forces DEQ of those locks that do not have process affinity) for the ESDEMO region, on the DBHOST database server instance. Only run this command when the region is no longer running. :
    dbfhadmin -region -recover -usedb:DBHOST -name:ESDEMO

    To release locks that do have process affinity, use the -cassprocess -recover option above.

    Warning: Caution should be exercised with the next two commands. Only reset if, for example, you started an enterprise server region, but it failed because the region database was in use and you were absolutely certain that was not the case. To check, ensure that the process/program/host that was reported has having started the region was not actually running.
  • The following command displays the status of the ESDEMO region database, on the DBHOST database server instance:
    dbfhadmin -region -status -usedb:DBHOST -name:ESDEMO
  • The following command resets the status of the ESDEMO region database, on the DBHOST database server instance to "stopped"
    dbfhadmin -region -status -reset -usedb:DBHOST -name:ESDEMO

Upgrading datastores[8]

  • Use the following command to generate the script file upgradeds.sql, required to manually upgrade the VSAM datastore. If you omit the -file option, a file named upgrade_datastore_VSAM_db-type.sql is generated (db-type is determined by the settings in the database configuration file).
    dbfhadmin -upgrade -datastore:sql://localhost/VSAM -file:upgradeds.sql

    If the datastore does not need to be upgraded, dbfhadmin outputs ADM0073I Datastore '<datastore-url>' does not need to be upgraded, and no script file is created. When an upgrade is required, dbfhadmin outputs ADM0045I Creating SQL script file '<sql-script-name>'.

    The resulting script should be run as a user with sysadmin privileges using the sqlcmd (SQL Server), psql (PostgreSQL), or db2 (Db2) command-line tool.

Datastore integrity

Use the following commands to verify the integrity of a datastore, and if required, recover it from any integrity issues.

  • The following command runs a datastore integrity check of the VSAM datastore:
    dbfhadmin -verify -list -datastore:sql://localhost/VSAM

    Currently this check only detects orphaned record locks (that is, those record locks that exist without an associated file handle). Record locks would typically be orphaned if the associated file handle had been manually deleted from the database. When orphaned record locks are detected, dbfhadmin lists the associated file name for non-sequential files, or lists <Sequential files> for sequential files (the actual file name cannot be determined as a global record lock table is used for these files), with a count of the orphaned locks; for example:

    Orphaned record locks:  Name                Folder  Count
                            ----                ------   -----
                            SPLJOB.dat          /MyDir   3
                            <Sequential files>           1
    
  • The following command recovers the VSAM datastore from any orphaned record locks:
    dbfhadmin -verify -recover -datastore:sql://localhost/VSAM
  • The following command generates a diagnostic report names diags.txt, which contains details about ESDEMO region database (and associated cross-region database) in the DBHOST database:
    dbfhadmin -diags -usedb:DBHOST -name:ESDEMO -file diags.txt

See dbfhadmin Return Codes for a list of possible return codes used by the command: