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


Chapter 1 Using TIBCO Object Service Broker Utilities : hrnbrula (Batch Unload from Archive)

hrnbrula (Batch Unload from Archive)
Syntax
hrnbrula -C controlfile [arguments] archivefile
Platforms
Windows, Solaris
Description
the hrnbrula utility is a TIBCO Object Service Broker recovery utility that restores one or more TDS tables from an archive file. You can:
Phases of hrnbrula Processing
There are three phases to the unload table from archive process. During the process, the archive file is scanned twice. The utility accepts a number of arguments to control both the program flow and storage utilization. The three phases of the table unload process are:
Extracts the data occurrences from the required pages and produces a work file that is sorted into appropriate order based on parameter values within the table name.
Arguments
 
-A auditreport
The file to which the audit report is written. This entry is optional. If omitted, the report is written to the default file stdout.
-C controlfile
-d datapage%
Data page %. This number indicates the approximate % of used pages that are D pages. The entry is optional and has a default of 85%.
-g group%
Group index page %. Approximate % of used segment pages that are G pages. This is an optional entry and has a default of 10%.
-h groupindex%
Group-index index page %. Approximate % of used segment pages that are H pages. This is an optional entry and has a default of 2%.
-i dataindex%
Data Index page %. Approximate % of used segment pages that are I pages. This is an optional entry and has a default of 3%.
-M 3-char-prefix
This entry indicates a separate file is required for each table or instance. You must supply either an ‑M 3 character prefix or a ‑U unloadfile argument.
-n buffer#
-p pages#
Approximate number of used pages in segment. This optional entry has a default of 100000. In cases where this number is unknown, enter the total number of pages in the segment. The default number is usually sufficient. If not, it is better to overestimate.
-S selectionfile
Full path of selection control file. This entry is required only if selected parameter instances of a table are being recovered.
-s segment#
-U unloadfile
The full path and name of the unload file. You must supply either a ‑U unloadfile or an ‑M 3 character prefix argument.
-v parameter%
Parameter value %. Approximate % of G pages participating in the recovery. This optional entry has a default of 1%.
-W workdir
 
Files
controlfile
A file containing the control information describing the output file and the table to unload. Create this file using the BATCHUNLD_CARDS tool.
archivefile
The name of the archive file.
Environment Variable
UNICODEDIR
Set this to indicate the directory that contains the Unicode configuration files, for example, %OS_ROOT%\database\UNICODEDIR in Windows or ${OS_ROOT}/database/UNICODEDIR in Solaris. For more information, refer to TIBCO Object Service Broker for Open Systems Installing and Operating.
Constraints
Control File
You must have a correctly formatted control file, describing the format of your table (which is also the format of your output file), the table name to be unloaded, and other relevant control information. This information can be prepared using the BATCHUNLD_CARDS tool or with an ASCII editor like Notepad or vi. For more information, refer to TIBCO Object Service Broker Shareable Tools.
The complete file must be defined so that the hrnbrula utility can determine the size of the maximum record.
Selection File
If the table to be unloaded is parameterized and you want to unload only selected instances, you must have a correctly formatted selection file (ASCII text) constructed using the online BATCHUNLD_CARDS tool. This selection file indicates which parameter instances you want to include or exclude.
Parameterized Table Instances
Tables must not be empty. Parameterized table instances selected for inclusion in the unloaded file by using the equals (=) relational operator must exist in the table.
Reloading the Data
If you use one of the Batch Unload utilities to unload data, reload the data by using the Batch Load utility. You cannot reload the data using the interactive LOAD tool.
EBCDIC Format
The output file is created in EBCDIC (z/OS variable) format.
Variable Block (VB) means that each block is prefixed by a four-byte Block Descriptor Word (BDW) containing the length of the data in the block, including the four-byte BDW itself. For example, the BDW for a 256-byte block of data would appear as follows:
where the first two bytes contain the length followed by two bytes containing zeros.
Within each block, each record has a Record Descriptor Word (RDW) with exactly the same format as the BDW. If a record contained 20 bytes of data, the RDW would appear as follows:
where the first two bytes contain the length, followed by two bytes containing zeros. If this record is the first in the block, the beginning of the block would appear as follows:
followed by the first record (of 20 bytes).
Null-equivalent Values
Numeric syntax fields (binary and packed decimal) have a null-equivalent value, which is defined as the lowest possible value that the field can hold. Null values in the input file are preserved using the following default behavior:
Packed decimal fields use the alternative negative sign (X’B’), which means that the lowest possible value can still be used in tables. In a file where the default null-equivalent value is used, the following values must not be used:
The default values can be overridden to use a user-defined value, the highest possible value, or no null-equivalence permitted.
You cannot represent a floating point null in fixed format. When a floating point null is unloaded using the hrnbrula utility, the hrnbrulb (Batch Unload (Offline)) utility, or the hrnbrulh (Batch Unload (Online)) utility, it is unloaded as true zero. Therefore, when floating point nulls are reloaded using the hrnbrtbl (Batch Load) utility, they are loaded as a zero.
Using FTP to Transfer Unloaded Data
If you are using FTP to transfer unloaded data between z/OS and Windows or Solaris, you must reformat the unloaded data using the S6BBRFRU z/OS utility before it can be used by TIBCO Object Service Broker. Refer to TIBCO Object Service Broker for z/OS Utilities for more information on the S6BBRFRU utility.
Examples
The following examples illustrate the use of the hrnbrula utility:
Windows
hrnbrula -A audit.report -C c:\cntl\control.file
         -S c:\brula\select.file -s 10 -n 40 -W c:\tmp
         -M c:\brula\TBL c:\archives\seg10.arc
Solaris
hrnbrula -A audit.report -C /usr1/cntl/control.file
         -S /usr1/brula/select.file -s 10 -n 40 -W /tmp
         -M /usr1/brula/TBL usr1/archives/seg10.arc
This produces an unload with a separate file for each table where:
Unloaded tables are written to files TBL001 through TBLnnn in the directory c:\brula (Windows) or /usr1/brula (Solaris). TBL is the 3 character prefix designated by the ‑M argument.
Sample Audit Log
The following is a compressed version of a sample audit log for the hrnbrula utility:

 
*hrnbrula TABLE RECOVERY ARCHIVE EXTRACT SEG# 001 DATE 2007 MAR 06 TIME 02:18
 
From Archive: seg01.bak
Control File: Y2000ULA.CTL
No Selection
Output File: ULA.OUT
Use current directory for work-file space
# of Tables requested: 1
No Parameterized tables included
BREAK RUN option not requested
 
REQUIREMENT TYPE % OF PAGES PAGE ESTIMATES MEMORY REQUIRED
 
DATA 85 85000 1700000
PRIMARY INDEX 3 3000 24000
GROUP INDEX 10 10000 200000
GROUP INDEX INDEX 2 2000 16000
TOTAL PAGES 100 100000 1940000
 
PARM INSTANCE INDEX 1 100 810012
TOTAL MEMORY ------------------------------ 2750012
 
-------------------- TABLE # 0001 -----------------------
CONTROL - file: Y2000ULA.CTL
INPUT - TDS Table: Y2000_TDS Character Set: ENGL
OUTPUT - file: : Data type: Huron; Record format: Variable
 
#fields - 2; #records - 100000; #parameters - 0; #secondaries - 0
Output sizes: Record - 18; Minimum Record - 3 Buffer - 65536
 
*************
S6BBA011I PASS ONE PROCESSING INITIATED
 
S6BBA012I PASS ONE: READ
PAGES: HIX GIX IX DATA OTHERS
0 5 1 149 32
 
S6BBA013I PASS TWO PROCESSING INITIATED
 
S6BBA015I DATA TABLE COMPRESSION COMPLETE
------> Input: 149 Output: 1
Input: 0 Processed: 0 - S6BBA019I PASS TWO; GROUP INDEX PAGES READ
 
 
S6BBA020I PASS THREE PROCESSING INITIATED
 
RECOVERING TABLE: Y2000_TDS S6BBA159I TABLE OR INSTANCE EMPTY
 
Input: 188 Processed: 1 - S6BBA021I PASS THREE; ARCHIVE RECORDS
 
Y2000_TDS ---> S6BBA159I TABLE OR INSTANCE EMPTY
 
 
-----------------------------------------
SORT INITIALIZATION: Work area = 262008
-----------------------------------------
 
SORTING COMPLETED - FINAL PHASE INITIATED:
 
FILE: ULA.OUT :
S6BSV997I MVS Dataset characteristics:
----> RECFM=VB,LRECL=38,BLKSIZE=42
Y2000_TDS # rows unloaded: 1
 
S6BBA160I **AT LEAST 1 TABLE OR INSTANCE EMPTY**

 
Related Utilities

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