DBUTLTY Reference

ddb provides a single utility that performs all operations for creating and maintaining your information base. The program name of the utility is DBUTLTY.
CA Datacom®/DB
 provides a single utility that performs all operations for creating and maintaining your information base. The program name of the utility is DBUTLTY.
This section contains an overview of the DBUTLTY operation and details of its command syntax. The DBUTLTY functions are presented in alphabetical order. Where a console command can be used to execute the function, the syntax for the 
CA Datacom®/DB
 portion of the console command is also provided.
Following the syntax information for each function is a guideline for the JCL to execute the function. Sample reports are also included with an explanation of the content of each report.
Security considerations for DBUTLTY include the following:
  • If you are using external security with 
    CA Datacom®/DB
    , you must have program authorization for the DBUTLTY function and the appropriate access authorization for the database resources being accessed by the DBUTLTY function.
  • In z/OS environments the Multi-User Facility (MUF) and the 
    CA Datacom®/DB
     Utility (DBUTLTY) must run authorized. The MUF is authorized when all JOBLIB/STEPLIBs are authorized. DBUTLTY can run some of the functions not APF authorized, but the intent of DBUTLTY is to run authorized.
This section is primarily intended for Database Administrators and systems programmers responsible for:
  • Administering the operations of the 
    CA Datacom®
    CA Ideal™ for CA Datacom®
  • Maintaining data integrity and accessibility
  • Installing and supporting the CA system software
  • Managing and implementing definitions
  • Performing routine maintenance tasks
Multiple Commands
You can usually perform more than one function with a single execution of DBUTLTY. Multiple commands can usually be in any order. Those functions that must be run alone are ACCT OPTION=CATALOG, ACCT OPTION=EDIT, DBTEST, and the MASSADD functions.
Prerequisite Commands
Some commands, such as DBTEST and RECOVERY, have prerequisite commands which set up the environment for them.
Syntax Check
To check the syntax of your commands, place the EDIT command first in the command stream. EDIT validates those commands that follow for syntax errors but does not execute the commands.
Every DBUTLTY execution produces a listing that contains the command exactly as entered followed by an alphabetic listing of all keywords and values entered, (except if DDOVER= is found on the statement, the data after the = (equal sign) is set to blanks to the next blank or comma). If you omitted a required keyword, that keyword prints with dashes indicating the maximum length of the keyword value and an error message. When multiple errors exist for one keyword parameter, only one error is displayed.
You also receive messages that explain any operational errors or provide explanatory information. Any error normally terminates execution of the utility immediately. However, the EDIT syntax check function scans all input data and displays all errors found during basic editing.
 Some edit errors are found in later editing and are not found with the EDIT function.
JCL Requirements for z/OS
If snapping is necessary, 
CA Datacom®/DB
 looks for a DD statement with a name of SNAPER. If it is not provided, 
CA Datacom®/DB
 dynamically allocates a DD statement for SNAPER with the value SYSOUT=*. Unless you want a specific SYSOUT class or other options, do not provide the DD statement. 
CA Datacom®/DB
 also dynamically allocates a SYSPRINT DD statement when needed if you do not provide it. The SYSPRINT DCB BLKSIZE and LRECL defaulted or are set based upon the DBSIDPR module assembled with the DBSYSID macro with keyword LINE=NEW or LINE=OLD. With LINE=NEW (the default) the BLKSIZE defaults to 0 if not set and the LRECL defaults to 133 if not set. With LINE=OLD, the BLKSIZE defaults to 121 if not set and the LRECL is set to 121, overriding any value provided. With LINE=OLD, if you specify a different block size in the JCL, it must be a multiple of 121. The exception to this is the COMM OPTION=SNAPCSA. This utility requires the SNAPER DD statement. During certain errors or on request, DBUTLTY can direct an address space snap to DD statement SNAPAS
, where 
 is a sequential number such as 01.
In addition to using the PGMDT option to select a specific date to get messages for newer programs, another option ss PGMMONTH=1. This parameter generates a PGMDT= of one month less than the current. For example, June becomes May and in January it becomes December of the previous year. Undocumented for a long time, this option is very useful in executions where the code frequently changes. You can see what has changed lately such as, in the CA development and QA. However, PGMMONTH=1 is not useful if you rarely apply maintenance and the maintenance was done prior to 30 days.
 The value 1 is not a variable Only the PGMMONTH=1 is valid.
Requirement to Run APF-Authorized, z/OS
We recommend (and DBUTLTY always expects to be) running authorized.
Certain DBUTLTY functions require that the job run APF-authorized. See the documentation on the individual functions to know if it requires APF-authorization.