Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 1 Using TIBCO Object Service Broker Utilities : S6BBRULA (Recover TDS Table From Archive)

S6BBRULA (Recover TDS Table From Archive)
S6BBRULA is a TIBCO Object Service Broker recovery utility that restores one or more TDS tables from an archive (backup) file. You can:
When the data is recovered to a file, the file can be used as input to S6BBRTBL (batch load utility) or it can be reloaded as an import file. If loaded as an import file, you must account for null handling in your rules.
Refer to Appendix C, Null Handling for information on preserving null values in data fields. The unload and subsequent load assume specific values in the unloaded file that represent nulls.
Constraints
The following constraints apply:
If you use either of the batch unload utilities to unload data, you can reload the data by using the batch load utility or by treating the data as a TIBCO Object Service Broker import file. However, you cannot treat the data as an import file when binary or packed fields are to contain numeric syntax null values. When using the import server, you must use a special value string to represent nulls (null equivalent field values) in the unload file or revert to the oldnull option. Refer to Appendix C, Null Handling for more information.
If you are using FTP to transfer unloaded data between z/OS and Windows or Solaris, transfer the files in binary and specify the z/OS FTP LOCSITE subcommand with the RDW parameter.
Processing Overview
The process of unloading a table from archive has three phases. During the process, the archive file is scanned twice. The utility accepts a number of parameters to control both the program flow and storage utilization. The three phases of the table unload process are:
1.
Group index pages are written to a temporary data set.
2.
3.
The third phase extracts the data occurrences from the required pages and produces a work file that is then sorted into appropriate order based upon parameter values within the table name.
The output from the third phase is the RECOVER file.
Invocation
The following sections:
The sample situation assumes that one table on segment 1 is lost or corrupted. If you are unloading all the table instances from a parameterized table, the process would be the same. For information about recovering particular table instances, review the sample and refer to “Selecting Records During Processing”.
Before using S6BBRULA, ensure that the backup level is appropriate for your requirements. In the sample situation, S6BBRULA is used to recover the table from the most recent backup. This backup can be merged with outstanding journals to create a more current backup. For more information about this procedure, refer to TIBCO Object Service Broker for z/OS Managing Backup and Recovery.
Step 1: Define the Table to Recover
To define the tables that you want to recover, code control cards as described in this section. Your definition must match that of the table when it was archived. You can use the BATCHUNLD_CARDS utility, which provides a screen interface for you to specify the table or table instances to unload from the archive, and creates the control cards and selection file for you. Refer to the documentation for BATCHUNLD_CARDS in TIBCO Object Service Broker Shareable Tools.
If you cannot use BATCHUNLD_CARDS because TIBCO Object Service Broker is not available, you must define the control cards manually according to the format described below.
Each record in the control cards is 80 characters long and has a fixed format. The fields are spaced apart to conform to the layout used by a number of TIBCO Object Service Broker batch utilities such as the batch load utility (S6BBRTBL).
Table Control Card
The first card in the control card file is a table control card. This control card specifies the number of tables specified in the control card file and must be the first entry in the file. The layout is as follows:
Table Definition Cards
These cards define each of the tables to be recovered as follows:
Offset of parameter/field in output text (the 4-byte variable length and 16-byte table name are excluded from the offset).
Sample Table Definition
The layout you are describing must match the definition contained in the backup file. The following contains a description of the table definition of the sample table:

 
Table Definition for : SCRIPTCOMMANDS
Field Definitions
Field Name Semantic Type Syntax Len Dec Key Order Rqd
------------- ------------- --------- --- - -- ---- ----- ---
COMMAND S String C Fix Char 16 0 P
RULE I Identifier C Fix Char 16 0
USAGE S String C Fix Char 20 0
PURPOSE S String V Var Char 35 0

 
Sample Control Cards
The following illustrates a sample control card file for this table:

 
* 0002
H 000 T SCRIPTCOMMANDS 000 004
H 000 F COMMAND S C 016 000
H 000 F RULE I C 016 000
H 000 F USAGE S C 020 000
H 000 F PURPOSE S V 035 000
H 000 R

 
Step 2: Customize the Sample JCL
To customize the JCL, specify input files, output files, and runtime parameters. The files and runtime parameters used by S6BBRULA are described below.
Files Used by S6BBRULA
Files used by S6BBRULA are as follows:
SYSPRINT type file. Output execution audit trail including table definitions and summaries for each processing step.
Fixed block 4096 byte. Output/input file retains group index page images between pass 1 and 2. This is a temporary file that you do not need to retain. VIO type device is recommended.
Variable block, 4100 bytes maximum. The output/input file retains raw extracted data with sequencing fields and the table name at the beginning of the record. This file is used as input to the internal sort that orders the entries and removes the sequencing information. This is a temporary file that you do not need to retain afterwards. VIO type device is recommended.
Variable block, 4100 bytes maximum. This is the final output file with extracted data in proper sequence for loading.
There are additional files if you choose to break during execution. These files and the necessary runtime parameters are described in Selecting Records During Processing.
Runtime Parameters
There are two runtime parameters that you must specify. These are:
The segment number of the Pagestore that stores the tables to be unloaded. If omitted, the default is segment 0.
The total number of pages contained in a specified segment, including both allocated and unallocated pages. It is better to overestimate the size than underestimate it.
Note  Do not include commas in the parameter value (for example, specify 100000).
There are additional runtime parameters that you can leave at their default values unless error messages indicate that a particular value should be modified. The additional parameters are listed in Runtime Storage Parameters.
Sample JCL
The S6BBRULA member of the JCL data set distributed with TIBCO Object Service Broker contains sample JCL required to run this utility.
This sample is provided as a reference only; modify the JCL for your needs.
Files and parameters used are as described above.
The JCL includes the following entries:
Step 3: Run S6BBRULA and Review Results
Submit the JCL and review the execution report. Here is a sample execution report:

 
  S6BBRULA TABLE RECOVERY ARCHIVE EXTRACT DATE 2009 MAR 17 TIME 1
PROCESSING SEGMENT 1
REQUIREMENT TYPE % OF PAGES PAGE ESTIMATES MEMORY REQUIRED
DATA 85 8,500 170,000
PRIMARY INDEX 3 300 2,400
GROUP INDEX 10 1,000 20,000
GROUP INDEX INDEX 2 200 1,600
TABLE INSTANCE 1 400 105,600
PAGE STORE/TOTAL ** 10,000 299,600
  S6BBRULA TABLE RECOVERY ARCHIVE EXTRACT DATE 2009 MAR 17 TIME 1
TABLE NUMBER 0 TABLE NAME SCRIPTCOMMANDS
FIELDS FOR TABLE - SCRIPTCOMMANDS
NAME TYPE SYNTAX LENGTH DECIMAL OFFSET
**************** * * *** *** ****
COMMAND S C 16 0 0
RULE I C 16 0 16
USAGE S C 20 0 32
PURPOSE S V 35 0 52
  S6BBRULA TABLE RECOVERY ARCHIVE EXTRACT DATE 2009 MAR 17 TIME 1
S6BBA011I PASS ONE PROCESSING INITIATED
S6BBA012I PASS ONE; 000008104 RECORDS READ, 000008104 ACCEPTED,
S6BBA013I PASS TWO PROCESSING INITIATED
S6BBA014I GIX TABLE COMPRESSION COMPLETE INPUT=00043767, OUTPUT=00000071
S6BBA015I DATA TABLE COMPRESSION COMPLETE INPUT=00043839, OUTPUT=00000072
S6BBA019I PASS TWO; GROUP INDEX PAGES READ 000000000, 000000000 PROCESSED
S6BBA020I PASS THREE PROCESSING INITIATED
S6BBA021I PASS THREE; 000000445 RECORDS READ, 000000445 ACCEPTED,
S6BBA022I SCRIPTCOMMANDS 0000000000000055 RECORDS UNLOADED
RECOVERY START TIME 12:01:37, END TIME 12:01:46

 
Browse the RECOVER data set.
Records in the RECOVER data set store the table name as a 16-byte header. You must account for this 16-byte header when you describe the record format to the batch load utility (S6BBRTBL).
Selecting Records During Processing
If you do not need to recover all the instances of a parameterized table, you can select specific parameter values.
Parameterized Table Example
The following illustrates the definition of an example parameterized table. The sample table is parameterized by USERID and is used to explain record selection:

 
COMMAND==> TABLE DEFINITION
Table:EMPLOYEE Type:TDS Unit:PER IDgen:N
Parameter Name Typ Syn Len Dec Reference ’ Event Rule Typ Acc
--------------- - - --- -- -------------- ’---------------- - -
_ USERID I C 16 0 ’
_ ’
Field Name Typ Syn Len Dec Key Ord Rqd Default Reference
--------------- - - ---- -- - - - ----------- ---------------
_ EMPNO I P 3 0 P
_ LNAME S C 22 0
_ POSITION S C 14 0
_ MGR# I P 3 0 MANAGER
_ DEPTNO I B 2 0
_ SALARY Q P 4 2 0.00
_ HIREDATE D B 4 0
_ ADDRESS S V 38 0
_ CITY S C 20 0
_ PROV S C 3 0
_ P_CODE S C 7 0

 
Sample Control Cards
The following example shows the control cards for this table:

 
* 001
H 000 T EMPLOYEE 001 011
H 000 P USERID I C 016 000
H 000 F EMPNO I P 003 000
H 000 F LNAME S C 022 000
H 000 F POSITION S C 014 000
H 000 F MGR# I P 003 000
H 000 F DEPTNO I B 002 000
H 000 F SALARY Q P 004 002
H 000 F HIREDATE D B 004 000
H 000 F ADDRESS S V 038 000
H 000 F CITY S C 020 000
H 000 F PROV S C 003 000
H 000 F P_CODE S C 007 000

 
Selecting Parameter Values
Parameter values can be selected internally or externally.
Internal Selection
If you know the parameter values that you want to select before you initiate S6BBRULA execution, you can use a selection file to specify table instances.
External Selection
To select specific parameter value sets externally, you can run S6BBRULA in Break mode to halt processing and allow you to select parameter values according to your criteria. This procedure is described in Defining Table Instances Externally.
Additional Selection Files
Additional files are also required for selection:
Fixed block, 530 bytes. This file contains selection criteria for the parameter values. It is required for internal parameter value selection only.
Variable block, maximum length 40. This output file is created in phase 2 of processing if the BREAK parameter is specified. It retains data page header and requirement information.
Variable block, maximum length 300. This output file is created in phase 2 of processing if the BREAK parameter is specified. It retains parameter value information so that selection can be done to eliminate unwanted table instances of a parameterized table.
Variable block, maximum length 40. This input file is read at initialization when in CONTINUE processing mode (refer to BRKDATA).
Variable block, maximum length 300. This input file is read at initialization when in CONTINUE processing mode (refer to BRKPVS).
Defining Table Instances Internally
To define files internally, the selection criteria in a SELECT file must be 530 bytes. This can be generated using the BATCHUNLD_CARDS utility. For more information, refer to the documentation for BATCHUNLD_CARDS in TIBCO Object Service Broker Shareable Tools.
If you cannot use BATCHUNLD_CARDS, you must define the selection file manually in the following fixed format:
The first record in the selection file is a control record. The control record must have a table name of “****************” (16 asterisks). The first four bytes of the Parm 1 field must contain a count of the number of records in the SELECT file, excluding the control record. The following illustrates an example of the selection file for this table:

 
**************** 0001
EMPLOYEE I=EDUC

 
Defining Table Instances Externally
The alternate way to extract table instances is to define the instances externally by executing S6BBRULA in Break and Continue modes. To halt S6BBRULA processing, you can specify a runtime parameter of BREAK. To continue with the unload after doing some external processing, you run S6BBRULA with a runtime parameter of CONTINUE. The parameters are described here:
(Optional) Halt processing after all the required data pages have been tagged and data chain and parameter value files have been produced. To eliminate table instances of specific parameter values you do not want to unload, review the parameter value file (BRKPVS).
Break Execution JCL
The BRKEXEC member of the JCL data set distributed with TIBCO Object Service Broker contains sample JCL required to run the table unload program, halting it after internal parameter value selection (PVS) and data page selection.
This sample is provided as a reference only; modify the JCL for your needs.
The BRKPVS data set contains a header record and a record for every table instance extracted from the archive. The header record contains a count of the number of parameter value records. You can edit this file and delete the parameter value records for the table instances you do not want to recover.
Do not edit the header record. We recommend that you make a backup copy of the BRKPVS file before you edit it and use it as input to the Continue process as CONTDATA and CONTPVS.
Continue Execution JCL
The CONTEXEC member of the JCL data set distributed with TIBCO Object Service Broker contains sample JCL required to continue the table unload process after a break run.
This sample is provided as a reference only; modify the JCL for your needs.
Runtime Storage Parameters
The following runtime parameters are used in the calculation and distribution of allocated storage. These parameters allow you to tune the execution of S6BBRULA. With the exception of the PAGES parameter, all these storage parameters should be left at their default values unless a previous execution failure indicates that modification is necessary.
Note  Do not embed commas in the parameter value (for example, specify 100000).
Note  If the tables being unloaded is not parameterized, the GIX percentage can be zero.
Note  If the tables being unloaded is not parameterized, the HIX percentage can be zero.
Storage requirement = total pages * gix% * pvs% * average GIX entries per page (100) * entry length (264).
Note  If the tables being unloaded is not parameterized, the PVS percentage can be set to zero.
Step 4: Restore the Table Under a New Name and Segment
The following steps describe how to restore an archived file to a new name or segment, or both. This example uses the EMPLOYEE table that resides on segment 2 and restores it as EMPLOYEE_RESTORE on segment 3.
1.
2.
3.
4.
5.
These procedures can have an adverse effect on your continuous backup. When possible, take full backups before attempting to restore files from an archive. Refer to TIBCO Object Service Broker for z/OS Managing Backup and Recovery for more information.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved