Overview

The binary host data handler is a data-conversion module whose primary role is to convert business objects to and from host system COBOL records.

In addition to converting host records into business objects and vice versa, the binary host data handler parses COBOL records containing the Packed Decimal (PD) and Double Byte Character Set (DBCS) data available in the form of bytes, along with the general ASCII/Text data.

The binary host data handler handles the COBOL datatypes described in Table 66.

Table 66. Datatypes supported by the binary host data handler

Data Type PIC clause format
Alphabetic A(n), AAA... n times
Numeric 9(n), 999... n times
Alphanumeric X(n), XXX... n times
Packed decimal 9(n) with a COMP-3 clause
DBCS G(n), GGG... n times

In addition to these data types, the binary host data handler also supports a number of other PICTURE clauses (for example, V, P, S, and others).

The data handler can be plugged into and used by the JText Connector Agent. The following section describe the binary host data handler in more detail. For more information about configuring and using the JText Connector Agent, see the Adapter for Jtext User Guide.

Processing COBOL records and business objects

COBOL records use a template, called a copybook, to define their structure. Figure 37 shows the basic structure of a COBOL record, which is specified in the data division of a COBOL program.

Figure 37. COBOL record structure

Data Division.
           File Section.
                 FD Customer-File
                 Record Contains 50 Characters.
                 01 Customer-Record.
                    05 Customer-Name.
           10 Last-Name Pic x(17).
           10 Filler Pic x.
           10 Initials Pic xx.
        05 Part-Order.
           10 Part-Name Pic x(15).
           10 Part-Color Pic x(15).
   Working-Storage Section.
     01 Orig-Customer-Name.
        05 Surname Pic x(17).
        05 Initials Pic x(3).
     01 Inventory-Part-Name Pic x(15).
     01 Inventory-Part-Color Pic x(15).
 

The file section of the data division denotes the structure of the record as specified in the file, whereas the working-storage section denotes the handling of the data within the COBOL program.

The COBOL copybook corresponds to the file section of the data division. The copybook corresponding to the record with the above structure appears in Figure 38.

Figure 38. Sample copybook

01  CUSTOMER-RECORD.
   05  CUSTOMER-NAME
         10 LAST-NAME          PIC X(17)      USAGE DISPLAY-1    
         10 FILLER                 PIC X                                     
         10 INITIALS               PIC XX                          
   05  PART-ORDER
         10 PART-NAME          PIC X (15)      USAGE DISPLAY-1    
         10 PART-COLOR         PIC X (15)      
 

Just as a copybook describes the structure of the COBOL record, the business object definition describes the structure of the business object. The binary host data handler uses business object definitions when it converts between business objects and COBOL records. It determines how to perform the conversion using the structure of the business object definition and its application-specific information.

A properly-constructed business object definition ensures that the data handler can correctly convert a business object to a COBOL record and a COBOL record to a business object. Before the binary host data handler can perform a conversion between the COBOL record and the business object, it must be able to locate the associated business object definition.

Use of the binary host data handler to convert a COBOL record to a business object or a business object to a COBOL record requires that the following steps occur.

Table 67. Using the binary host data handler

Step For more information
1. Business object definitions that describe the COBOL record and business-object structure must exist and be available to the binary host data handler when it executes. Business object definitions for COBOL records Creating business object definitions for COBOL records
2. The binary host data handler must be configured for your environment. Configuring the binary host data handler
3. The binary host data handler must be called from the Jtext connector to perform the appropriate data operation:
a) Data operation: receive a business object from the caller, convert the business object to a COBOL record, and pass the COBOL record to the caller. Converting business objects to COBOL records
b) Data operation: Receive a COBOL record from the caller and use binary host components to build a business object based on the supplied binary datatype. Then return the business object to the caller. Converting COBOL records to business objects

Binary host data handler limitations

The binary host data handler has been created specifically for use with certain binary data formats, with COBOL records, and with Jtext connector in particular. Limitations on its capibilities in a business integration system are as follows:

Binary host components

Internally, the binary host data handler uses different components to handle the various types of data in a COBOL record. Figure 39 shows these components.

Figure 39. Binary host data handler components

These components are described in detail in the following sections.

Pure DBCS data

Any attribute with ASI specifying a COBOL PICTURE Clause of G(x) and the datatype as DBCS will be treated as DBCS data by the binary host data handler. The Pure DBCS data component of the data handler will process DBCS data retrieved from the mainframe as follows :

The minimum length of any DBCS data that can be processed is one character, i.e. 2 bytes. The COBOL Compiler restricts the maximum length. DBCS data is always right padded with double-byte blank/space characters.

EBCDIC data

The binary host data handler recognizes EBCDIC data with application specific information in the BO definition that contains any of the alphabetic COBOL PICTURE Clauses (A or X), and the datatype specified as EBCDIC. The EBCDIC component of the data handler decodes EBCDIC data with the encoding format specified by the user in the 'BinaryEncoding' property of the MO_ DataHandler_DefaultBinaryHostConfig (Cp930, by default) to get a Unicode Java String object.

The minimum limiting length for any EBCDIC data is one character, corresponding to one byte. The COBOL Compiler restricts the maximum length. This data is always right padded with blank/space characters.

Packed decimal data

Packed Decimal data is recognized by the binary host data handler through application specific information in the business object definition that contains any of the numeric PIC clauses (9 or X), with a COMP-3 clause, and the datatype specified as Packed Decimal.

The base limit on Packed Decimal data is one digit. The digit has to be a signed integer, and cannot represent a float value. The Packed decimal data component does not supercede the maximum value that a packed decimal field in COBOL can hold, specified as 15 digits by S/390 architecture. Packed decimal data is always left padded with zeroes.

Note:
The example input 999 (base 10) corresponds to the hex value: 03D7 (base 16). Hence, if it is not packed, it will be stored as 000003D7. When packed, each digit gets stored in a nibble, and hence, the value becomes 999C (base 16).

The rightmost nibble denotes the sign of the packed decimal. A rightmost nibble of A, C, E, or F implies positive, and B or D implies negative.

Copyright IBM Corp. 1997, 2003