Learning
Documentation
Community
Open Exchange
Global Masters
Home / Class Reference / ENSLIB namespace / EnsLib.FTP.InboundAdapter
Private  Storage   

EnsLib.FTP.InboundAdapter


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

Adapter that receives files via the FTP protocol.

Inventory


Parameters Properties Methods Queries Indices ForeignKeys Triggers
2 26 16


Summary


Properties
%CredentialsObj %SFTPPassphraseCredentialsObj %WarnedLatest %completeFileSpec
%currentFileSpec %fileSpecHasMulti %logTransfers %multiFileSpec
AppendTimestamp ArchivePath BusinessHost CallInterval
Charset CommandTranslateTable ConfirmComplete ConnectTimeout
Credentials DeleteFromServer FTPPort FTPServer
FileAccessTimeout FilePath FileSpec FileSpecDelimiter
FilenameExpression IsDirExpression KeepaliveInterval Protocol
RegistryID SFTPAuthenticationMethods SFTPFileAccessMode SFTPInteractiveDTL
SFTPPassphraseCredentials SFTPPrivateKeyFile SFTPPublicKeyFile SFTPSetFileAccessModeByClient
SSLCheckServerIdentity SSLConfig SemaphoreSpec ServerListStyle
SizeExpression StayConnected SubdirectoryLevels TimestampExpression
TranslateTable UseFileStream UsePASV VMSLatestVersionOnly
WorkPath

Methods
%AddToSaveSet %ClassIsLatestVersion %ClassName %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Extends
%GetParameter %IsA %IsModified %New
%NormalizeObject %ObjectModified %OriginalNamespace %PackageName
%RemoveFromSaveSet %SerializeObject %SetModified %ValidateObject
AssignOneSetting AuthenticateSSH ClearAllAppData ClearRuntimeAppData
ClearStaticAppData Connect ConnectSSH CorrespondingSemaphoreExists
CreateTimestamp DeepListClose DeepListExecute DeepListFetch
Disconnect EnumerateSettingsClose EnumerateSettingsExecute EnumerateSettingsFetch
FileLikePattern FileListClose FileListExecute FileListFetch
FileListSSHClose FileListSSHExecute FileListSSHFetch GenerateSemaphoreFilename
GetSettings IsVMSLatestVersion LinkFileStream NormalizeDirectory
OnKeepalive SFTPPassphraseCredentialsSet SemaphoreFileExists System
TakeFromCol TestConnection TestConnectionSSH delete
fixPath rename retrieveFile testPaths


Parameters


• parameter DOMAIN = "Ensemble";
Use our own domain for localization
• parameter SETTINGS = "RegistryID:Basic:selector?context={Ens.ServiceRegistry.External.ContextSearch/Services?Protocols_1=FTP},FilePath:Basic,DeleteFromServer:Basic,FileSpecDelimiter:Basic,UseFileStream,-WorkPath,ServerListStyle,-SFTPFileAccessMode,-SFTPSetFileAccessModeByClient";
List of properties can be set as settings in the configuration file format is a comma separated list of property names

Properties


• property %completeFileSpec as %String [ Transient ];
When multiple wildcards in the File Specification this contains the original File Specification setting value
• property %currentFileSpec as %String [ Transient ];
When multiple wildcards in the File Specification this is the current file specification being used
• property %fileSpecHasMulti as %Boolean [ InitialExpression = 0,Transient ];
Internal flag to indicate multiple wild cards in FileSpec
• property %multiFileSpec as %String [ MultiDimensional ];
• property AppendTimestamp as %String [ InitialExpression = 1 ];
Append a timestamp to Archive 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 ArchivePath as %String(MAXLEN=1000);
Path on the InterSystems IRIS server to save a copy of each file received from the FTP server. If not given, the local copy of the file will be stored in a temporary location and then 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 Charset as %String [ InitialExpression = "Binary" ];
FTP - Use the named Character encoding to translate characters from the file.
A * prepended to any of the charset names will cause a binary FTP transfer with the resulting data then translated using the specified encoding.
Note that Binary should be chosen for binary files and other cases when special characters such as line terminators must be preserved.
Other settings may be useful when transferring text documents via FTP.

Choices include:
Binary - binary transfer
Ascii - Ascii mode FTP transfer but no character encoding translation
Native - the default character encoding of the installed locale of the InterSystems IRIS 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 ConfirmComplete as %Integer(DISPLAYLIST=",None,Size,Rename,Size & Rename",VALUELIST=",0,1,2,3") [ InitialExpression = "1" ];
Confirm complete receipt of file if possible, in case it is not completely available on the server at the time downloading begins.

'None' offers the fastest performance for small files because no extra FTP directory listing needs to be retrieved for each file download attempt

'Size' means keep reading more data for a file until the file size reported by the server directory listing does not increase
This option is only reliable for Charset='binary' transfers (In text mode the file position used for downloading may get corrupted by the insertion or removal of Linefeed characters)
This option alone may not be sufficient if the FTP server or source application is sluggish. If the server reports the same
size for the file 2 times in a row, 2 seconds apart, then InterSystems IRIS will consider the download complete. Therefore the 'Size & Rename' setting is preferable if the server supports 'Rename'.
This option relies on correct results from the Adapter.SizeExpression string set in the OnInit() method of the Business Service.

'Rename' means keep trying to read more data for a file until the server allows us to rename it
This option will only work if the FTP server grants Rename privilege to InterSystems IRIS for the download directory, using the Credentials
configured on this adapter, and if the file permissions on the file itself are set so that the FTP server has privilege to rename it.
If not then the Rename attempt will always fail and the InterSystems IRIS download will never complete

• property DeleteFromServer as %Boolean [ InitialExpression = 1 ];
Specifies whether or not to delete files from the FTP server after successful processing
If not deleted, the adapter will ignore files already processed until something else removes them from the FTP server.
• property FilePath as %String(MAXLEN=1000) [ Required ];
Directory on the FTP server in which to effect FTP operations.
• property FileSpec as %String(MAXLEN=2000);
Filename or wildcard file specification for file(s) to retrieve from the FTP server Multiple file specifications can be entered separated by a delimiter. It is necessary to enter the delimiter used in the File Specification Delimiter setting. Enter the FileSpec as one line. Maximum length is 2000 characters.
• property FileSpecDelimiter as %String;
If this is non empty then it will be used as the delimiter to split the File Specification setting into multiple filename/wild card searches.
• property FilenameExpression as %String;
Expression for extracting the filename portion of a line of the FTP directory listing (%line)
• property IsDirExpression as %String;
Expression for extracting the is-a-directory flag from the FTP directory listing (%line)
• property ServerListStyle as %String(VALUELIST=",Unix,MSDOS,AS/400,VMS,VMSAllVersions,NetWare") [ InitialExpression = "Unix" ];
Type of listing format returned by the FTP server.

'VMSAllVersions' means on VMS FTP servers, retrieve all versions listed, not only the latest VMS version of the file
This value is not pertinent if the protocol is SFTP.

• property SizeExpression as %String;
Expression for extracting the file size from the FTP directory listing (%line); if present used for detecting download complete status
• property StayConnected as %Numeric(MINVAL=-1,VALUELIST=",0,-1") [ InitialExpression = -1 ];
If zero, disconnect from the remote FTP server between attempts to retrieve a directory listing. A value of -1 means never disconnect.
• property TimestampExpression as %String;
Expression for extracting the timestamp portion of a line of the FTP directory listing (%line)
• property UseFileStream as %Boolean [ InitialExpression = 0 ];
Should the adapter construct a FileStream or a GlobalStream for data received?
Note that regardless of this setting a FileStream will be used if ArchivePath or ArchiveIO is set.

Methods


• classmethod TakeFromCol(s, col)
• method delete(pFilename As %String, pFileDir As %String) as %Boolean
• method rename(pFilename As %String, pNewFilename As %String, pFileDir As %String) as %Boolean
• method retrieveFile(pFilename As %String, pStream As %AbstractStream, pFileDir As %String, pRetry As %Boolean) as %Status
• method testPaths(pOnInit As %Boolean = 1) as %Status