Configuring the Adapter : FileSubscriber Usage Guidelines

FileSubscriber Usage Guidelines
This section discusses the following FileSubscriber usage guidelines:
How FileSubscriber Determines blockSizeAlloc
You can use the lineLength and blockSizeAlloc parameters in the FILE_OPTIONS element of the FILE_TYPE section to set the record size (linelength) and the block size. The block size must always be a multiple of the linelength for fixed block size and is recommended to be a multiple of (linelength +4) +4 for variable width block size. For example, if the linelength is 100, the block size should be a (multiple of 104) + 4.
Setting these two parameters is highly recommended for efficiency.
This section discusses how the subscriber determines blockSizeAlloc if one or both of the parameters is undefined.
For all cases, the useFixedRecordFile parameter determines whether fixed block size or variable block size is used.
lineLength > 0, ’blockSizeAlloc’ > 0
If lineLength is defined, and blockSizeAlloc is defined, and you are using fixed-block, then the Adapter makes sure that the block size is a multiple of the line length and signals an error if the numbers do not match. In that case, the subscriber will not create a file. If you are using variable block size, the Adapter does not validate that the numbers match. Use the following rule of thumb for determining which lineLength corresponds to which blockSizeAlloc:
Fixed block sizeblockSizeAlloc must be multiple of lineLength. For example, if lineLength = 120, blockSizeAlloc = 1200.
Maximum for lineLength is 32756 and for blockedSizeAlloc is 32760.
Variable block sizeblockSizeAlloc must be at least lineLength+8. For example, if lineLength = 120, blockSizeAlloc = 1204.
lineLength > 0, blockSizeAlloc = -1 (or undefined)
If lineLength is defined, and blockSizeAlloc is undefined, the subscriber proceeds as follows:
Fixed block sizeblockSizeAlloc is set to lineLength. For example, if lineLength = 120, blockSizeAlloc = 120.
Variable block sizeblockSizeAlloc is set to lineLength + 8. For example, if lineLength = 120, blockSizeAlloc = 128.
lineLength = 0, blockSizeAlloc = -1 (or undefined)
If lineLength is undefined and blockSizeAlloc is also undefined, the subscriber proceeds as follows:
Fixed block sizelineLength and blockSizeAlloc are both set to 80.
Variable block sizelineLength is set to 80 and blockSizeAlloc is set to 88
lineLength = 0, blockSizeAlloc > 0
If lineLength is undefined and blockSizeAlloc is defined, the subscriber proceeds as follows:
Fixed block size—If blockSizeAlloc is a multiple of 80, lineLength = 80. If not, lineLength = blockSizeAlloc.
Variable block sizelineLength = blockSizeAlloc - 8.
Receiving COBOL Numeric Data Types
This section explains how FileSubscriber can be configured to handle the COBOL numeric data types supported by the Adapter.
FileSubscriber can be configured to create non-text files by using the isBinary=true parameter in the FileType section and two field parameter tags in the FILE_LINE element. This allows FileSubscriber to process non-text data types. The numeric data types are converted from incoming TIBCO data types of either INTEGER, UNSIGNED INTEGER, SHORT, UNSIGNED SHORT, FLOAT, or STRING into the desired target data type to be written to the file that is specified in the convertTo parameter. Because there can be a loss of precision when converting from FLOAT values, it may be preferable to specify STRING as the published data type. The numeric data type to be used for the output record for each field is specified by the tag convertTo in a field parameter of the FILE_LINE element.
See also Configuring VSAM Files for an example of a FileSubscriber configuration file coded to handle the supported numeric data types.
To support zoned, binary, packed, and floating-point data types:
1.
Set the isBinary parameter in the FILE_OPTIONS element to true.
2.
Set the convertTo and precision tabs in the FILE_LINE element to desired values.
Since the fields of data type BINARY(COMP, COMP-4) are being published as INTEGER, mention the type="INTEGER" and convertTo="BINARY".
Configuring VSAM Files
Configuring VSAM files is similar to configuring Sequential or GDG datasets. However there are some differences in the way VSAM files are subscribed.
The VSAM file (KSDS, ESDS, RRDS) must be allocated prior to subscribing to the file.
INSERT—Newly received TIBCO data are simply inserted in the VSAM file as new records. Any fields in the VSAM record that are not received in the Rendezvous message are set to the appropriate default values (BLANKS or ZEROS). For example, for ESDS files, the new data is appended to the end of the existing file. For KSDS files the data is inserted according to the key values.
REPLACE—Existing data records are updated with the data received in the TIBCO message. Any fields in the VSAM record that are not received in the message are left as is, at their existing value. This mode is mainly used for the KSDS file types.
UPSERT—Any newly received TIBCO data is checked against the existing VSAM file. If the key already exists, the record is updated. If the key does not exist, the record is inserted instead. This mode should be used with caution to avoid INSERTs of extraneous records, since it assumes and requires that keys in the published VSAM file are in sync with keys in the subscriber file.
The vsamFileMode parameter in the FILE_OPTIONS element determines which mode is used.
The outputDataset name is mandatory and must be allocated prior to subscribing to the file. This dataset is used to get the catalog information of the file being subscribed.
The VSAM file type is always treated as a binary file type (isBinary="true"). Hence, there is no need to specify the values isBinary="true", useFieldWidth="true", and skiPadding="false".
VSAM Logging
For each VSAM file to be logged, you must supply the name of the log file to use. The log file is a sequential binary file that keeps a record (audit trail) of all changes made to the VSAM file by the file adapter.
When a new set of TIBCO messages arrives for a specific VSAM file, the VSAM file is opened. At the same time, if VSAM logging is enabled, the associated log file is also opened in append mode. The adapter adds the following information to the log file:
For each VSAM record inserted, an Insert record is written to the log file.
For each VSAM record that is updated, a Before record is written, then an After record is written to the log file.
Each record consists of a 26 byte header followed by the binary contents of the associated VSAM file record.
When the VSAM file is closed, the associated log file is also closed.
You can use the vsamLogFile, and vsamUseLog parameters in the FILE_OPTIONS section for configuration.
Setting FileSubscriber for Explicit Confirmation Mode
The following FileSubscriber options apply to Explicit Confirmation Mode.
useExplicitConfirmation: Flag that specifies whether Explicit Confirmation Mode is on or off during block transfer. All the options below are only valid if this flag is true. [default: "false"]
ECMSubscriberName: the ECM subscriber name. This entry must match the corresponding participating ECM Publisher.
Adding Header and Trailer Records
You can add a header record or a trailer record, or both, to an output file. The added record(s) can contain any text string and variable data.
To add a header record, use the fileHeader parameter in the FILE_OPTIONS element of the FileSubscriber configuration file. To add a trailer record, use the fileTrailer parameter in the FILE_OPTIONS element of the FileSubscriber configuration file. For each of these parameters, a text string and up to three variables — the number of records, a blank field, and the date and time — can be specified in the following format:
 
  fileHeader=”<text>|[%<fieldWidth>,NUMBER_OF_RECORDS%]|
    %<fieldWidth>,BLANK%]|[<text>|%<fieldWidth>,DATE_TIME%]”
 
 fileTrailer=”<text>|[%<fieldWidth>,NUMBER_OF_RECORDS%]|
    %<fieldWidth>,BLANK%]|[<text>|%<fieldWidth>,DATE_TIME%]”
where
<text> is any alphanumeric descriptive string. If included, it can appear anywhere within the quotation marks but must not be included within the square brackets ([ ]).
%<fieldWidth> is the number of characters in the related field; % is a C type substitution
NUMBER_OF_RECORDS is replaced with the number of records in the output file. If there are no errors, this number should correspond to the number of messages received to generate the file.
Because the Adapter receives records into a work file then generates the final output file, the NUMBER_OF_RECORDS variable can be used when specifying a header record.
DATE_TIME is the date and time added in the format YYYYMMDDHHMMSS.
BLANK is a blank field that can be used to provide a space between the other variables.
FileHeader Example
Suppose you want to add a header record to an output file that shows the number of records received and the date and time that the output file was created, with two spaces between the fields. You would include code in the FILE_OPTIONS element of the FileSubscriber configuration file as follow:
 
  FILE_OPTIONS = { prefix=”test”,
  fileHeader=”[%4,NUMBER_OF_RECORDS%][%2,BLANK%][%14,DATE_TIME%]”,
  subscribeSubjectName=…