FTP Server Object

Sends and retrieves files from an FTP server. Use the FTP Control to copy files between a local client and any FTP server.

note

File transfers use all available bandwidth to minimize the time it takes to transfer a file or buffer.

note

The default transfer type of this object depends on which version of iCore Integration Suite is installed. For more information, see FTP Server Object::Type.

note

The implementation of this object assumes that the remote FTP server uses the same default transfer type. Setting the Type property of this object to the default transfer type prior to the first file transfer in a session will not have any effect, since the implementation assumes that the server will use the default transfer type anyway.

If the FTP server does not use ASCII as default transfer type and the first file transfer should be in ASCII, send a TYPE command (use FTP Server Object::SendCommand) to set transfer type to ASCII. Example: ftpServerObject.SendCommand (CommandText: 'TYPE A', Return value: sReturnValue).

If the FTP server does not use Image as default transfer type and the first file transfer should be in Image, send a TYPE command (use FTP Server Object::SendCommand) to set transfer type to Image. Example: ftpServerObject.SendCommand (CommandText: 'TYPE I', Return value: sReturnValue).

Sections

Init, Main, Procedures, OnExit, and Structure.

note

The object is declared in the Declare section.

Properties

Name	Description
AllocateRequired	Indicates whether space must be allocated on a server as part of the Store method.
BufferSize	Specifies the size (in bytes) of data buffer used in data transfer.
ConcurrentConnections	Specifies the number of concurrent connections to the server opened for receiving files. Applicable only when using FTPType transfer type.
Directory	Working directory on the server.
IncomingSpeedLimit	The maximum number of bytes per second that may be received. A value of 0 (zero) means unlimited.
LocalDataPort	Restricts the local data port to a value or range compatible with your firewall.
LocalAddress	Address of the local host in dot notation.
LocalPort	Port number that the socket is bound to.
OutgoingSpeedLimit	The maximum number of bytes per second that may be sent. Value of 0 (zero) means unlimited.
Passive	Indicates how the data connection is to be formed.
ProxyType	The type of proxy server used for this connection.
ProxyHost	Specifies the name or address of the proxy server that requests are to be routed through.
ProxyPort	Specifies the port used by proxy server that requests are to be routed through.
ProxyUsername	Username to be sent on all requests through a proxy server that requires authentication.
ProxyPassword	Password to be sent on all requests through a proxy server that requires authentication.
RemoteAddress	Returns the address of the remote host in dot notation (i.e. nnn.nnn.nnn.nnn) when the State property is FTPState_Connected.
RemotePort	Returns the port number of the remote host when the State property is FTPState_Connected.
State	Status of the FTP connection.
StoreType	Type of store that will be performed when the Store method is called.
System	Type of operating system used by the server.
Timeout	Timeout in milliseconds.
TransferMode	Transfer mode to be used for subsequent file transfers.
Type	Data type to be used for subsequent file transfers.
UseFEATCommand	Specifies whether to send FEAT command to the server.
UseIPv6	Specifies whether IPv6 should be used.
UseMLSD	Specifies whether to use MLSD command for directory listing.
VirtualHostName	Name of the host to send using the HOST command.
ObjectIsEmpty	Returns 1 if object is not created.
LastReturnCode	Returns last known return code from object.

note

Properties ObjectIsEmpty and LastReturnCode are common methods. For more information see Common properties and methods.

Methods

Name	Description
Login	Login to FTP server.
Logout	Logout from FTP server.
SendCommand	Sends a command to the server.
StartTraceToFile	Starts tracing to file.
StartTraceToSimpleStringList	Starts tracing to a simple string list.
StopTrace	Stops tracing to file or simple string list.
Status	Sends the STAT command to the server.
List	Fetches a file directory listing.
NameList	Fetches a file directory listing with names only.
ChangeDirectoryUp	Sets the working directory to the parent directory.
DeleteFile	Deletes a file on the server.
RenameFile	Renames a file on the server.
MakeDirectory	Creates a directory on the server.
RemoveDirectory	Deletes a directory on the server.
MGet	Retrieves (gets) multiple files.
MPut	Stores (puts) multiple files.
Store	Stores (puts) a file.
Retrieve	Retrieves (gets) a file.
CreateObject	Creates a new instance of the object.
FreeObject	Releases the instance of the object.

note

Methods CreateObject and FreeObject are common methods. For more information see Common properties and methods.

Properties

---

AllocateRequired

Indicates whether space must be allocated on a server as part of the Store method.

Type: ParamTypeBool
Default: False_Value
Read: get__AllocateRequired
Write: put__AllocateRequired

See Also

FTP Server Object::Store

---

BufferSize

Specifies the size (in bytes) of data buffer used in data transfer.

Type: Integer
Default: 262144
Read: get_BufferSize
Write: put_BufferSize

---

ConcurrentConnections

Specifies the number of concurrent connections to the server opened for receiving files. Applicable only when using FTPType transfer type.

Type: Integer
Default: -
Read: get_ConcurrentConnections
Write: put_ConcurrentConnections

---

Directory

Working directory on the server.

Type: String
Default: ''
Read: get_Directory
Write: put_Directory

See Also

FTP Server Object::ChangeDirectoryUp

---

IncomingSpeedLimit

The maximum number of bytes per second that may be received. A value of 0 (zero) means unlimited.

Type: Integer
Default: -
Read: get_IncomingSpeedLimit
Write: put_IncomingSpeedLimit

---

LocalDataPort

Restricts the local data port to a value or range compatible with your firewall.

Type: String
Default: 0
Read: get_LocalDataPort
Write: put_LocalDataPort

Remarks

The default value, "0", indicates that any port may be used. When set to a single value, such as "20", only that port will be used. When set to a range of values, such as "1024:1028", successive ports in this range will be tried until one can be opened. Use this property if for some reason the client machine is limited in the ports that can be used to make data connections. This is often the case in intranet environments where clients are restricted or firewalled for security purposes. When using this property it is recommended to specify a range of ports, if at all possible. The reason is that many FTP servers do not allow connections to a port unless a period of time has elapsed since the last connection to this port.

See Also

FTP Server Object::LocalPort

---

LocalAddress

Address of the local host in dot notation.

Type: String
Default: ''
Read: get_LocalAddress
Write: -

Remarks

When the State property is FTPState\_Connected, LocalAddress returns the address of the local host in dot notation (for example, nnn.nnn.nnn.nnn). When not connected, it returns an empty string.

See Also

FTP Server Object::LocalPort
FTP Server Object::State
FTP Server Object::RemotePort

---

LocalPort

Port number that the socket is bound to.

Type: Integer Default: -
Read: get_LocalPort
Write: -

Remarks

When the State property is FTPState\_Connected, LocalPort returns the port number that the socket is bound to. When not connected, it returns 0.

See Also

FTP ServerObject::LocalDataPort FTP Server Object::LocalAddress FTP Server Object::RemotePort

---

OutgoingSpeedLimit

The maximum number of bytes per second that may be sent. Value of 0 (zero) means unlimited.

Type: Integer
Default: 0 (unlimited) Read: get_OutgoingSpeedLimit
Write: put_OutgoingSpeedLimit

---

Passive

Indicates how the data connection is to be formed.

Type: ParamTypeBool
Default: True_Value
Read: get_Passive
Write: put_Passive

---

ProxyType

The type of proxy server used for this connection.

Type: FTPProxyType
Default: FTPProxy_None
Read: get_ProxyType
Write: put_ProxyType

See Also

FTPProxyType
FTP Server Object::ProxyHost
FTP Server Object::ProxyPort
FTP Server Object::ProxyUsername
FTP Server Object::ProxyPassword

---

ProxyHost

Specifies the name or address of the proxy server that requests are to be routed through.

Type: String
Default: ''
Read: get_ProxyHost
Write: put_ProxyHost

See Also

FTPProxyType
FTP Server Object::ProxyType
FTP Server Object::ProxyPort
FTP Server Object::ProxyUsername
FTP Server Object::ProxyPassword

---

ProxyPort

Specifies the port used by proxy server that requests are to be routed through.

Type: Integer
Default: -
Read: get_ProxyPort
Write: put_ProxyPort

---

ProxyUsername

Username to be sent on all requests through a proxy server that requires authentication.

Type: String
Default: ''
Read: get_ProxyUsername
Write: put_ProxyUsername

See Also

FTPProxyType
FTP Server Object::ProxyType
FTP Server Object::Host
FTP Server Object::ProxyPort
FTP Server Object::ProxyPassword

---

ProxyPassword

Password to be sent on all requests through a proxy server that requires authentication.

Type: String
Default: ''
Read: get_ProxyPassword
Write: put_ProxyPassword

See Also

FTPProxyType
FTP Server Object::ProxyType
FTP Server Object::Host
FTP Server Object::ProxyPort
FTP Server Object::ProxyUsername

---

RemoteAddress

Returns the address of the remote host in dot notation (i.e. nnn.nnn.nnn.nnn) when the State property is FTPState_Connected.

Type: String
Default: ''
Read: get_RemoteAddress
Write: -

See Also

FTP Server Object::LocalAddress

---

RemotePort

Returns the port number of the remote host when the State property is FTPState_Connected.

Type: String
Default: ''
Read: get_RemotePort
Write: -

See Also

FTP Server Object::LocalPort

---

State

Status of the FTP connection.

Type: FTPStateType
Default: -
Read: get_State
Write: -

---

StoreType

Type of store that will be performed when the Store method is called.

Type: FTPStoreType
Default: -
Read: get_StoreType
Write: put_StoreType

See Also

FTP Server Object::Store

---

System

Type of operating system used by the server.

Type: String
Default: -
Read: get_System
Write: -

---

Timeout

Timeout in milliseconds for a command.

Type: Integer
Default: 30000
Read: get_Timeout
Write: put_Timeout

---

TransferMode

Transfer mode to be used for subsequent file transfers. Available transfer modes are:

• FTPTransferType_Stream
• FTPTransferType_Block
• FTPTransferType_Compressed

For detailed descriptions, see FTPTransferModeType.

Type: FTPTransferModeType
Default: FTPTransferType_Stream
Read: get_TransferMode
Write: put_TransferMode

warning

Only supports transfer mode: stream (default). Setting any other value will result in a runtime error.

See Also

FTPTransferModeType
FTP Server Object::Store
FTP Server Object::Retrieve
FTP Server Object::MPut
FTP Server Object::MGet

---

Type

Data type to be used for subsequent file transfers. Available types are:

• FTPType_Ascii
• FTPType_Image
• FTPType_Ebcdic
• FTPType_Zip

For detailed descriptions, see FTPType.

Type: FTPType
Default:
FTPType_Ascii (for iCIS versions earlier than 3.30.5)
FTPType_Image (for iCIS version 3.30.5 and later)
Read: get_Type
Write: put_Type

warning

Only supports types: ASCII and Image. Setting any other value will result in a runtime error.

See Also

FTPType
FTP Server Object::Store
FTP Server Object::Retrieve
FTP Server Object::MPut
FTP Server Object::MGet

---

UseFEATCommand

Specifies whether to send FEAT command to the server.

Type: ParamTypeBool
Default: True_Value
Read: get_UseFEATCommand
Write: put_UseFEATCommand

Remarks

The FEAT command is used by the FTP client to determine what extended features the FTP server supports.

---

UseIPv6

Specifies whether IPv6 should be used.

Type: ParamTypeBool
Default: False_Value
Read: get_UseIPv6
Write: put_UseIPv6

---

UseMLSD

Specifies whether to use MLSD command for directory listing.

Type: ParamTypeBool
Default: False_Value
Read: get_UseMLSD
Write: put_UseMLSD

---

VirtualHostName

Name of the host to send using the HOST command.

Type: String
Default: -
Read: get_VirtualHostName
Write: put_VirtualHostName

Remarks

The value of this property specifies the name of the host that the FTP client needs to get to when connecting to a server that supports multiple virtual host names. The property should be set before the call to the Login method.

---

Methods

---

Login

Login to FTP server.

Parameters

ServerName	Type: String Description: Specifies the name or IP address of the server.
Username	Type: String Default: '' Description: Specifies a user name for an account on the server.
Password	Type: String Default: '' Description: Specifies the account password associated with User.
RemotePort	Type: Integer Default: 21 Description: Specifies the remote port to connect to.
Account	Type: String Default: '' Description: Specifies an account on the server.

See Also

FTP Server Object::Logout
FTP Server Object::State

---

Logout

Logout from FTP server.

Parameters

-

See Also

FTP Server Object::Login

---

SendCommand

Sends a command to the server.

Parameters

CommandText	Type: String Description: The command text.
Return value	Type: String Description: The response from the server.

---

StartTraceToFile

Starts tracing to file.

Parameters

Filename	Type: ParamTypeFilepath Description: File path for trace file.

Remarks

Starts trace of FTP communication. You can trace to either a Simple String List Object or to a file on disk. It is not possible to trace to both a file and a string list at the same time. If StartTraceToFile is called followed by a StartTraceToSimpleStringList, the trace to file will end.

note

To make the trace file more suitable for presentation, use the custom Node Type FTP trace. For more information, see FTP TraceFormat.

See Also

FTP Server Object::StartTraceToSimpleStringList
FTP Server Object::StopTrace

---

StartTraceToSimpleStringList

Starts tracing to a simple string list.

Parameters

TraceSend	Type: ParamTypeBool Default: False_Value Description: A True_Value value indicates that sent data is to be traced.
TraceReceive	Type: ParamTypeBool Default: True_Value Description: A True_Value value indicates that received data is to be traced.
SendPrompt	Type: String Default: '' Description: Prompt to precede sent data.
ReceivePrompt	Type: String Default: '' Description: Prompt to precede received data.
Return value	Type: Simple String List Object Description: Returns a Simple String List Object for trace data.

Remarks

Starts trace of FTP communication. You can trace to either a Simple String List Object or to a file on disk. It is not possible to trace to both a file and a string list at the same time. If StartTraceToFile is called followed by a StartTraceToSimpleStringList, the trace to file will end.

See Also

FTP Server Object::StartTraceToFile
FTP Server Object::StopTrace
Simple String List Object

---

StopTrace

Stops tracing to a file or a simple string list.

Parameters

-

See Also

FTP Server Object::StartTraceToFile
FTP Server Object::StartTraceToSimpleStringList

---

Status

Sends the STAT command to the server.

Parameters

PathName	Type: String Default:" Description: See Remark below.
Return value	Type: String Default: '' Description: String variable where the reply from the server is to be placed.

Remarks

PathName argument:
If the argument is a path name, this method is analogous to the List method. If a partial path name is given, the server may respond with a list of filenames or attributes associated with that specification. If no argument is given, the server should return general status information about the server FTP process (this should include current values of all transfer parameters and the status of connections).

---

List

Fetches a file directory listing.

Parameters

PathName	Type: String Default:" Description: If empty, the current server directory is used. Property Directory.
Return value	Type: IEObjectFTPListingInterface Default: '' Description: The FTP Listing Object to receive the directory listing.

Remark

The server sends name and supplementary information on each file found within the specified PathName.

See Also

FTP Server Object::Directory
FTP Server Object::NameList
FTP Directory Listing Object

---

NameList

Fetches a file directory listing with names only.

Parameters

PathName	Type: String Default:" Description: If empty, the current server directory is used. Property Directory.
Return value	Type: Simple String List Object Description: The String List Object to receive the listing.

Remark

Gets a file directory listing without file attributes. The server sends a filename for each file found within the PathName specified.

See Also

FTP Server Object::Directory
FTP Server Object::List
Simple String List Object

---

ChangeDirectoryUp

Sets the working directory to the parent directory.

Parameters

-

See Also

FTP Server Object::Directory

---

DeleteFile

Deletes a file on the server.

Parameters

FilenamePath	Type: String Description: Specifies the file to delete.

See Also

FTP Server Object::RemoveDirectory
FTP Server Object::RenameFile

---

RenameFile

Renames a file on the server.

Parameters

FromFilename	Type: String Description: Specifies the old filename and path.
ToFilename	Type: String Description: Specifies the new filename and path.

See Also

FTP Server Object::DeleteFile

---

MakeDirectory

Creates a directory on the server.

Parameters

DirectoryPath	Type: String Description: Specifies the absolute or relative directory path.

See Also

FTP Server Object::RemoveDirectory

---

RemoveDirectory

Deletes a directory on the server.

Parameters

DirectoryPath	Type: String Description: Specifies the absolute or relative directory path.

See Also

FTP Server Object::MakeDirectory

---

MGet

Retrieves multiple files from the server.

Parameters

Source	Type: String Description: Specifies a list of files and directories to retrieve from the server. Wildcards are allowed, and multiple paths may be specified when separated by a space. Any path with a space must be enclosed within quotes. If using wildcards (*) -> Source is interpreted by the FTP server. The FTP server may return a recursive list of files but the directory structure will not be recreated locally.
Destination	Type: ParamTypeFilepath Description: Any path with a space must be enclosed within quotes. Must be a valid path.
FileErrors Optional	Type: Pointer to Simple String List Description: A Simple String List Object variable containing a list of files, with corresponding errors, that failed to be retrieved.
FilesTransferred Optional	Type: Pointer to Simple String List Description: A Simple String List Object variable containing a list of files that were successfully retrieved.

See Also

FTP Server Object::Store
FTP Server Object::MPut
FTP Server Object::Retrieve Simple String List Object

---

MPut

Stores multiple files on the server.

Parameters

Source	Type: ParamTypeFilepath Description: Specifies a list of files and directories to store on the server. Wildcards are allowed, and multiple paths may be specified when separated by a space. Any path with a space must be enclosed within quotes. If using wildcards () -> All files matching the wildcard () will be stored in the specified directory on the FTP server.
Destination	Type: String Description: Specifies a destination directory. Any path with a space must be enclosed within quotes. Defaults to current server directory.
FileErrors Optional	Type: Pointer to Simple String List Object Description: A Simple String List Object variable containing a list of files, with corresponding errors, that failed to be stored.
FilesTransferred Optional	Type: Pointer to Simple String List Object Description: A Simple String List Object variable containing a list of files that were successfully stored.

See Also

FTP Server Object::Store
FTP Server Object::MGet
FTP Server Object::Retrieve
Simple String List Object

---

Store

Stores a file on the server.

Parameters

RemoteFileName	Type: String Description: Specifies the remote filename (with path) to store, store unique or append to. Remark: If StoreType is UniquNoPrefix, specifiying a RemoteFilename will result in a runtime error.
SourceType	Type: FTPSourceType Default: FTPSourceFilepath Description: Type of source. Depending of the value of this parameter either parameter SourceFilename or SourceData must be filled in.
SourceFilename	Type: [ParamTypeFilepath]../CommonDataTypes.md#paramtypefilepath) Default: Description: If parameter SourceType is FTPSourceFilepath this parameter is the filepath to the source..
SourceData	Type: String Default: '' Description: If parameter SourceType is FTPSourceString this parameter is the data to be stored in the file.

See Also

FTP Server Object::MPut
FTP Server Object::MGet
FTP Server Object::Retrieve
FTPSourceType

---

Retrieve

Retrieves a file from the server.

Parameters

RemoteFileName	Type: String Default: Description: Specifies the remote filename (with path) to retrieve.
DestType	Type: FTPDestinationType Default: FTPDestinationFilepath Description: Type of destination. Depending of the value of this parameter either parameter DestFilename or DestData must be filled in.
DestFilename	Type: [ParamTypeFilepath]../CommonDataTypes.md#paramtypefilepath) Default: Description: If parameter DestType is FTPDestinationFilepath this parameter is the filepath to the destination.
DestData	Type: Pointer to String Default: Description: If parameter DestType is FTPDestinationString this parameter is the variable where the data from the remote file is to be stored.

See Also

FTP Server Object::MPut
FTP Server Object::MGet
FTP Server Object::Store
FTPDestinationType