Configuring the Adapter : FileSubscriber Configuration File

FileSubscriber Configuration File
The FileSubscriber configuration file contains three sections: Trace, Options, and one or more FileType sections.
Figure 12 Sections of a FileSubscriber Configuration File
Detailed information about each section can be found using the table below:
Element Syntax
Each section consists of elements; elements consist of parameters surrounded by curly brackets. Each parameter has either a value or consists of tags, surrounded by curly brackets.
For example, the FILE_OPTIONS element shown below consists of parameters with values, separated by commas:
 
FILE_OPTIONS = { filePrefix = "ft2", datasetType = ”SEQ”,
           skipPadding=”false”, outputDataset=”TIBCO.TEST.OUTPUT”,            subscribeSubjectName = "A.C" }
 
The FILE_LINE element shown below consists of a number of field parameters that have as their value a set of tags with values (separated by commas).
 
FILE_LINE = {
   field = { description = "Part Number", fromMessage="true",
         length = ”6”,type="STRING", value="PartNo", length = ”11”,
         position=”0”},
 
   field = { description = "Description", fromMessage="true",
         type="STRING", value="Desc", length = ”15”,          position=”11” },
     ..........}
JCL Consideration
Publisher or subscriber programs can locate the configuration file in the following two ways:
Both programs can identify the INI file either through the PARM= or DD name.
If the INI file is not specified in the PARM= parameter on the EXEC card, then the programs locate the INI file using the DD name //INIFILE.
Trace Section
You use the Trace section to specify the tracing behavior of FileSubscriber. This should be the first section in the configuration file. The elements specified in this section are listed below; all are required (except those used at the request of TIBCO Support).
Number of log files to keep. Each saved old log file name has a number from 1 to the FILE_COUNT value minus 1 suffixed to it. For example, if FSLOG is specified as the FILE_NAME, then the latest saved old log file is named FSLOG1. If FILE_COUNT is set to 5, then there are four saved log files, named FSLOG1 through FSLOG4.
Identifies the log file to be used for trace messages. This must be a sequential data set. If the data set does not exist, then FileSubscriber creates it.
Specifies whether to send the trace messages also to the standard output (STDOUT) of the job log. Setting this element to true causes trace messages to be placed in the job log as well as written to a log file. Setting this element to false means that trace messages are only written to a log file.
TRACE_EMS_
EPM_ERROR_
MSGS
Specifies if JMS tracing should be enabled for ERROR or EPM messages when using EMS. Valid values are none, epm, error, both. Default is none.
A value of EPM will turn on JMS Message body tracing for all EPM messages sent by the Adapter to the EEM_DESTINATION.
A value of error will turn on JMS Message body tracing for all ERROR messages sent by the Adapter to the ERROR_DESTINATION.
A value of both will turn on JMS Message body tracing for all EPM and ERROR messages sent by the Adapter.
TRACE_EMS_
HEARTBEAT_
MSGS
Specifies if JMS tracing should be enabled for HEATBEAT messages when using EMS. Valid values are true, false. Default is false.
A value of true will turn on JMS Message body tracing for all Heartbeat messages sent by the Adapter.
The kind of information that FileSubscriber should log. FileSubscriber generates trace messages according to a trace level (1, 2, or 3) that you specify with this element.
Trace level 1 generates the following session-level messages:
Trace level 2 generates level 1 messages plus all the following values loaded from the configuration file:
Trace level 3 generates level 1 and 2 messages plus the following field-related messages:
Trace level 4 for detailed tracing. Usually used only at the request of TIBCO Support.
Trace level 5 for detailed tracing. Usually used only at the request of TIBCO Support.
Trace Level 6 generates level 1 through 5 messages. Usually used only at the request of TIBCO Support.
Traces all detailed Timer callbacks used for handling ECM Admin messages, Re-Publish Messages, File Lock retry, HeartBeat Messages, etc.
Trace Level 10 generates Level 1 through 6 messages. Usually used only at the request of TIBCO Support.
Trace Level 15 generates Level 1 through 10 messages. Usually used only at the request of TIBCO Support.
TRACE_
SWITCHES
Allows non-SMS (System-Managed Storage) sites to specify the associated UNIT parameter to be used with the VOLSER for trace (.LOG) files. See VOLSER_TRACE, below.
Allows non-SMS (System-Managed Storage) sites to specify a specific MVS volume (or set of volumes) to be used for storing trace (.LOG) files. Must be used with the UNIT_TRACE element. See UNIT_TRACE, above.
For customers in time zones other than the ones specified above, the appropriate TZ string should be specified. For example, mainland European times can be specified as
Options Section
You use the Options section for the following:
You can override these global elements in the FileType section.
 
Sets the terminate subject or destination (for EMS) to _FILEADAPTER.<adapter name>.TERMINATE. This is used to stop FileSubscriber.
Sets the heartbeat subject or destination (for EMS) to _FILEADAPTER.<adapter name>.HEARTBEAT. This is used to send heartbeat messages, but does not mean that heartbeats are always sent.
For terminate messages, the default destination type is QUEUE. For heartbeat messages, the default destination type is TOPIC.
Specifies whether to abend the Adapter when it first encounters an initialization error. If set to true and, if a configuration error is found for a file, generate a message to the log and go on to the next file. If set to false, abend the Adapter.
Valid values: true, false. Default is false.
Valid values: true, false. Default is false.
Identifies the subject for messages that the Adapter will pass to TIBCO BusinessEvents. The value is the destination to which the event messages should be routed.
Identifies the destination for messages that the Adapter will pass to TIBCO BusinessEvents. The value is the destination to which the event messages should be routed.
Specifying this element along with the following required parameters establishes reliable mode publishing:
providerURL — The URL of the TIBCO EMS server
Specifies where error messages should be published. If this parameter is not blank, all traceErr and FatalErr messages are copied and sent to that destination.
Note: Specify this field at the end of the Options section. Since the Rendezvous transport or EMS connection is not created until the end of the Options section, any error that occurs before this cannot be published.
Specifies where the error message should be published. If this is not blank, all traceErr and FatalErr messages are copied and sent to that subject.
If set to true, additional file type information is published in the heartbeat message. For example, file prefix, file extension, and number of messages published are included.
Valid values: true, false. Default is true.
Specifies the interval in milliseconds between heartbeat messages. The default is 60000 milliseconds, or 60 seconds.
Defaults to codepage 1047, which is the standard default for U.S., Canadian, and western European EBCDIC “Latin-1” systems.
Specifies the default output data set to be used for any file type. This will be suffixed appropriately for the actual output data sets.
You must identify which data set contains the file(s) that you want to create. You can use the FILE_OPTIONS section to identify a default output data set's higher level qualifier at a global level.
In addition, you can specify an output data set for each file type. You must identify which data set contains the file(s) that you want to create. You can use the Options section to identify a default output data set's higher level qualifier at a global level.
Valid values: true, false. Default is true.
Allows you to group all Progress (.PRG) files under a common high-level qualifier. Use the following parameter to specify an HLQ that will be prepended to all .PRG files generated by Adapter for Files z/OS:
hlq.qualifier
where qualifier is a user-defined string.
If set to true, the publishing of heartbeat messages is enabled. If not specified, defaults to false, i.e., heartbeat messages are not published.
Limits the number of data blocks that the publisher can asynchronously send to prevent over-consumed or exhausted memory. This element only supports implementations using SFT (Simple File Transfer) and ECM (Explicit Confirmation Mode).
The value is one or more digits specifying the maximum depth of the RV Listen queue for incoming data block messages. The minimum value is 6. The default is 0.
The recommended RegionSize setting for Subscriber Job is 160M, for message sizes from 128K to 512K. This release of the Adapter is tuned to handle message sizes 128K to 512K. If you are using message sizes less than 128K, the subscriber performance may be affected.
If the Adapter has any memory problems with the above recommended steps, please contact TIBCO support.
Warning: QUEUE_LIMIT should be used only in ECM or RVCM transport mode. Do not use in RV transport mode. Doing so may result in lost data.
If you include this element, do not include the RVCM_SESSION element.
Specifying this element along with the following required parameters establishes a reliable mode of publishing.
name — Unique alphanumeric name identifying the TIBCO Rendezvous session
service — Service group for this session
network — Network to initialize a TIBCO Rendezvous session
daemon — Name of the TIBCO Rendezvous daemon for this session
If you include this element, do not include the RV_SESSION element.
Specifying this element establishes a Certified Messaging session. Include the same parameters as listed for RV_SESSION, plus the following:
ledgerFile — Name of the file-based ledger for Certified Messaging. This file is created in the Integrated File System.
requireOldMessages — Indicates whether a persistent correspondent requires delivery of messages sent to a previous session with the same name for which delivery was not confirmed. Setting this parameter to true enables delivery of old unacknowledged messages; setting it to false does not.
defaultTimeLimit — Sets the default message time limit for all outbound certified messages. Specify the time in whole seconds.
syncLedger — If you want to use a synchronous ledger file, set this parameter to true. The default for this is false, meaning an asynchronous ledger file is used.
If set, this parameter contains the name of the mapping file to use to map incoming user ids into userids on the local system. Once the mapping is performed, a RACF CHECK is performed on any user-id for an incoming File being subscribed to, to ensure that the user has the authority to update the associated z/OS file.
Note: The FileAdapter loadlib must be “APF authorized” if you intend to activate the RACF check function. Please contact your system programmer for this procedure.
--Purpose: To map the userid's coming from other --platforms to the ones on z/OS system.
--Node    Publisher UserId       Subscriber Mapped --                               UserId
BATMAN-DT      batlab             BATMAN
BATMAN-DT      batlab             BATMAN2
MARS           BATMAN             BATMAN
MARS           BATMAN2            BATMAN2
BATMAN-DT      ROBIN              BATMAN
BATMAN-DT      ROBIN             BATMAN2
Specifies the Adapter should abend if it cannot successfully call the API tibrvsend. This flag is only applicable to record mode processing. If the file is in block mode, the flag will be ignored and the Adapter will be abended. Upon recovery, the Adapter will re-sync to the last check point. In the case of standard block mode, the entire file will be retransmitted. In ECM, retransmission will begin with the last block that was successfully acknowledged.
Valid values: true, false. Default is false.
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a UNIT parameter to be used with the VOLSER for work (.CWK) files. (See VOLSER_CWK below.)
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a UNIT parameter to be used with the VOLSER for GDG output files. (See VOLSER_GDG below.)
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a UNIT parameter to be used with the VOLSER for SEQ (sequential) output files. (See VOLSER_OUTPUT below.)
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a UNIT parameter to be used with the VOLSER for Progress (.PRG) files. (See VOLSER_PRG below.)
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a specific MVS volume (or set of volumes) to be used for storing File Adapter work (.CWK) files. Must be used with UNIT_PRG.
VOLSER_CWK = "volume,volume"
where volume is a valid setting for MVS volume.
The maximum number of VOLSER values you can set is 59. If you need assistance determining the correct VOLSER names to use, contact your MVS systems programmer.
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a specific MVS volume (or set of volumes) to be used for storing File Adapter GDG output files. Must be used with UNIT_GDG.
VOLSER_GDG = "volume,volume"
where volume is a valid setting for MVS volume.
The maximum number of VOLSER values you can set is 59. If you need assistance determining the correct VOLSER names to use, contact your MVS systems programmer.
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a specific MVS volume (or set of volumes) to be used for storing File Adapter SEQ (sequential) output files. Must be used with UNIT_PRG.
VOLSER_OUTPUT = "volume,volume"
where volume is a valid setting for MVS volume.
The maximum number of VOLSER values you can set is 59. If you need assistance determining the correct VOLSER values to use, contact your MVS systems programmer.
For implementations that do not use SMS (System-Managed Storage), this element allows you to specify a specific MVS volume (or set of volumes) to be used for storing progress (.PRG) files. Must be used with UNIT_PRG.
VOLSER_PRG = "volume,volume"
where volume is a valid setting for MVS volume.
The maximum number of VOLSER values you can set is 59. If you need assistance determining the correct VOLSER names to use, contact your MVS systems programmer.
Allows you to group all File Adapter Work (.CWK) files under a common high-level qualifier (HLQ). Use the following parameter to specific an HLQ that will be prepended to all .CWK files generated by Adapter for Files z/OS:
hlq.qualifier
where qualifier is a user-defined string.
Specifies write z/OS errors to SYSLOG. Each message includes date and time information. The format is standard IBM style message format, that is, AAAnnnnnn header followed by message text.
Valid values: true, false. Default is false.
FileType Section
Use the FileType section of the FileSubscriber configuration file to describe the file that is to be written. The FileType section consists of two elements:
Configuring the FILE_OPTIONS Element
This section describes the parameters for configuring the FILE_OPTIONS element. A config file can have multiple [FILE_OPTIONS] definitions in a single file. See the File Subscriber Examples section to see how this is done.
Used to construct the name of the file that is written to the output data set by FileSubscriber. Specify a value of up to 8 characters. Also used by FileSubscriber for deriving the names of the progress file and the work file.
Valid values: TOPIC, QUEUE. Default is TOPIC.
Valid values: body, null.
Specifies that a trackingId message is to be sent by the subscriber. This message is created after the subscriber finishes writing the file and receiving the EOF acknowledgement from the publisher.
Valid values: true, false. Default is false.
If this value is true, the following additional fields are attached to the message published to trackingIdSubject:
Result (0 or 4 or 8 = OK or Fail) Overall transfer result from Subscriber
Name of the subject on which messages containing the trackingId information are published.
Name of the destination to which messages containing the trackingId information are published.
Specifies the type of data set for this file type. This can be SEQ for sequential data sets, GDG for Generation Dataset Groups,PDS for partitioned datasets, or VSAM for Virtual Storage Access Method.
The higher-level qualifier for the output data set for this file type. The default is what is specified in the OUTPUT_DATASET element of the Options section. Output File Naming describes how a complete data set name is derived for output in the case of SEQs, GDGs, and VSAM.
NOTE: VSAM and GDG file types must be pre-allocated before subscribing to them.
Maximum number of characters constituting a line in the output file. This parameter is valid only if skipPadding is true.
Note: lineLength cannot be larger than 32756 bytes.
Possible values are true for fixed-length records, false for variable-length records.
Indicates how the subscriber should behave when the receiving data record length is different from the one specified by the lineLength parameter.
Possible values are wrap, discard, error.
wrap—wrap around the rest of the record to a new line.
discard—truncate the record and do not generate an error file
error—truncate the record and rename the working file (.CWK) to the error file (.ERR) at EOF.
This parameter can only be used for sequential data sets. If true, FileSubscriber appends the system time along with the filePrefix parameter to the output data set when constructing the name of the file to be written. That is, the generated output data set name has the format:
If true, enables automatic output file creation based on a timer or a message count. If false, output files will only be created when an End-of-File is received.
Default is true. This value should be explicitly turned off if not required.
If autoGenerateFile is set to false, then the saveFileInterval parameter and generateFileOnNumberOfMessages are ignored. When set to false, the file will not be generated until an End-Of-File indication is received from the Publisher.
The rate (in seconds) that FileSubscriber uses to generate an output file. Valid only if autoGenerateFile is set to true. Default is 120 seconds.
The saveFileInterval parameter is used to cause periodic (every N seconds) saving of received (staged) data to the target file. The saveFileInterval and generateFileOnNumberOfMessages parameters are mutually exclusive.
The maximum allowable value is 1800, corresponding to an interval of 30 minutes. If a value greater than 1800 is specified, a message is written to the trace log and a value of 1800 is used.
An integer value for this parameter causes FileSubscriber to generate an output file if the number of messages received since the generation of the last output file equals this number.
Default is 0, which means that the parameter is not used.
The generateFileOnNumberOfMessages parameter is used to cause the saving of received (staged) data to the target file whenever N number of messages (records) have arrived. The saveFileInterval and generateFileOnNumberOfMessages parameters are mutually exclusive.
Time between each retry in milliseconds. Specifies the amount of time the FileSubscriber should wait between retries when it detects a “File Locked” condition. Default is 0.
If true, specifies that if an output file already exists, the data received is appended to the existing file. Otherwise, FileSubscriber overwrites existing data. In the case of sequential dataset output, this option is effective only when appendDateTime is set to false.
Warning: If the subscriber is configured with appendToExistingFile="false" and if there is an I/O error (B37/D37) in writing to output file, then the Adapter removes the output file first and then renames the work file to error file.
As a result customers lose the existing output file even though the file transfer has failed. This is like deleting the existing load module even when linking failed. This behavior is observed only with SEQ files not with GDG.
Specifies what the Adapter does when it cannot save data to the target file due to insufficient space. If true, exit the Adapter. Otherwise continue to accept data and write it to the 'temporary' subscriber file.
Valid values: true, false. Default is true.
1.
The volume is completely out of space, and no file can be created. An error message is written to the log indicating the file could not be created because of lack of space.
2.
The file was partially written, but no more extents can be allocated. In that case, the partial file is renamed to filename.ERR and cataloged. An error message is written to the log indicating the file could not be created because of lack of space.
If this flag is set to 'true', the output file is named the same as the file being published. Specifically, the output file is named the same as the filename contained in the EOF message.
1.
the filePrefix must be specified.
2.
generateFileSubjectName must be specified and must match the endPublishSubject as specified in the Publisher's INI file.
Valid values: true, false. Default is false.
If the subject is defined, then the subscriber will publish a message using this subject to announce that a new file is created. It is published after the executeAfterProcess is performed.
If this destination is defined, then the subscriber will publish a message using this destination to announce that a new file is created. It is published after the executeAfterProcess is performed.
Note: The destination type defaults to subscribeDestinationType.
Valid values are: none, all, append, new. Default is none.
A value of none indicates create the file regardless of whether an existing file is cataloged or not.
A value of append denotes the incoming file should be discarded, if the FileType is marked for append, but there is no current dataset cataloged.
A value of new denotes the incoming file should be discarded if there is no existing cataloged file entry.
A value of all combines the attributes of both append and new.
This required parameter specifies the subject name to subscribe to for generating the output file for this file type.
If autoGenerateFile is set to false, then the saveFileInterval parameter and generateFileOnNumberOfMessages are ignored. When set to false, the file will not be generated until an End-Of-File indication is received from the Publisher.
This required parameter specifies the destination name to subscribe to for generating the output file for this file type.
Note: The destination type defaults to subscribeDestinationType.
Most usages of generateFileSubjectName require that it match the subscribeSubjectName.
The generateFileFieldName is used to act as a message differentiator, so that message being sent to a Subscriber can be identified as being a “Generate File” trigger message. It is only required if the subscriber is using the generateFileSubjectName for the associated FileType.
If you have specified that the session identified in the configuration file is a certified session, then you can identify those files that you wish to be published in certified or in non-certified (Reliable) mode.
Note: If you specify a certified session, then all files are published in certified mode unless you specify false for the isCertified parameter.
If the FileSubscriber session is not a certified session, this parameter is ignored. If the FileSubscriber session is specified as a certified session, then the default value for this parameter is true, which means that the file is subscribed to in certified mode. You can specify false if you want to have a specific file subscribed to in non-certified (reliable) mode.
If included and set to true, specifies that data fields are to be delimited and not padded.
In that case, FileSubscriber generates variable length fields in the record. The field position in the output record is determined by the position parameter in the FILE_LINE element.
If false, data fields are padded with characters specified by the padCharacter parameter and are fixed width.
In that case, FileSubscriber generates fixed-length fields in the output record. The file position in the output record is determined by the position parameter in the FILE_LINE element, and the field length is determined by the length parameter.
If skipPadding is false, this alphanumeric character is used as the pad character.
Specifies which direction to pad the data field, left or right. The default is right, which means that the pad characters are added to the right side of the field (that is, left-justified).
An alphanumeric character used to separate the fields in a line. This parameter is valid only if skipPadding is true. There is no default, which means that if this parameter is not specified, there is no separator between fields.
When set to true, specifies that the file data is in binary format. Binary data includes zoned decimal, binary, packed decimal, and floating point data types.
Specifies the data transfer mode (i.e, Record Mode or Block Mode) and whether to use ECM or non-ECM with the specified data transfer mode. Valid values:
If true, the Adapter writes the data to the file in blocks. The publisher determines the block size. Default is false.
Valid values: true, false. Default is “false”.
Name of the corresponding ECM publisher in block mode. This parameter must have a valid value if ECM mode is selected.
Warning: You cannot specify both an ECMSubscriberName and a confirmationSubject.
Confirmation subject name used by FileSubscriber to exchange block confirmation messages in record mode.
Warning: You cannot specify both a confirmationSubject and an ECMSubscriberName.
Only used for ECM Block Mode. Specifies the number of seconds the FileSubscriber should wait between retries to re-connect to the Publisher after a startup. It is used to coordinate the startup handshake used between the Publisher and Subscriber, when ECM is being used.
Specifies how the VSAM file should be used: INSERT only, REPLACE only, or UPSERT (insert and replace).
File name to use if VSAM file logging is enabled. This is a sequential file used to log any changes made to the associated VSAM file. Any inserts or updates made to the VSAM file by the Adapter are recorded to the log sequential file. The sequential file is always opened in append and binary mode.
Note: When this flag is specified, the vsamUseLog is required or the Adapter throws a fatal error.
(stopOnFull or No) Determines whether logging is to be performed. If set to No, no logging is performed. If set to StopOnFull, logging is performed. If the log file becomes full during operation, the Adapter abends to prevent making changes to the VSAM file without an associated log record of the changes.
It is the end user’s responsibility to monitor the use of the log, and to periodically clear it to prevent the Adapter from abending due to log full conditions. If VsamUseLog enables logging, then any primaryAlloc= and secondaryAlloc= keywords are used to allocate space for the associated VSAM log file.
Configuring the FILE_LINE Element
Use the FILE_LINE element in the FileType section to format the output record. If output records are in a different format, you can include multiple FILE_LINE elements in a single FileType section. The FILE_LINE element contains parameters that are defined using the following tags. These tags are optional unless specified otherwise.
The FILE_LINE element describes the format of the message to be published. It can be formed by using one or more of the following parameters.
Tags in the field parameter
The FILE_LINE element’s field parameter has the following tags.
A setting of true flags this field as being generated from a data item in the incoming TIBCO Rendezvous message. A setting of false means that this field is a constant field. Default is false.
For delimited files, specifies the field position in the record, starting at 1. Otherwise, specifies the byte index in the record, starting at 0. Also see the skipPadding parameter for the effect of position in output records. Use position or fieldStart but not both.
Used for binary files to specify the start of a field. The first byte of an input or output record is “1.” Use fieldStart or position but not both.
Data type of this field. Valid values: STRING, INTEGER, UNSIGNED INTEGER, SHORT, UNSIGNED SHORT, FLOAT, DOUBLE, BOOLEAN, and TIME. The default is STRING.
Valid values for EMS: STRING, INTEGER, SHORT, FLOAT, DOUBLE, BOOLEAN.
Allows you to override the padCharacter specified in the FILE_OPTIONS section. If needed, specify an alphanumeric character.
Allows you to override the padDirection specified in the FILE_OPTIONS section. If needed, specify either left or right.
The TIBCO Rendezvous numeric data types INTEGER, UNSIGNED INTEGER, SHORT, UNSIGNED SHORT, and FLOAT can be converted to PACKED, ZONED, BINARY, or Floating Point. STRING values that are in numeric format can also be converted to PACKED, ZONED, BINARY, or Floating Point output.
The implied length of the field will be calculated using the precision value, unless the length tag has been specified, in which case the value of length will be used.
When you specify TIME as a data type, FilePublisher gets the current system time, and places it in the TIBCO message. When FileSubscriber receives the message, it converts the time to a string, which represents the system time of the publishing system.
Tags in the constraint Parameter
FileSubscriber supports multiple line formats from different sections of a TIBCO message. To support this, you include multiple FILE_LINE elements in the FileType section. When multiple FILE_LINE elements are used, a constraint parameter must be supplied for each FILE_LINE element to indicate when to use that definition.
The FILE_LINE element’s constraint parameter contains the following tags:
The length of a line in the output file for this line field definition. The default is the value specified by the lineLength parameter in the FILE_OPTIONS section.