Home > Class Reference > ENSLIB namespace > EnsLib.File.InboundAdapter


class EnsLib.File.InboundAdapter extends Ens.InboundAdapter, EnsLib.File.Common

Finds files in a FilePath directory and submits all that match a FileSpec wildcard to an associated BusinessService for processing within Ensemble

Property Inventory

Method Inventory


parameter SERVICEINPUTCLASS = %Stream.Object;
parameter SETTINGS = RegistryID:Basic:selector?context={Ens.ServiceRegistry.External.ContextSearch/Services?Protocols_1=File},FilePath:Basic:directorySelector,FileSpec:Basic,ArchivePath:Basic:directorySelector,WorkPath:Basic:directorySelector,SubdirectoryLevels,Charset::selector?context={Ens.ContextSearch/CharacterSets},AppendTimestamp,ConfirmComplete,FileAccessTimeout,SemaphoreSpec;
Inherited description: List of properties can be set as settings in the configuration file format is a comma separated list of property names


property AppendTimestamp as %String [ InitialExpression = 1 ];
Append a timestamp to Archive and Working filenames in order to prevent possible name collisions on repeated processing of the same filename.

If this value is empty or 0, no timestamp will be appended. If it is 1, then the standard timestamped filename specification template '%f_%Q' will be used.

Any other value will be used directly as a timestamped filename specification template.

Property methods: AppendTimestampDisplayToLogical(), AppendTimestampGet(), AppendTimestampIsValid(), AppendTimestampLogicalToDisplay(), AppendTimestampLogicalToOdbc(), AppendTimestampNormalize(), AppendTimestampSet()
property ArchivePath as %String (MAXLEN = 1000);
Path to move a file to after processing is completed. If not given, the file will be deleted after processing is completed. Note that the AppendTimestamp option must be used to avoid name collisions in the archive directory if the same filename will be retrieved repeatedly.
Property methods: ArchivePathDisplayToLogical(), ArchivePathGet(), ArchivePathIsValid(), ArchivePathLogicalToDisplay(), ArchivePathLogicalToOdbc(), ArchivePathNormalize(), ArchivePathSet()
property Charset as %String [ InitialExpression = "Native" ];
Character encoding scheme used for translating input from files. For binary input, use 'Binary'. Other choices include:
Native - the default character encoding of the installed locale of the Ensemble server
latin1 - the ISO Latin1 8-bit encoding
ISO-8859-1 - the ISO Latin1 8-bit encoding
UTF-8 - the Unicode 8-bit encoding
Unicode - the Unicode 16-bit encoding (Little-Endian)
UnicodeBig - the Unicode 16-bit encoding (Big-Endian)
@<ttable> - <ttable> means a raw InterSystems character translation table name. A prefix of '@' means to use the named table.
Property methods: CharsetDisplayToLogical(), CharsetGet(), CharsetIsValid(), CharsetLogicalToDisplay(), CharsetLogicalToOdbc(), CharsetNormalize(), CharsetSet()
property ConfirmComplete as %Integer (DISPLAYLIST = ",None,Size,Rename,Readable,Writable", VALUELIST = ",0,1,2,4,8") [ InitialExpression = "4" ];
Special measures to confirm complete receipt of a file, in case it is still being written at the time we detect it in the FilePath directory.

- 'Size' means wait until the size reported for the file in the FilePath directory listing stops increasing.
This option alone may not be sufficient when the source application is sluggish. If the OS reports the same size for the file for a duration of the FileAccessTimeout value then Ensemble will consider the file complete.
- 'Rename' means keep trying to read more data for a file until the OS allows us to rename it. If WorkPath or ArchivePath is different from FilePath, this option is implied because the file must be moved which is equivalent to renaming. This option may not be effective because it is common for an OS to allow Ensemble to rename a file even while another application has the file open and is still writing more data into it.
- 'Readable' means if we consider the file complete if we are simply able to open it in Read mode. Depending on the OS and the details of the process that puts the file in the FilePath directory where we find it, this may be enough although in many cases it isn't.
- 'Writable' means if we consider the file complete if we are able to open it in Write mode (as a test - we generally don't intend to write to it.). This may be enough depending on the OS and the details of the process that puts the file in the FilePath directory where we find it.

Property methods: ConfirmCompleteDisplayToLogical(), ConfirmCompleteGet(), ConfirmCompleteIsValid(), ConfirmCompleteLogicalToDisplay(), ConfirmCompleteNormalize(), ConfirmCompleteSet()
property DeleteFromServer as %Boolean [ InitialExpression = 1 ];
Specifies whether or not to delete files from the local file server after successful processing
If not deleted, the adapter will ignore files already processed until something else deletes them
Property methods: DeleteFromServerDisplayToLogical(), DeleteFromServerGet(), DeleteFromServerIsValid(), DeleteFromServerLogicalToDisplay(), DeleteFromServerNormalize(), DeleteFromServerSet()
property FileAccessTimeout as %Integer [ InitialExpression = 2 ];
Amount of idle time to wait before abandoning our attempt to confirm complete access to a file we've found (see the ConfirmComplete option)
Property methods: FileAccessTimeoutDisplayToLogical(), FileAccessTimeoutGet(), FileAccessTimeoutIsValid(), FileAccessTimeoutLogicalToDisplay(), FileAccessTimeoutNormalize(), FileAccessTimeoutSet()
property FilePath as %String (MAXLEN = 1000) [ Required ];
Path to directory to look for files in - may be prefixed with @MyAgent:
Property methods: FilePathDisplayToLogical(), FilePathGet(), FilePathIsValid(), FilePathLogicalToDisplay(), FilePathLogicalToOdbc(), FilePathNormalize(), FilePathSet()
property FileSpec as %String (MAXLEN = 400) [ InitialExpression = "*" ];
Wildcard filename to look for; may be a semicolon-separated list of wildcards.
Property methods: FileSpecDisplayToLogical(), FileSpecGet(), FileSpecIsValid(), FileSpecLogicalToDisplay(), FileSpecLogicalToOdbc(), FileSpecNormalize(), FileSpecSet()
property SemaphoreSpec as %String (MAXLEN = 400);
This is the Semaphore file specification to control when to process files found that match 'File Spec'.
The Default is empty which means process files when the Confirm Complete requirement is met.
If specified the files matching File Spec will not be processed until a corresponding semaphore file has been detected in the same directory.
The semaphore sepcification can be a wildcard filename pairing of target=semaphore filename e.g.
ABC*.TXT=ABC*.SEM which means do not process any files found that match ABC*.TXT unless a corresponding ABC*.SEM exists for each one.

Multiple pairings are separated by ;
The target pattern is case sensitive and the semaphore pattern case sensitivity will be OS dependent
e.g. *.TXT=*.SEM will only be applied to target files found ending with capitalized .TXT but the OS may not differentiate between *.SEM and *.sem

If a singleton is specified e.g. *.SEM or READY.SEM then that is taken as the semaphore pattern for all files. The following are equivalent:
*.SEM *=*.SEM
If no wildcard is used in the semaphore pattern then the semaphore pattern is taken as the file name and will be used for the one polling interval.
If such a semaphore file appears during the middle of a polling interval it will not be used until the start of polling interval.
This is to prevent deletion of the semaphore file before all relevant files are processed.

If a semaphore pattern is specified and a file found based on File Spec does not have a semaphore pattern match then the file will not be processed unless an * is specified as the last semaphore pattern.

The same semaphore check is carried out at all subdirectory levels.

Confirm Complete setting is still applied but if a semaphore file is specified then you can consider changing Confirm Complete setting to None

If a File Spec of * is specified along with a semaphore file then the semaphore file will not be processed by the Adapter as a target file but only as a semaphore file.

Semaphore files are deleted after all target files found during the polling interval are processed and those target files are marked for deletion.
Property methods: SemaphoreSpecDisplayToLogical(), SemaphoreSpecGet(), SemaphoreSpecIsValid(), SemaphoreSpecLogicalToDisplay(), SemaphoreSpecLogicalToOdbc(), SemaphoreSpecNormalize(), SemaphoreSpecSet()
property SubdirectoryLevels as %Integer (MINVAL = 0) [ InitialExpression = 0 ];
Number of levels of subdirectory depth under the FilePath directory that should be searched for files matching the FileSpec pattern.
Property methods: SubdirectoryLevelsDisplayToLogical(), SubdirectoryLevelsGet(), SubdirectoryLevelsIsValid(), SubdirectoryLevelsLogicalToDisplay(), SubdirectoryLevelsNormalize(), SubdirectoryLevelsSet()
property VMSLatestVersionOnly as %Boolean [ InitialExpression = 1 ];
Property methods: VMSLatestVersionOnlyDisplayToLogical(), VMSLatestVersionOnlyGet(), VMSLatestVersionOnlyIsValid(), VMSLatestVersionOnlyLogicalToDisplay(), VMSLatestVersionOnlyNormalize(), VMSLatestVersionOnlySet()
property WorkPath as %String (MAXLEN = 1000);
Path to move a file to while it is being processed. If not given, the file will not move while in process.

This setting is useful when the same filename is used for repeated file submissions.

Property methods: WorkPathDisplayToLogical(), WorkPathGet(), WorkPathIsValid(), WorkPathLogicalToDisplay(), WorkPathLogicalToOdbc(), WorkPathNormalize(), WorkPathSet()


method IsVMSLatestVersion(pFilename As %String) as %Boolean
method OnInit() as %Status
Inherited description: This user callback method is called just after %OnNew()
method OnTask() as %Status