EXTBKUP (Extract from Backup File)

The EXTBKUP function of DBUTLTY reads a backup file and writes extract of backup format data to the output data sets.
datacom151
The EXTBKUP function of DBUTLTY reads a backup file and writes extract of backup format data to the output data sets.
Prior to the execution of the EXTBKUP function, one or more FILEOUT functions must have been specified. FILEOUT functions define which tables are extracted by the EXTBKUP function. See FILEOUT (Define Output Data Sets).
A backup file contains records for one or more tables, based upon the area or database content, and optional control statements provided to the backup utility. The EXTBKUP function can extract one or more tables from a backup file, as specified by the user. The function can also expand compressed data on the backup to a new backup file with no compressed records.
EXTBKUP with FORMAT=EXTRACT generates data in expanded form. An extract file is not compressed and contains no
Datacom
control information. However, backup files always contain control information and may or may not contain compressed data. Compressed data, if present, can be in the Datacom form or in a user compression form, such as the Datacom Presspack. EXTBKUP uses the control information on the backup file to know what tables exist, the row size, and compression options.
The FILEOUT function (see FILEOUT (Define Output Data Sets)) is used to define one or more output data sets for EXTBKUP. If the table is empty, FILEOUT creates a valid null output data set.
EXTBKUP usually writes each data record as a fixed-length record in a fixed-block format.
Output files have a block size as specified in the JCL or a default of the operating system maximum, based upon device type. TAPE is blocked up to 32767, and DISK is blocked up to 27998.
When using the EXTBKUP function, an error occurs after one the following scenarios:
  • No FILEOUT statements were provided, or if
  • The input file is not a valid Datacom backup file produced by r10 or later, that is, backups produced by Datacom releases before r10 are not supported.
EXTBKUP reads the control records at the start of the backup and edits them to see if the backup represents all tables selected by the FILEOUT statements.
Tables are not required to have rows present.
The z/OS input concatenation of multiple individual backup files is supported by EXTBKUP.
Prior to the EXTBKUP function, one or more FILEOUT functions must have been specified to define which tables are extracted.
The following topics are discussed on this page:
When to Use EXTBKUP
Use the EXTBKUP function when you intend to process table information for use with the
Datacom Datadictionary
Record Migration Facility utility (DDRMFLM) in fixed-block format or for use outside the Datacom environment.
You can also use EXTBKUP FORMAT=BACKUP to create an uncompressed copy of the backup file.
How to Use EXTBKUP
The MUF must be active when you execute this command. Execute the EXTBKUP function using the following command format:
Extract from Backup File (z/OS)
►►─ EXTBKUP DDNAME=
dddddddd,
─┬─────────────────────────┬──────────────────────►◄ └─ FORMAT= ─┬─ EXTRACT ─┬─┘ └─ BACKUP ──┘
Command
  • EXTBKUP
    Invokes the function to extract data from a backup file in expanded form.
Required Keywords
  • DDNAME=
    Specifies the name of the input backup file.
    A DDNAME is not acceptable
    for sequential input or output files if it is a name reserved for a Datacom area. Names with the following patterns are therefore not acceptable for DDNAME=:
  • 3-byte names that end with XX, meaning they are reserved as either current or future Datacom control areas.
  • 6-byte names that end with what could be a database ID from 001 through 999.
  • 7-byte names that end with what could be a database ID from 1000 through 9999.
    The DDNAME= value is verified for acceptability to protect you from unintentionally causing data corruption. The DDNAME check is the default but optional. You can prevent the DDNAME check by using a DBSIDPR parameter (DBUTLTY_EDIT_DATA_SET=) for individual MUF environments. However, we recommend that you allow the DDNAME check.
    The data corruption risk involves not the DDNAME itself but the content of the data set. For example, suppose that you used the CXX DDNAME as the output of a backup. You then copied the CXX DD statement and changed the DDNAME of the copy to be acceptable, avoiding the DDNAME= error. The backup would, however, then overlay the CXX data set, which is not the intent of a backup.
    If you specify an unacceptable name for DDNAME=, message DB10059E is generated.
    We recommend that you allow DDNAME= check protection. You can, however, disable DDNAME= protection. To disable protection, assemble the DBSIDPR module used for this Datacom environment and specify NONE for the DBUTLTY_EDIT_DATA_SET= parameter. The default is DBUTLTY_EDIT_DATA_SET=FULL_1, which allows DDNAME= protection.
Optional Keywords
  • FORMAT=
    If you do not specify FORMAT= or if you specify FORMAT=EXTRACT, output is one or more extracted files, as was the case before Version 12.0 (in r11). If you specify FORMAT=BACKUP, the output is a single file in backup format with all records compressed by any option to be expanded. When FORMAT=BACKUP, you are required to have a previous single FILEOUT function to define the single output file, and in that FILEOUT function the keyword TABLE= must be set to *** (three asterisks) to specify that all tables be written to the output file.
    In support of FORMAT=, message DB13279E could be received if there is an edit error.
    VAR or NONE are not valid entries for FORMAT= in EXTBKUP and, if specified, are considered an error.
Example JCL (EXTBKUP)
The following example shows the command to extract the data table POL in area POL in database 1 to the output data set, POLOUT. The FILEOUT statement is shown immediately before the EXTBKUP line.
Use the following  example as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
//jobname See the note above and
JCL Requirements
.
// EXEC PGM=DBUTLTY,REGION=4M //STEPLIB See the note above and
JCL Requirements
.
//CXX DD DSN=cxx.data.set,DISP=SHR Directory data set //POLOUT DD DSN=db001.pol,DISP=SHR Output extract file //INFILE DD DSN=infile,DISP=SHR Input data set //SYSIN DD * Command Input FILEOUT DDNAME=POLOUT,TABLE=POL EXTBKUP DDNAME=INFILE /*
Sample Report
Following is a sample report page. For an example report header, see Sample Report Headers.
Information is reported about the AREA, TABLE, TABLEID, and number of records extracted. Zero records indicated that a null extract file was created because there were no records on the backup file. Each table specified in a FILEOUT statement (see FILEOUT (Define Output Data Sets)) must be found in the control records for the input backup file. If any of the specified tables are not found in the control records for the input backup file, a message in the report indicates the invalid table name, and the utility terminates as a failure.
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 FILEOUT DDNAME=POLOUT,TABLE=POL FUNCTION=FILEOUT DDNAME=POLOUT TABLE=POL
This page of the report shows the following:
  • The command exactly as entered.
  • An analysis of keywords encountered and expected. Any errors found are flagged with a note in the left margin.
  • Any messages related to syntax processing.
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 EXTBKUP DDNAME=INFILE FUNCTION=EXTBKUP DDNAME=INFILE
This page of the report shows the following:
  • The command exactly as entered.
  • An analysis of keywords encountered and expected. Any errors found are flagged with a note in the left margin.
  • Any messages related to syntax processing.
BACKUP FILE INFORMATION JOBNAME RUN UNIT DATE TIME CXXNAME DBID SEQ RECID AREA DBUTLTY 42,395 mm/dd/ccyy hh.mm.ss PRODCXX 1 NAT NO OUTPUT TABLE INFORMATION AREA TABLE ID RECORDS POL POL 4 4
This page of the report shows the following:
Confirmation that records were extracted from the requested table, as specified by the FILEOUT statement.