JText meta-object structure

A JText meta-object has a hierarchical structure. The default top-level meta-object is named MO_JTextConnector_Default. Two attributes of the top-level meta-object, EventDataHandler and OutputDataHandler, represent child meta-objects that provide configuration information for the data handler that the connector uses. The connector uses the data handler to convert data between business objects and strings or byte arrays.

By default, both of these attributes specify the same data-handler meta-object (MO_DataHandler_DefaultNameValueConfig). This data-handler meta-object calls the NameValue data handler to actually convert the data. In other words, the delivered default configuration specifies that event and output file conversion use the same data handler. For information on instantiating a data handler, see the Data Handler Guide.

Note:
Because formatter usage has been deprecated in favor of data handler usage, the EventFormat and OutputFormat attributes that formerly represented a formatter have been removed from the MO_JTextConnector_Default meta-object. To use a formatter, you must:

For information on using a formatter, see the documentation for the 3.0.0 or 2.3.0 release of the JText connector.

Figure 5 shows the hierarchical structure for the default JText meta-objects and each attribute name and type.

Figure 5. Hierarchical Structure of the JText meta-object

Hierarchical Structure of the JText meta-object

Creating custom meta-objects

MO_JTextConnector_Default, as the top-level JText meta-object, contains configuration information and child meta-objects for the connector. You can create separate top-level meta-objects for each type of business object that the connector handles. These custom meta-objects can contain the same or different child meta-objects to configure the type of data handler. For example, to configure processing differently for the Customer and Item business objects, create the MO_JTextConnector_Customer and MO_JTextConnector_Item meta-objects, and design these top-level meta-objects to contain different data-handler meta-objects.

At initialization, the connector retrieves a list of its supported meta-objects and business objects from the integration broker. From the names of these objects, the connector determines which business objects have their own associated top-level meta-objects. At runtime, the connector matches the name of a request business object with one of its supported meta-objects to locate the appropriate configuration information.

For example, assume that the connector supports the following meta-objects:

and the following business objects:

When the integration broker sends a request Customer business object, the connector uses the configuration information specified in the MO_JTextConnector_Customer meta-object. When the integration broker sends a request Order business object, the connector uses the configuration information specified in the MO_JTextConnector_Default meta-object.

MO_JTextConnector_Default attributes

This section describes the attributes in the MO_JTextConnector_Default meta-objects.

Note:
All values in an attribute's DefaultValue property are case-sensitive. Directory information must specify the absolute path of a directory.

Table 7 and the following sections describe the functionality of each attribute in the MO_JTextConnector_Default meta-object. Among other information, this table includes the value provided for each simple attribute's DefaultValue property. You can replace the product-delivered value with your own value.

Table 7. Attributes in the MO_JTextConnector_Default meta-object definition

Attribute name Description
ArchiveDir
Specifies the absolute path of the Archive directory. The directory must already exist. The delivered default values are:
UNIX: /tmp/JTextConn/Default/archive

Windows:C:\temp\JTextConn\Default\Archive
BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.

DataEncoding
DataEncoding is the encoding to be used to read and write business object strings. If this property is not specified in the static meta-object, the connector tries to read or write the business object string without using any specific encoding. You can specify any Java-supported encoding set for this attribute.
DataProcessing Mode
This attribute provides new flexibility for reading and writing binary files. When set to Binary, this MO property enables JText to read and write binary files from the file system while calling the appropriate data handler interface for BO to byte array and vice versa transformations. The traditional setting for this is Text. In Text mode, the BO to String and vice versa data handler interface is used. When the property is not set, it defaults to Text. Binary mode should only be used with a data handler that appropriately implements the getBO(byte[]) and getByteArrayFromBO() methods.
DummyKey
This attribute exists to satisfy the requirement that one attribute in every business object definition have the Key property enabled.
EndBODelimiter
Specifies a delimiter that separates business objects within an input file. For more information on the EndBODelimiter attribute, see "Polling for specific business objects".


If you do not provide a default value during configuration and the DataProcessingMode is set to Text, the property defaults to the following value: <EndBO:BOName>. When DataProcessingMode is binary, the property defaults to the following value: FF01.

Note:
Since the NameValue data handler is set as the default data handler, the EndBODelimiter value is set to <EndBO:BOName>. If you would like to use another data handler, such as the Delimited data handler, you will have to specify the corresponding value. For the Delimited data handler, the string EOL is a valid EndBODelimitervalue.
EndOfFileDelimiter
When DataProcessingMode is binary, and FTPDataStructure is Record, both EndBODelimiter and EndOfFileDelimiter are used. This property is set to the hexadecimal byte that is used for the end of file marker in the record file. If it is not set, the default, FF02, is used.
EventDataHandler
Represents a child meta-object whose attributes provide configuration values for the data handler to be used for event processing (business object string converted to business object). The delivered default value is MO_DataHandler_DefaultNameValueConfig
EventDir
Specifies the absolute path of the Event directory. The directory must already exist. If you create separate meta-objects for different business objects, and you specify the same EventDir path for both, you must specify unique values for the EventExt attribute in each meta-object. For more information, see "Specifying event directories and extensions". To configure the connector to use a remote FTP file system for event processing, specify the FTP URL in this attribute. Optionally, you can use this attribute to specify the following additional information in the URL:
  • the id and password of a user with privileges to connect to the FTP server and perform FTP operations; if not specified in EventDir, must be specified in FTPUserId and FTPPassword.
  • the FTP port; if not specified in EventDir, the connector uses the default FTP port.
  • the remote event directory; if not specified in EventDir, the connector polls the event files from the directory to which the connection is established to the FTP server.

Syntax for specifying FTP information in the EventDir attribute is:

ftp://[UserId:password@]FTPserver[:port][RemoteEventDirectory]

For more information, see "Remote event processing". To specify local file information in the EventDir attribute, use the full path of the file. Alternately, you can use a FILE URL, which uses the following format:

[file://]FullPathname

The delivered default values are:

UNIX: /tmp/JTextConn/Default/event

Windows:C:\temp\JTextConn\Default\Event
BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.

Note:
A new Connector-specific boolean property, "NoPoll", has been introduced, to optionally turn off polling. The default value is false. When set to true, the adapter only processes requests and does not poll.
EventExt
Specifies the extension of the file used for event notification. If no value is specified, the JText connector polls for files with no file extension. For more information, see "Specifying multiple event files or multiple event directories".
Note:
The use of an asterisk (*) for this attribute to specify that the connector poll for all files in a single event directory regardless of their extension is no longer supported.
The delivered default value is in.
FailArchiveExt
Specifies the file extension used to archive business objects that were not successfully processed. For more information, see "Specifying event archiving". The delivered default value is fail.
FileSeqEnabled
Specifies filename sequencing, which outputs each business object to a separate file. The file's name includes a unique sequence number. For more information, see "Specifying request processing". The delivered default value is true.
FixedBOSize

When present with a valid value, this meta-object property overrides the EndBODelimiter property, and provides users an alternative to the traditional delimiter based BO parsing.

FTPArchiveDir
Specifies the relative path of the archive directory on the FTP server. The directory must already exist. There are several options for using this attribute to specify archiving:
  • Specifying a value for this attribute but no value for the FTPRenameExt attribute causes the connector to append a timestamp to the event filename and move it to the FTP server archive directory specified in this attribute.
  • Specifying a value both for this attribute and the FTPRenameExt attribute causes the connector to rename the processed event filename with a timestamp and the value specified in FTPRenameExt, and move it to the FTP server archive directory specified in this attribute.
  • Specifying no value either for this attribute or the FTPRenameExt attribute causes the connector to delete the processed event file without archiving it.
  • Specifying no value for this attribute but specifying a value for the FTPRenameExt attribute causes the connector to rename the processed event file, adding a timestamp and the value specified in FTPRenameExt, and move it to the directory specified in the EventExt attribute.
  • Specifying / (slash) for this attribute but no value for the FTPRenameExt attribute causes the connector to move the processed event file to the root directory on the FTP server.
  • Specifying / (slash) for this attribute and a value for the FTPRenameExt attribute causes the connector to rename the processed event filename with the extension specified in FTPRenameExt, and move it to the root directory on the FTP server.

For more information, see "Specifying event archiving". There is no delivered default value for this attribute.
BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.

FTPDataStructure
This attribute is of type String. The user can specify the FTP data structure (either File or Record) to get or put files from or to the remote site. If nothing is specified, Jtext will use 'File as default value
FTPEventFileMask
Uses embedded wildcard characters to specify the mask or prefix of remote FTP files for event processing. Specify a value for this attribute only to identify the file mask on a mainframe that does not adhere to the same naming standards that apply to UNIX or Windows systems. Using wildcard characters in the file name enables you to specify multiple files for event processing. For example, you can use the following format to specify multiple event files: ACT.Z1UC.INPT*For more information, see "Identifying files on a mainframe: Optional configuration". There is no delivered default value.


If you are polling, you should provide a very specific mask. For example, if you want to poll all the following event files: USER.JTEXT.TEST001.EVENT, USER.JTEXT.TEST002.EVENT, USER.JTEXT.TEST003.EVENT, USER.JTEXT.TEST004.EVENT, and the FTPArchiveDir is set as / or left blank, and the FTPRenameExt is set as RENAME, then these files would get archived as the following: USER.JTEXT.TEST001.RENAME, USER.JTEXT.TEST002.RENAME, USER.JTEXT.TEST003.RENAME. So, if you provide an FTPEventFileMask=USR.JTEXT.TEST*.*, all the events would get picked up on the first poll. All the archived files would get picked up at the next poll, since even they conform to the same file mask. In order to avoid this, you must provide a very specific mask. For example, like USR.JTEXT.TEST*.EVENT, so that USR.JTEXT.TEST*.RENAME is not picked up during polling.

Note:
Do not specify a mask that is applicable for both event files and archived files.

BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.
FTPFileListingFormat
Specifies the format in which the JText connector should expect file information to appear when reading in files. This enables the connector to read in files in different locales where date and time information may be stored in different orders within the file format information. To configure the connector to use the format for your locale, specify a semicolon-delimited series of characters that represent the order in which file attributes occur; below is a list that associates the possible characters with the file attributes they represent.
P Permission L Links U User G Group S Size D Date M Month T Time N Name
A suitable value for this attribute, then, might be P:L:U:G:S:D:M:T:N.
FTPGetQuantity
Determines the number of files retrieved from the remote FTP URL with each remote poll.
FTPKeepConnectionOpen
Set the Default Value property of this attribute to the value true to cause the JText connector to maintain its connection with an FTP site. If this attribute is set to the value true then the connector only closes the connection when the connector terminates or if the FTP server closes the connection itself (due to a configured timeout, for instance). The connector checks to make sure that the connection is still alive each time it performs a remote operation in order to handle the situation when the FTP server might have closed the connection due to a timeout. If the connection has been closed then the connector re-establishes it. Set the Default Value property of this attribute to the value false to cause the JText connector to open a connection with the FTP server each time it performs an operation and to close the connection when it is finished. Configuring the connector to keep the connection alive can improve the performance of the connector when performing request processing on FTP sites.
FTPLocalEventDir
Specifies the local system directory into which the connector downloads event files from the FTP site. You must specify a value for this attribute to enable the connector to process events using FTP. For more information, see "Specifying the local directory". There is no delivered default value.
BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.
FTPOSPlatform
Use this attribute only if configuring the connector to use a remote FTP file system where the remote FTP server is an MVS platform. In this case, specify the value of this attribute as MVS. Case is not significant. For more information, see "Specifying a remote FTP file system". There is no delivered default value.
FTPPassword
Specifies the password of the user who has privileges to connect to the FTP server and perform FTP operations. You need not specify a value for this attribute if the password is included in the URL specified in the EventDir or OutputDir attribute. For more information, see "Specifying the FTP URL and login information". There is no delivered default value for this attribute.
FTPPollTerminateIfServerDown

Specifies the behavior of the connector when configured to poll the FTP site for events and the FTP site is unavailable. If the Default Value property of the FTPPollTerminateIfServerDown attribute is set to the value true and the FTP site is unavailable when the connector attempts a poll call, then the connector terminates. If the Default Value property of the FTPPollTerminateIfServerDown attribute is set to the value false and the FTP site is unavailable when the connector attempts a poll call, then the connector does not terminate.
There is no delivered default value.

FTPRenameExt

Specifies the file extension or suffix that the connector uses to rename the remote FTP file after the connector has polled for it. Renaming the file prevents the connector from polling the same file in the next poll cycle. Alternatively, you can configure the connector to rename the processed event file and move it to an archive directory. For more information, see the FailArchiveExt attribute. For more information, see "Identifying files on a mainframe: Optional configuration". There is no delivered default value.

FTPRequestTerminateIfServerDown

Specifies the behavior of the connector when configured to perform request processing and communicate with an FTP site, and the FTP site is unavailable. If the Default Value property of the FTPRequestTerminateIfServerDown attribute is set to the value true and the FTP site is unavailable when the connector attempts to perform request processing, then the connector terminates. If the Default Value property of the FTPRequestTerminateIfServerDown attribute is set to the value false and the FTP site is unavailable when the connector attempts to perform request processing, then the connector does not terminate.
There is no delivered default value .

FTPTransferType

This JText meta-object property is used during both event and request processing. The possible values for this property are Binary and ASCII. The property dictates the transfer type JText will use when remotely placing or retrieving files from an FTP server. When the property does not exist, the adapter behavior defaults to Binary.

FTPUserId
Specifies the name of the user who has privileges to connect to the FTP server and perform FTP operations. You need not specify a value for this attribute if the UserId is included in the URL specified in the EventDir or OutputDir attribute. The connector ignores this attribute if it does not find an FTP URL in the EventDir attribute (during event processing) or OutputDir attribute (during request processing). For more information, see "Specifying the FTP URL and login information". There is no delivered default value for this attribute.
IncludeEndBODelimiter
Specifies whether or not the value specified for the EndBODelimiter meta-object attribute is included in the string written to a file by the JText connector. If the Default Value property of this attribute is set to true then the connector includes the value specified for the EndBODelimiter attribute when it writes files. If the Default Value property of this attribute is set to false then the connector does not include the value specified in the EndBODelimiter attribute when it writes files.
LargeObject
A flag used to turn on the large object optimization features of JText adapter (when set to true). Setting this flag to true will result in the following changes in the behavior of the archiver:
  1. If an event file has multiple business objects, the archiving will be done only after all the business objects for that event file are processed.
  2. The original file will not be archived in case the processing of all business objects in that event file results in failure or unsubscribed status.

Also an extra log file will be created internally for keeping track of the archive status.

MVSSiteCommand
Used for issuing MVS FTP site commands. The site command should be specified without SITE or QUOTE keywords. An example for site command value is:LRECL=<value> BLKSIZE=<value>, where <value> represents the site command arguments passed.
ObjectEventID
Placeholder not used by the connector in a meta-object but required by the integration broker. This attribute must be the last attribute in the meta-object. There is no delivered default value.
OriginalArchiveExt
Specifies the file extension used to archive the original event file, which preserves the entire event file for reference in case any of its business objects fail processing or are unsubscribed. For more information, see "Specifying event archiving". The delivered default value is orig.
OutputDataHandler
Represents a child meta-object whose attributes provide configuration values for the data handler to be used for service call requests (business object converted to business object string). The delivered default value is MO_DataHandler_DefaultNameValueConfig
OutputDir
Specifies the absolute path of the Output directory. The directory must already exist. To configure the connector to use a remote FTP file system for request processing, specify the FTP URL in this attribute. Optionally, you can use this attribute to specify the following additional information in the URL:
  • the UserId and password of a user with privileges to connect to the FTP server and perform FTP operations; if not specified in EventDir, must be specified in FTPUserId and FTPPassword.
  • the FTP port; if not specified in OutputDir, the connector uses the default FTP port.
  • the remote output directory; if not specified in OutputDir, the connector loads request files into the default connection directory (the directory on the FTP server to which the connection is established).

Syntax for specifying FTP information in the OutputDir attribute is:ftp://[UserId:password@]FTPserver[:port]For more information, see "Remote request processing". To specify local file information in the OutputDir attribute, use the full path of the file. Alternately, you can use a FILE URL, which uses the following format:

[file://]FullPathname

The delivered default values are: UNIX: /tmp/JTextConn/Default/out

Windows:c:\temp\JTextConn\Default\Out
BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.

OutputExt
Specifies the extension of the file used for request processing. The delivered default value is out.
Note:
If OutputFileName contains no extension, but the OutputExt attribute does contain an extension, the output file is generated with both the file name and the extension. If neither contain an extension, the output file is generated without one.
OutputFileName
Specifies the name and path of the output file into which the connector writes the incoming business object during request processing. If the OutputDir attribute contains a valid output directory, the output file is generated into the specified directory. For more information, see "Specifying the name of the output file".
Note:
If OutputFileName and OutputExt attributes do not contain an extension, the output file is generated without an extension.
The delivered default value is Native.
BiDi supported. If the BiDi format used in the target platform is different from the Windows 2003 format, values for these meta-data attributes will be transformed.
PartialArchiveExt
Specifies the file extension used to archive the successfully processed business objects (when the event file contains multiple business objects, not all of which process successfully). For more information, see "Specifying event archiving". The delivered default value is partial.
StagingDir
Specifies a directory in which the connector should write files to before moving them into the directory specified by the OutputDir attribute. This is designed to handle environments where other software processes might be monitoring and manipulating the directory into which the JText connector outputs files (such as an FTP process that detects files created by the connector and moves them to another location). In situations such as this, there is a risk that the external process could move the file before it has been completely written. You can specify a staging directory in the StagingDir attribute, therefore, so that the connector writes the file completely to the staging directory and then moves it to the output directory when it is finished, eliminating the risk of the external process picking up an incomplete file.
It is recommended that the staging directory and output directory be on the same file system or drive to accommodate different operating systems' approaches to file moving operations. Note that the StagingDircan be a remote directory.


There is no delivered default value.


BiDi supported for Windows. All BiDi enabled properties will be transformed from Windows BiDi format into the BiDi.Metadata format, which is an e-Mail connector standard property.

SuccessArchiveExt
Specifies the file extension used to archive all successfully processed business objects. For more information, see "Specifying event archiving". The delivered default value is success.
UnsubscribedArchiveExt
Specifies the file extension used to archive all unsubscribed business objects. For more information, see "Specifying event archiving". The delivered default value is unsub.

Note:
Attributes FTPTransferType, FTPDataStructure, DataProcessingMode, EndOfFileDelimiter, and FixedBOSizeare not part of the JText meta-object as delivered. To use these attributes, they need to be explicitly added to the meta-object and their default values must be set.

Specifying the name of the output file

There are three ways to specify the name of the output file:

There are several ways to use the OutputFileName attribute to specify the name of the output file:

Note:
If the connector is processing more than one type of business object and OutputFileName is set to a string other than Native, each business object must have its own top-level meta-object, which specifies a unique output filename. For example, the meta-object used by the Customer business object might be MO_JTextConnector_Customer, and the meta-object used by Item might be MO_JTextConnector_Item. Set the value of the OutputFileName attribute in each of these meta-objects to a unique value.

Native is a reserved word.

For more information, see "Specifying request processing".

Copyright IBM Corporation 1997, 2004. All Rights Reserved.