Configuring the Adapter : Usage Guidelines for Publisher and Subscriber

Usage Guidelines for Publisher and Subscriber
This section discusses the following usage guidelines that apply to both publisher and subscriber:
Pre-Processing and Post-Processing Files
You can execute a JCL command script before or after a file is published by FilePublisher, or before or after an output file is generated by FileSubscriber.
If you want to have a JCL command script executed before or after a file is published, or before or after an output file is generated, use the executeBeforeProcess parameter or the executeAfterProcess parameter in the FILE_OPTIONS element. These parameters may be used in either FilePublisher or FileSubscriber for any file type that you have configured. Specify a fully qualified PDS member name where the JCL command script is stored.
How executeBeforeProcess and executeAfterProcess Operate
When you specify executeBeforeProcess, the following occurs:
FilePublisher  When FilePublisher has a file that is to be published, and you have specified the executeBeforeProcess parameter, FilePublisher submits the specified JCL command script to the internal reader for execution. The data set name of the file to be published can be inserted into the JCL script by using the keyword %FILENAME%. If the %FILENAME% keyword is used, FilePublisher substitutes this variable with the actual data set name of the file to be published before submitting the job to the internal reader.
FileSubscriber  When FileSubscriber has an output file to be generated, and you have specified the executeBeforeProcess parameter, FileSubscriber submits the specified JCL command script to the internal reader for execution. The data set name of the output file to be written can be inserted into the JCL command script by using the keyword %FILENAME%. If the %FILENAME% keyword used, FileSubscriber substitutes this variable with the actual data set name of the file to be generated before submitting the job to the internal reader.
When you specify executeAfterProcess, the following occurs:
FilePublisher  When FilePublisher has finished publishing a file and you have specified the executeAfterProcess parameter, FilePublisher submits the specified JCL command script to the internal reader for execution. The data set name of the file that was published and the status of that operation can be inserted into the JCL command script by using the keywords %FILENAME% and %STATUS%.
If these keywords are used, FilePublisher replaces them as follows before submitting the job to the internal reader:
%FILENAME% is replaced by the actual data set name of the file published.
%STATUS% is replaced by the completion code of 0 if the file was published successfully. If there was an error in publishing the file, %STATUS% is replaced with the completion code of 8.
FileSubscriber When FileSubscriber has finished generating an output file, and you have specified the executeAfterProcess parameter, FileSubscriber submits the specified JCL command script to the internal reader for execution. The data set name of the output file to be written and the status of that operation can be inserted into the JCL command script by using the keywords %FILENAME% and %STATUS%.
If these keywords are used, FileSubscriber replaces them as follows before submitting the job to the internal reader:
%STATUS% is replaced by the completion code of 0 if the file was generated successfully. If there was an error in generating the file,%STATUS% replaced by the completion code of 8.
Examples for executeBeforeProcess and executeAfterProcess
The examples that follow show some typical uses of the executeBeforeProcess and executeAfterProcess parameters. Consider the following example from a sample FilePublisher configuration file:
FILE_OPTIONS = { filePrefix="TEST", fileExtension=".dat",
inputDataset="TIBCO.TEST.IN",
processDataset="TIBCO.TEST.PROCESS",
outputDataset="TIBCO.TEST.OUT",
useFilePolling="true", pollInterval="1000",
delimiter="|", startAtLine="1",
removeAfterProcess="false", messagesPerTransaction="2",
transactionDelay="5000", dataSetType="PDS",
executeBeforeProcess="TIBCO.TFA.JCL(PUBEXEBP)",
executeAfterProcess="TIBCO.TFA.JCL(PUBEXEAP)",
publishSubjectName="A.B", triggerSubjectName="A.D" }
The preceding example specification causes FilePublisher to submit the JCL in a data set named TIBCO.TFA.JCL(PUBEXEBP) to be submitted for execution before starting to publish the file, then submit the JCL in a data set named TIBCO.TFA.JCL(PUBEXEAP) to be submitted for execution after the file is published.
If the step specified in the TIBCO.TIBFA.JCL(PUBEXEBP) JCL is
 
//EXEBP EXEC PGM=EXEBP,PARM='%FILENAME%'
then the program EXEBP receives the name of the file to be published as a parameter.
If the step specified in the TIBCO.TIBFA.JCL(PUBEXEAP) JCL is
 
//EXEAP EXEC PGM=EXEAP,PARM='%FILENAME% %STATUS%'
then the program EXEAP receives the name of the file that is published and the status code as parameter.
Heartbeat Messages
Heartbeat messages are an option that you can configure to provide an indication that either FilePublisher or FileSubscriber is active. These messages can be monitored by TIBCO Hawk to send notification or alerts, or both, when FilePublisher or FileSubscriber goes down. Heartbeat messages are configured globally, in the Options section of the configuration file. This is true for both FilePublisher and FileSubscriber. Configuring a heartbeat message consists of enabling the option and specifying a heartbeat interval.
Operation
The heartbeat option of FilePublisher and FileSubscriber lets the Adapter publish a heartbeat message on a regular basis. Heartbeat messages are published with a subject that is created by the Adapter. The format of the subject is:
 
   _FILEADAPTER.<adaptername>.HEARTBEAT
Once heartbeat messages are configured, FilePublisher or FileSubscriber publishes a heartbeat message with the subject specified at the interval configured.
Parameters
To configure this option, use these two elements in the Options section:
1.
PUBLISH_HEARTBEAT —Enables heartbeat messages. The default value is false. To enable heartbeat messages, set this element to true.
2.
HEARTBEAT_TIME. If used, it specifies the interval between heartbeat messages. The default value is 60000 milliseconds, or 60 seconds.
Heartbeat Message Format
For FilePublisher, the format of the heartbeat message is FilePublisher start time and current time. Then, for each file type configured, the format is:
For FileSubscriber, the format of the heartbeat message is FileSubscriber start time and current time. Then, for each file type, the format is file prefix and file extension.
Block Transfer Mode
You may wish to publish a file without regard to its file structure. To do this, specify that the file is to be published, or subscribed to, in block mode. When a file is processed in block mode, the data from the file is read without regard to the field or record structure, and the data is published as a block. The size of the block can be specified, or you can accept the default value of 65,536 bytes.
Operation
When a file is published in block transfer mode, FilePublisher reads the file in blocks, as specified with the blockTransferSize, without additional processing of the data. The MESSAGE_ITEM element is not required, and is ignored.
When the data is received by FileSubscriber, the blocks are written to a progress file. When FileSubscriber receives the message with the subject specified in generateFileSubjectName, it writes the completed file to the output data set. The FILE_LINE element is not required, and is ignored.Need info for updating the description of ’generateFileSubjectName’.
When block transfer mode is enabled, the following tags are ignored for that file type in FileSubscriber:
Parameters
blockTransferMode — A value of true causes the file specified to be published in blocks of data without further processing of the data. The default value is false. When you set blockTransferMode to true, you may specify an endPublishSubject parameter for FilePublisher and you must specify generateFileSubjectName parameter for FileSubscriber.
blockTransferSize — This value specifies the block size, in bytes, that the Adapter uses to publish the file. The default value is 65536. This parameter is not used for FileSubscriber.
A file that is published in block transfer mode must be subscribed to in block transfer mode. Data received from a file that is published in block transfer mode does not have record or field characteristics; therefore the FILE_LINE element is not required and is ignored.
FileSubscriber can only generate a final output file when it receives a message with a subject that FileSubscriber has defined with the generateFileSubjectName parameter. The autoGenerateFile, appendDateTime, and generateFileOnNumMsgs parameters are not used to create the final output file for block transfer mode.
Publisher Parameter Options by FileType
This section defines the parameter options that are valid for each FileType mode. Not all parameter options work with each FileType mode; some parameters are used in common, others are only valid for certain FileTypes. Attempting to use a parameter option that is not supported by a FileType mode will result in an error message or incorrect operation.
The following are the common parameter options for Publisher used by all FileType modes:
 
Other parameter options that are valid for specific FileType modes are described in the tables below. These tables include:
ECM Block Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
messagesPer
Transaction
noWaitAfter
Confirmations
useExplicit
Confirmation
SFT Block Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
messagesPer
Transaction
noWaitAfter
Confirmations
useExplicit
Confirmation
ECM Record Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
messagesPer
Transaction
noWaitAfter
Confirmations
useExplicit
Confirmation
Normal Record Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
endPublish
DestinationName
messagesPer
Transaction
noWaitAfter
Confirmations
startPublish
DestinationName
trackingId
DestinationName
useExplicit
Confirmation
Subscriber Parameter Options by FileType
This section defines the parameter options that are valid for each FileType mode. Not all parameter options work with each FileType mode; some parameters are used in common, others are only valid for certain FileTypes. Attempting to use a parameter option that is not supported by a FileType mode will result in an error message or incorrect operation.
In general, the Subscriber does not support receipt of ECM Record Mode transmissions. ECM Record Mode is primarily designed to communicate with custom-defined TIBCO BusinessWorks applications.
The following are the common parameter options for Subscriber used by all FileType modes:
 
Other parameter options that are valid for specific FileType modes are described in the tables below. These tables include:
ECM Block Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
SFT Block Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
Normal Record Mode
A column containing "X" indicates the option is supported; blank indicates not supported.
Sequential
Fixed Block
Sequential
Variable Block
Generation
DataSets (GDG)
* Tracking notification via useTrackingId, trackingIdSubject, and trackingIdDestinationName is only performed for Record Mode files if the generateFileSubjectName or generateFileDestinationName option is also used.