For example, the FILE_OPTIONS element shown below consists of parameters with values, separated by commas:
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).
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.
|
|
|
|
|
|
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.
|
|
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.
|
|
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 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.
|
•
|
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.
|
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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 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:
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.
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.
•
|
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.
--Node Publisher UserId Subscriber Mapped -- UserId
|
|
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.
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.
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.
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.
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:
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.
|
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.
|
|
|
|
|
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:
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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.
|
|
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.
|
|
|
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:
|
|
|
|
|
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.
|
|
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.
|
|
|
|
|
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.
|
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.
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.
|
|
|
|
|
|
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.
|
|
|
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: