Configuring the Adapter : FilePublisher Configuration File

FilePublisher Configuration File
The FilePublisher configuration file contains four sections: Trace, Options, Pre-Register, and one or more FileType sections.
Figure 11 Sections of a FilePublisher 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:
 
FILE_OPTIONS = { filePrefix="ft1",
                 useFilePolling="true", pollInterval="5000",
                 datasetType=”PDS”,
                  ....
               }
 
The MESSAGE_FIELDS element shown below consists of parameters that have as their value a set of tags with values.
 
MESSAGE_FIELDS = {
   messageItem = { location="1", label="PartNo", type="STRING" },
messageItem = { location="2", label="Desc", type="STRING" },
   ...
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 control the tracing behavior of FilePublisher. 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).
Specifies how many 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 FPLOG is specified as the FILE_NAME, then the latest saved old log file is named FPLOG1. If FILE_COUNT is set to 5, then there will be four saved log files, named FPLOG1 through FPLOG4.
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 FilePublisher creates one.
Specifies whether to send the trace messages also to the standard output (STDOUT) of the job log. If set to true, trace messages are placed in the job log, as well as written to a log file. If set to false, trace messages are written only 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.
Specifies the kind of information that FilePublisher should log. FilePublisher 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 values loaded from the config file as below:
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.
PST8PDT -- Pacific Standard Time
MST7MDT -- Mountain Standard Time
CST6CDT -- Central Standard Time
EST5EDT -- Eastern Standard Time
When using the TZ setting, certain installation defaults may cause it to be ignored by OMVS. If this occurs, you will need to change the defaults in the EDCLOCTZ macro (which requires an assembly and re-link), which changes the TZ defaults system-wide. Alternatively, you can temporarily override the system defaults for the FileAdapter Job(s) only, by explicitly setting an ENVAR in the PARM field of your FileAdapter JCL as follows:
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:
Define certain global elements that apply to all file types defined in the configuration file. These global elements can be overridden in the file type definitions by using the appropriate tags.
.
Sets the terminate subject or destination (for EMS) to _FILEADAPTER.<adapter name>.TERMINATE. This is used to stop FilePublisher
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 published.
For terminate messages, the default destination type is QUEUE. For heartbeat messages, the default destination type is TOPIC.
If set to true, a RACF CHECK will be performed to ensure that the user id that sent in the trigger message to publish a file is authorized to access that file.
Valid values: true, false. Default is false.
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.
Specifies whether to abend the Adapter when it encounters an initialization error. If set to true, and if a configuration error is found for a file, the publisher generates a message to the log and goes on to the next file. If set to false, abend the Adapter.
Valid values: true, false. Default is false.
Specifies whether to remove the progress file at the end of a file transfer. The adapter uses the progress file for recovery purposes, as discussed in Progress File.
none—do not remove the progress file.
single—remove the progress file when it is a 1:1 relationship between the publisher and subscriber.
multiple—remove the progress file.
Valid values: true,false. Default is false.
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.
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.
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/EMS connection is not created until the end of the Options section, any error that occurs before this cannot be published.
Specifies where error messages should be published. If this parameter is not blank, all traceErr and FatalErr messages are copied and sent to that subject.
If set to true, additional file type information is also 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 heartbeat interval in milliseconds. The default value 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.
Default data set to be used for any PDS file type. An input file must be moved, not copied, to an input data set to ensure that the Adapter does not open a file that has not been completely generated.
If set to true, enables a publisher to shut down when the Rendezvous daemon shuts down.
If not specified, defaults to false, which means that the publisher continues to run even if the Rendezvous daemon shuts down.
Note: This functionality is provided by default in TIBCO EMS, i.e., whenever an exception occurs in a client connection to an EMS server, it is handled by default.
This limits the number of files that will be published at the same time (concurrently). This is used to limit excessive memory consumption and CPU when a large number of files need to be published.
Note: Ensure that the storage capacity allocated is sufficient to hold the files when moved.
Valid values: true, false. Default is true.
Note: Ensure that the storage capacity allocated is sufficient to hold the files when moved.
Allows you to group all Progress (.PRG) files under a common high-level qualifier. Use the following parameter to specific 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.
A setting to true for this element enables publishing of heartbeat messages. If not specified it defaults to false, meaning heartbeat messages are not published.
Specifying this element along with the following required parameters establishes a reliable mode publishing:
name — A unique alphanumeric name identifying the TIBCO Rendezvous session
service — The service group for this session
network — Network to initialize a TIBCO Rendezvous session
daemon — The name of the TIBCO Rendezvous daemon for this session
Specifying this element establishes a certified messaging session. Include all parameters listed for RV_SESSION, plus the following:
ledgerFile — The name of the file-based ledger for Certified Messaging. Specify a sequential data set for the ledger file.
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. A setting to true enables delivery of old unacknowledged messages; a setting 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.
Warning: To prevent ledger files from becoming filled and unusable, allocate sufficient storage capacity for them.
Specifies that the Adapter should abend if it cannot successfully call the tibrvsend API. This flag is only applicable to record mode processing. If the file is in block mode, the flag is ignored and the Adapter will be abended. Upon recovery, the Adapter re-syncs to the last check point. In the case of standard block mode, the entire file will be retransmitted. In ECM, retransmission begins 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 progress (.PRG) files. (See VOLSER_PRG below.)
If you need assistance determining the correct UNIT value 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. (See UNIT_PRG above.)
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.
If true, z/OS errors are written to SYSLOG. Each message includes date and time information. The format is standard IBM-style message format such as an SXFnnnnn header followed by message text.
Valid values: true, false. Default is false.
Pre-Register Section
You use the Pre-Register section to configure and specify the list of anticipated subscribers for the subjects that are published. When the anticipated subscribers are pre-registered, the delivery of Certified Messages is guaranteed even if subscribers start before or after FilePublisher or if FileSubscriber goes down and is restarted. To use this feature, both FilePublisher and FileSubscriber must establish an RVCM_SESSION with the requireOldMessage parameter set to true.
Use of this section in your configuration file is optional. If it appears, it should be defined after the Options section. Use the following element to specify the anticipated subscribers for each subject.
Specify the following required parameters within braces ({ }) for each anticipated subscriber for each subject. Up to 126 SUBSCRIBER elements can be defined in the configuration file.
listenerName — Specifies the name of the subscribing session.
listeningSubject — Specifies the name of the subscription subject.
FileType Section
The FileType section contains two elements:
FILE_OPTIONS Element
Use the FILE_OPTIONS element to specify the following:
The FILE_OPTIONS element is also used to identify those files you want to be published in certified mode if you have started a certified FilePublisher session. A config file can have multiple [FILE_OPTIONS] definitions in a single file. See the File PublisherExamples section for details.
The following table lists the parameters in the FILE_OPTIONS elements
filePrefix (required)
Used by FilePublisher to select files from the input data set for publishing. While polling, any files with a name that starts with this file prefix are selected for publishing. This prefix can be up to 8 characters. The string NULL is allowed.
When this parameter is NULL, and if trigger mode is used, and the full path of the file is specified, then the publisher should not be ignoring this file type. It should generate the temporary file without using the file prefix.
Valid values: TOPIC, QUEUE. Default is TOPIC.
Valid values: PERSISTENT, NON_PERSISTENT, RELIABLE_DELIVERY. Default is PERSISTENT.
Valid values: body, null.
Valid values are TIBEMS_AUTO_ACKNOWLEDGE, TIBEMS_CLIENT_ACKNOWLEDGE, TIBEMS_CLIENT_ACKNOWLEDGE, TIBEMS_DUPS_OK_ACKNOWLEDGE, TIBEMS_EXPLICIT_CLIENT_ACKNOWLEDGE, TIBEMS_EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE, TIBEMS_NO_ACKNOWLEDGE.
Default is TIBEMS_AUTO_ACKNOWLEDGE.
Specifies whether a GUID-like transaction id is to be used. If the file is configured as needing one, and if no trackingId string is received as part of the trigger message, then the publisher automatically generates a GUID-like string for the trackingId. If the trackingId string comes with the trigger message, the id is forwarded to the subscriber. This information is sent after the publisher receives the final EOF message from the subscriber.
Valid values: true, false. Default is false.
If the value is true, following fields are attached to the message published on the subject specified by trackingIdSubject:
PubLocalResult        (Publisher's Local result = 0 or 8)
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.
Polling can be used only if the data set type is PDS. Polling is not supported for sequential data sets, GDGs, or VSAM file types.
If set to true, FilePublisher polls for PDS files. A setting to false disables file polling. Default is false.
If file polling is enabled, specifies the time delay between file polls. The time is in milliseconds, i.e., 1000 = 1,000 milliseconds, or 1 second. Default is 1000.
Valid values: TOPIC, QUEUE. Default is TOPIC.
Specifies a subject on which FilePublisher sends a message when it starts to publish the file. The published message contains the name of the file that is published.
Specifies the destination to which FilePublisher sends a message when it starts to publish a file. The published message contains the name of the file that is published.
Note: Destination type is the same as the publishDestinationType
The subject on which FilePublisher sends a message after it has completed publishing the file. The end publish message contains the name of the file that is published and the number of messages published.
This parameter has a dual purpose. The first is to communicate to the FileSubscriber an end-of-file condition. The second is to communicate that the file has been published.
The durable subscribers in EMS require that endPublishSubject equal publishSubject (or endPublishDestinationName equal publishDestinationName).
Note that publishing an end-of-file indication on a different subject than publishSubject in RV may not maintain the correct sequence of messages.
Specifies the destination to which FilePublisher sends a message after it has completed publishing a file. The end publish message contains the name of the file that is published and number of messages published.
Note: Destination type is the same as the publishDestinationType
Most usages of generateFileSubjectName require that it match the subscribeSubjectName.
The adapter uses the generateFileFieldName parameter as a message differentiator. A message arriving on a subject name can be checked whether it is a regular “Data” message, or whether it is a “Generate File” trigger.
When an incoming message has a field matching the value specified in the generateFileFieldName parameter, then the message is assumed to be a “Generate File” trigger message, and the subscriber generates the final target output file.
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 reads the file in blocks, without regard to its record or field structure. Default is false.
Determines the block size, that is, the number of bytes that the Adapter reads and publishes each time it reads the file. Default is 65536 bytes.
Valid values: true, false. Default is false. If true, block mode is used automatically.
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. Default is 10 seconds.
Specifies how a publisher proceeds upon acknowledgement from all ECM subscribers. If set to true, the next transaction is processed immediately after FilePublisher receives all the confirmations. If set to false, it uses the normal transactionDelay parameter to process transactions.
Valid values: true, false. Default is true. Set to true for ECM publishers to speed up delivery.
Identifies the ECM subscriber with which this publisher is exchanging acknowledgements in block mode. Repeat this entry for every participating ECM subscriber. This string must be precisely the same spelling as the ECMSubscriberName parameter that is specified in the subscriber's configuration file.
Warning: You cannot specify both an ECMSubscriberName and a confirmationSubject.
A new SubscriberName ID is required so that the EMS server can identify which consumer client(s) requires which messages resent after a failure. This SubscriberName ID is created dynamically when the Subscriber is started.
Confirmation subject name used by FilePublisher to exchange block confirmation messages in record mode.
Warning: You cannot specify both a confirmationSubject and an ECMSubscriberName.
PDS for partitioned data sets. This is the default.
SEQ for sequential data sets.
GDG for Generation Dataset Groups.
VSAM for Virtual Storage Access Method files.
Name of the input data set.The default is the INPUT_DATASET specified in the Options section.
For a PDS data set, this parameter is used in conjunction with polling. The input file must be moved, not copied, to an input data set to ensure that the Adapter does not open the file before the file is completely generated.
For VSAM files, this parameter allows you to indicate the cluster name or the path name if you are using VSAM alternate index to access the data.
Name of the process data set for this file type. The default is the PROCESS_DATASET specified in the Options section.
Name of the output data set for this file type. The default is the OUTPUT_DATASET specified in the Options section. This is used only for a PDS data set in conjunction with polling.
Record length of the file being published. If lineLength is not specified, the Adapter will use the catalog service to obtain the file attributes.
The default is false which means a log file will not be created.
Valid values: true, false.
The default is false which means a log file will not be created.
Valid values: true, false.
If the FilePublisher session is not a certified session, this parameter is ignored. If the FilePublisher session is specified as a certified session, the default for this parameter is true, meaning the file is published in certified mode. If you want to have a specific file published in non-certified (Reliable) mode, you can specify false.
Specify a value for this parameter to override the default value specified in the Options section of the configuration file.
runJCL or false—submit JCL only
alwaysDo or true—submit JCL and delete file
suppressJCL—do not submit JCL and delete file
suppressOnError—do not submit JCL and do not delete file.
Default is runJCL or false.
Applies to STRING fields. Set this parameter to true to have FilePublisher strip leading blanks from a STRING.
Applies to STRING fields. Set this parameter to true to have FilePublisher strip trailing blanks.
Identifies the record structure to FilePublisher. If this value is true, the fields in the records are assumed to be fixed length.
Identifies the record as having variable-length fields. The delimiter can be any unique character. If useFieldWidth is set to false, the default for this field is | (vertical bar).
Used by FilePublisher to identify which record to start with when publishing. It can be used to skip over header records in a file. If this parameter is not specified, FilePublisher starts at the first record in the file. This parameter is not used for VSAM data sets.
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 path file name for the alternate index for the cluster defined in the inputDataset. If more than one alternate index is defined for the cluster, the configuration must have vsamAltIndex defined for each path name.
MESSAGE_FIELDS Element
Use the MESSAGE_FIELDS element of the FileType section to configure any messages that are to be published.
To publish from a file with single record format (either delimited or fixed-width), define one MESSAGE_FIELDS element.
To publish from a file with multi-record format (a file with header and detail records), define one MESSAGE_FIELDS element for each record type using the constraint parameter.
The MESSAGE_FIELDS 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 messageItem Parameter
The messageItem parameter can identify a field with a constant value, a field from a fixed-width input record, or a field from a delimited input record. In any case, it uses the following tags:
Valid values: STRING, INTEGER, UNSIGNED INTEGER, SHORT, UNSIGNED SHORT, FLOAT, DOUBLE, BOOLEAN, and TIME. Default is STRING.
Valid values for EMS: STRING, INTEGER, SHORT, FLOAT, DOUBLE, BOOLEAN.
Note: When you specify TIME as the data type, FilePublisher gets the current system time and adds it to the TIBCO message. When FileSubscriber receives the message, it converts the time to a string that represents the time of the publishing system.
Specify OPAQUE to send a field untranslated. See Sending Data Untranslated (OPAQUE).
For COBOL numeric datatypes only, specify one of ZONED, BINARY, PACKED, COMP, COMP-1, COMP-2, COMP-3, or COMP-4 for numeric data. See Sending COBOL Numeric Data Types.
Note: Make sure isBinary is set to true for both OPAQUE and COBOL numeric data.
The default value is false, meaning the input numeric field is published as a FLOAT or INTEGER value depending on the type of the field. The datatypes COMP-1, COMP-2, and COMP-3 are published as FLOAT and COMP, COMP-4 as INTEGERs.
For a more accurate conversion, specify true, meaning a STRING data type will be published.
Allows you to emulate the COBOL equivalent of LOW-VALUES and HIGH-VALUES. Valid values:
LOW-VALUES -- Sets field’s value to binary zeros.
HIGH-VALUES -- Sets field’s value to binary X’FFFFFFFF’.
For a field with a constant value, add the following tag along with label and type.
Set this tag to true to specify that the field is a constant.
For a field from a fixed-width input record, add the following tags along with label and type to specify the field’s position within the record and the length of the field.
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.
For a field from a delimited input record, add the following tag along with label and type to specify the field’s location within the record.
Tags in the messageContainer Parameter
You can group message items into containers to form a nested message using the messageContainer parameter. Include the following tags along with the messageItem or other messageContainer that you want to group together.
Tags in the constraint Parameter
The adapter supports files with multiple record formats. If there is more than one record format, include the constraint parameter using the following tags:
Specifies that this message field definition should start a new message. If this tag is set to false, the TIBCO message created by the message field is combined with the previous TIBCO message. If there are no previous messages, a message is not created.
The default for RV is false, which means that a new message is not started.
The default is true for EMS and false for Rendezvous. Refer to Example 10, Nesting of Mapped Messages.
Specifies the value of the record identifier field. While publishing, this MESSAGE_FIELD format is used only if this value matches the record identifier field of the input record.
For a fixed width input record, add the following tags to the containerName, startNewMessage, and value tags.
For a delimited input record, add the following tag to the containerName, startNewMessage and value tags: