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


Chapter 1 Using TIBCO Object Service Broker Utilities : hrnbrulh (Batch Unload (Online))

hrnbrulh (Batch Unload (Online))
Syntax
hrnbrulh -C controlfile [arguments] filename
Platforms
Windows, Solaris
Description
The hrnbrulh utility extracts data from an entire table or from selected table instances of a parameterized table. It is used when TIBCO Object Service Broker is up and running and the Pagestore segment containing the data to be unloaded is online. This unload utility provides you with:
Unload Utilities Differences
The two unload utilities (hrnbrulh and hrnbrulb (Batch Unload (Offline)) are similar, and differ only in the following ways:
Online/Offline
The hrnbrulh utility is an online unload, while the hrnbrulb utility is an offline unload.
Specifying Table Location
In the hrnbrulh utility, you identify the Data Object Broker to be accessed. In the hrnbrulb utility, you specify the segment where your table resides.
Security on the hrnbrulh Utility
Unload Restrictions
Unloading is not permitted under either of the following conditions:
Permissions Enforced
The following permissions are enforced for allowable unloads:
If the requestor is either the owner of the target table or the security administrator of the owner, the request is allowed.
If the requestor is neither the owner of the target table nor the security administrator of the owner, and the requestor’s security classification is less than the security clearance required of the target table, the request is denied.
If the requestor has READ ACCESS to the target table by virtue of direct permission granted to the user ID or the current group, for example, the request is allowed; otherwise, the request is denied.
Arguments
 
-A auditreportname
The file to which the audit report is written. If this argument is omitted, the report is written to the screen (Windows), or stdout (Solaris).
-C controlfile
Indicates oldnull argument is selected. All numeric nulls encountered in the unload file are treated as zero.
-S selectionfile
The full path and filename of the selection file that is constructed using the BATCHUNLD_CARDS shareable tool. This entry is optional.
-t nodename
-U userid
The user ID used to determine authorities. This argument must always be used in conjunction with the ‑P argument. If not specified, the login user ID is the default.
-P password
Files
controlfile
A file containing the control information describing the output file and the table you want to unload. Create this file using the BATCHUNLD_CARDS tool.
filename
The name of the file to which the table is unloaded.
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
Segment Online
The Pagestore segment from which you intend to unload a table must be online. This means that the Data Object Broker must be in operation.
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 file is prepared using the BATCHUNLD_CARDS shareable tool and supplied to the utility using the ‑C argument. For more information, refer to TIBCO Object Service Broker Shareable Tools.
The complete file must be defined so that the hrnbrulh 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 BATCHUNLD_CARDS and supplied to the utility using the -S argument. For more information, refer to TIBCO Object Service Broker Shareable Tools. 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 either of the Batch Unload utilities to unload data, you can 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 only.
Fixed (F) or Fixed Block (FB) format means that all records are the same length. Under OSB for Windows or OSB for Solaris, there is no difference between F and FB formats.
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. 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 that 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 hrnbrulb (Batch Unload (Offline)) utility or the hrnbrulh 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.
Transferring Unloaded Data Using FTP
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 are examples of the hrnbrulh command:
Windows
hrnbrulh -A audit.trl -C c:\cntl\control.fil -O
         -t dbid output.fil
Solaris
hrnbrulh -A audit.trl -C /usr1/cntl/control.fil -O
         -t dbid output.fil
These command lines indicate:
Sample Audit Log
The following illustrates a sample audit log for the hrnbrulh utility:

 
*batchsrv OFFLINE BATCH UTILITY SERVER DATE 2007 MAR 06 TIME 11 27
Requested Utility: hrnbrulh
 
DEFAULT HOST, no (-t) HOST-ID submitted
HOST = TEST
CONTROL - file: Y2000ULH.CTL
INPUT - TDS Table: Y2000_TDS Character Set: ENGL
OUTPUT - file: ULH.OUT: Data type: Huron; Record format: Variable
 
#fields - 2; #records - 100000; #parameters - 0; #secondaries - 0
Output sizes: Record - 18; Minimum Record - 3 Buffer - 65536
 
 
UNLESS SPECIFIED BELOW (COLS 64-79) PACKED DECIMAL AND BINARY NULLS WILL
BE CONVERTED AND OUTPUT TO THE FILE AS FOLLOWS:
BINARY: (default = LOWVALUE) Length 2 thru 8 x'80~~~~~~~~00'
PACKED: (default = LOWVALUE) Length 1 thru 8 x'9B' thru x'999999999999999B'
 
 
UNLOAD FIELD - KEY: type= I; syntax= B; length= 4; decimals= 0
 
UNLOAD FIELD - FLD: type= S; syntax= C; length= 10; decimals= 0
 
 
END OF TABLE
 
 
 
*hrnbrulh TDS TABLE UNLOAD Date 2007 MAR 06 Time 11:27
 
usr10 UNLOADING TABLE Y2000_TDS FOR SYSADMIN
 
Get page request to Host failed
RTIX Index not available - S6BBU106E: RESIDENT TABLE INDEX ENTRY NOT FOUND FOR
TABLE
 
Connection with Host terminated

 
Related Utilities

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