CScript FT Object Function Reference

Contents

1. Overview

2. File Transfer Initiation Functions

3. File Transfer Utility Functions

4. File Transfer Property Get Functions

5. File Transfer Property Set Functions

6. File Transfer Callback Functions

1. Overview

This reference is intended to be a guide to the functions that constitute the main interface to the File Transfer functionality currently contained within TinyTERM user interface.

These functions constitute the public file transfer interface. This permits the sending and receiving of files, and the setting and getting of a limited set of file transfer properties. Aside from filenames and directories, all transfers are configured from the existing properties in the current session's .TPX file. This includes whether or not transfer status screens are displayed, whether or not TinyTERM should exit when a transfer is complete and all other options that are able to be set from the User Interface, .TPX file or programmatically. All the property set and get functions operate on the these properties, meaning that if they are changed programatically or through the user interface, they will update the file transfer dialogs when they are next used and if the .TPX file is saved, these properties will be saved into it

File Transfer Session Management
File transfer maintains its own list of FT sessions. Most of these sessions are associated with emulator sessions, with the exception of FTP file transfers, which are never linked to an emulator session. Only one file transfer can be run per session, with the above noted exception of FTP. The maximum number of file transfers (FTP and otherwise) is currently 20, and is defined as twice the number of maximum TE sessions (currently 9) plus 1.)

Sample File Transfer Script
The following is a simplified file transfer script using the FTP protocol. The script connects to the host using the username and password specified. It then sends and receives a file.

FTSetProtocol("FTP"); //Sets the file transfer protocol

FTSetHostName("255.255.255.255"); //Sets the host name that you would like to connect to

FTSetUsername("testuser"); //Sets the user name to be used for login

FTSetPassword("userpassword"); //Sets the password to be used for login

FTSetSync(1); //Pauses script execution until after the transfer is finished

FTSend("c:\\autoexec.bat", ".", 0); //Sends the autoexec.bat file to the current directory on the host

FTGet("/usr/testuser/test.fil", "."); //Gets the test.fil file from the host and places it in the current working
//directory on the PC

2. File Transfer Initiation Functions

These are functions that are used mainly to start an initial file transfer.

FTSend(sFiles, sRemotedir,iDlgID);
FTSend will send one or more files to a remote system. The behavior of this command differs depending upon the arguments passed and the protocol being used. In the case of FTP file transfers, this function will create a new file transfer object and associate it with the current session. This is because FTP file transfers are not associated with an emulator session.

sFiles names the files which are to be sent. These must be space separated. If a filename or its path contains a space, it should be enclosed within double quotes. For example, the file
c:\program files\Century\test.txt

needs to be enclosed within quotes

"c:\program files\Century\test.txt"

so that it is not treated as two files

(c:\program and files\Century\test.txt)

sRemotedir Names the remote directory in which received files are placed. This is optional, and is valid only for the following protocols:
WTERMCRC
FTP

Using these two protocols, the sending side will determine where to place received files. This overrides the receiver's local destination directory. If it is not specified, the current directory of the receiver is used.

In all other cases, the remote host will determine where the files should be placed when received.

iDlgID This value is reserved for internal functions and should always be set to 0.

FTRecv(sFile,sDirectory);
FTRecv will passively receive one or more files from a remote sender. In the case of FTP file transfers, this function will eventually create a new file transfer object and associate it with the current session. This is because FTP file transfers are not associated with an emulator session.

sFile names the file which is to be received. This is valid only for the following protocols:
XMODEM
XMODEM-CRC

In all other cases, the filename is passed along as part of the protocol. The filename specified in sFile is overridden by the sender's filename when using these protocols.

sDirectory names the directory in which files that are received are placed. This is overridden by the remote side when using WTERMCRC.

FTGet(sFileList,sDirectory);
FTGet will actively retrieve files from a remote host computer. In the case of FTP file transfers, this function will eventually create a new file transfer object and associate it with the current session. This is because FTP file transfers are not associated with an emulator session.

sFileList Names the files which you wish to receive. These must be space separated. If a filename or its path contains a space, it should be enclosed within double quotes. For example, the file
c:\program files\Century\test.txt

needs to enclosed within quotes

"c:\program files\Century\test.txt"

so that it is not treated as two files

(c:\program and files\Century\test.txt)

sDirectory names the directory into which the received files are placed.

FTGet works only with the following protocols:

TERMCRC

WTERMCRC

FTP

When FTGet is used with any of the other protocols (i.e., XMODEM), the result is the same as if FTRecv was used.
When using FTGet with the FTP protocol, multiple file receives are not possible when the files are explicitly listed. For example, passing the following string as the sFileList parameter will result in a "Cannot Read Remote Directory" error: "ftptest/connect.gif ftptest/testfile.txt". However, wildcards can be used, as in "ftptest/*.gif" or "ftptest/*.txt", but cannot be combined as in "ftptest/*.txt ftptest/*.gif" passed as one argument.

3. File Transfer Utility Functions

These functions are a collection of miscellaneous utilities that perform common tasks necessary when setting up a file transfer operation.
FTGetProtocolName(nProtocolIndex);
FTGetProtocolName will return the name of the protocol (as a string) associated with the index passed in. This is useful when setting the FT ActiveX object's protocol property which takes a name rather than an index.

nProtocolIndex The 1-based index of the protocol name you wish to retrieve. The value stored in the .TPX file is zero-based, meaning that you must add one to it before calling this function.

FindSessionFromFTObj(ft);
This function returns the zero-based index of the FT session associated with the passed in FT ActiveX object. It returns –1 if it cannot find a session. See also the public variable section for a description of the variables that make up the FT sessions.

ft The ft ActiveX object that you wish to find the associated FT session for.

FindFTFromStatus(oDlg);

oDlg The status dialog object that you wish to find the associated FT object for.

This function returns the ActiveX FT object associated with a given file transfer status dialog object. It returns nil if it cannot find an associated FT object.

FindSessionByFT(oFT);

oFT The ft ActiveX object that you wish to find the associated TE session for.

4. File Transfer Property Get Functions

FTGetRemoteDir();
This function returns the currently set remote directory to be used for file sends. It is retrieved from the first field of the list contained in property 214 FTDefSend. (The properties are defined later in this doc.)

FTGetUserName();
This function returns the user name as a string that is to be used for FTP file transfers. It takes into account the setting of property 264 FTPLogType, (properties are defined later in this doc.) meaning that it will return different values based on the setting of this property.

FTGetPassword();
This function returns the decrypted password as a string that is to be used for FTP file transfers. It takes into account the setting of property 264 FTPLogType, (properties are defined later in this doc.) meaning that it will return different values based on the setting of this property.

FTGetHostName();
This function returns the host name as a string that is to be used for FTP file transfers. It takes into account the setting of property 349 UseFTPCurHost, (properties are defined later in this doc.)meaning that it will return different values based on the setting of this property.

FTGetProtocolID();
This function returns the zero-based file transfer protocol ID from property 99 xprot(properties are defined later in this doc.). When one is added to this value, it can be passed to FTGetProtocolName to retrieve the name of the protocol that can then be used to set the FT ActiveX object's protocol property.

FTGetSendFileList();
This function returns the list of files that are to be sent for the current transfer. This is the contents of property 265 LastSendSrc (properties are defined later in this doc.).

5. File Transfer Property Set Functions

These functions allow the programmer to set basic properties relating to common file transfer situations. All the functions below will, when called, set not only the current file transfer parameters, but will set the properties saved in the .TPX file which includes those that show up on the file transfer dialogs.

FTSetSync(bOn); FTSetSync will turn on and off the synchronous transfer of files, meaning that when it is on, script will not execute until the current file transfer has completed. If you wish to turn on synchronous file transfers, you must do so before EACH transfer.

bOn	set to true to turn on synchronous file transfers, false to turn it off.

FTSetAsciiMode(bOn); FTSetAsciiMode will turn on and off ASCII CR/LF conversion.

bOn	set to true to turn on ASCII CR/LF conversion, false to run in binary mode

FTSetXferStat(bOn); FTSetXferStat turns on and off the file transfer status screen during a transfer.

bOn	set to true to display the status screen, false to turn it off. This variable is set to true by default.

FTSetPassword(sPassword); FTSetPassword sets the password used for FTP file transfers. When this is called, it will automatically set FTP to use its own login and password, as opposed to being anonymous or using the emulator login and password.

sPassword	is the password to be set.

FTSetUsername(sUser); FTSetUsername sets the user name used for FTP file transfers. When this is called, it will automatically set FTP to use its own login and password, as opposed to being anonymous or using the emulator login and password.

sUser	is the user name to be set.

FTSetHostname(sHost); FTSetHostname sets the host name used for FTP file transfers. When this is called, it will automatically set FTP to use its own host name instead of the current emulation host name.

sUser	is the user name to be set.

FTSetProtocol(sProtocol); FTSetProtocol sets the protocol to be used for the next file transfer.

SProtocol	is a string value that is the protocol to be used for file transfers. This must be one of the following values: TERMCRC WTERMCRC FTP XMODEM XMODEM-CRC YMODEM ZMODEM KERMIT ASCII LINE

FTSetCompression(bCompress); FTSetCompression turns on and off file transfer compression.

bCompress	is a boolean true or false value. TRUE for compression on, FALSE for compression off.

6. File Transfer Callback Functions

These functions are designed to be overridden by a CSL programmer to insert custom code into the chain of events that happen when a file transfer occurs.

FTStartSend(oFT, nSess);
FTStartSend is a callback function that is triggered when a file transfer SEND or XFER is initiated. More precisely, it occurs as the first when the internal callback function ft_StartBatchSend is called, which itself is fired by the FT ActiveX control when a SEND or XFER operation is performed.

oFT is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTEndSend(oFT, nSess);
FTEndSend is a callback function that is triggered when a file transfer SEND of XFER has finished. Specifically, it is called first in the internal callback function ft_EndBatchSend, which is fired by the FT ActiveX control when a SEND or XFER operation has completed.

oFT is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTStartReceive(oFT, nSess);
FTStartReceive is a callback function that is triggered when a file transfer GET or RECV has been started. Specifically, it is called first in the internal callback function ft_StartBatchReceive, which is fired by the FT ActiveX control when a GET or RECV operation has been initiated.

oFT is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTEndReceive(oFT, nSess);
FTEndReceive is a callback function that is triggered when a file transfer GET or RECV has finished. Specifically, it is called first in the internal callback function ft_EndBatchReceive, which is fired by the FT ActiveX control when a GET or RECV operation has completed.

oFT is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTSetProtocol("FTP");	//Sets the file transfer protocol
FTSetHostName("255.255.255.255");	//Sets the host name that you would like to connect to
FTSetUsername("testuser");	//Sets the user name to be used for login
FTSetPassword("userpassword");	//Sets the password to be used for login
FTSetSync(1);	//Pauses script execution until after the transfer is finished
FTSend("c:\\autoexec.bat", ".", 0);	//Sends the autoexec.bat file to the current directory on the host
FTGet("/usr/testuser/test.fil", ".");	//Gets the test.fil file from the host and places it in the current working //directory on the PC


sFiles	names the files which are to be sent. These must be space separated. If a filename or its path contains a space, it should be enclosed within double quotes. For example, the file c:\program files\Century\test.txt needs to be enclosed within quotes "c:\program files\Century\test.txt" so that it is not treated as two files (c:\program and files\Century\test.txt)

sRemotedir	Names the remote directory in which received files are placed. This is optional, and is valid only for the following protocols: WTERMCRC FTP Using these two protocols, the sending side will determine where to place received files. This overrides the receiver's local destination directory. If it is not specified, the current directory of the receiver is used. In all other cases, the remote host will determine where the files should be placed when received.

iDlgID	This value is reserved for internal functions and should always be set to 0.

FTRecv(sFile,sDirectory); FTRecv will passively receive one or more files from a remote sender. In the case of FTP file transfers, this function will eventually create a new file transfer object and associate it with the current session. This is because FTP file transfers are not associated with an emulator session.

sFile	names the file which is to be received. This is valid only for the following protocols: XMODEM XMODEM-CRC In all other cases, the filename is passed along as part of the protocol. The filename specified in sFile is overridden by the sender's filename when using these protocols.

sDirectory	names the directory in which files that are received are placed. This is overridden by the remote side when using WTERMCRC.

FTGet(sFileList,sDirectory); FTGet will actively retrieve files from a remote host computer. In the case of FTP file transfers, this function will eventually create a new file transfer object and associate it with the current session. This is because FTP file transfers are not associated with an emulator session.
sFileList	Names the files which you wish to receive. These must be space separated. If a filename or its path contains a space, it should be enclosed within double quotes. For example, the file c:\program files\Century\test.txt needs to enclosed within quotes "c:\program files\Century\test.txt" so that it is not treated as two files (c:\program and files\Century\test.txt)

sDirectory	names the directory into which the received files are placed.
FTGet works only with the following protocols: TERMCRC WTERMCRC FTP When FTGet is used with any of the other protocols (i.e., XMODEM), the result is the same as if FTRecv was used. When using FTGet with the FTP protocol, multiple file receives are not possible when the files are explicitly listed. For example, passing the following string as the sFileList parameter will result in a "Cannot Read Remote Directory" error: "ftptest/connect.gif ftptest/testfile.txt". However, wildcards can be used, as in "ftptest/.gif" or "ftptest/.txt", but cannot be combined as in "ftptest/.txt ftptest/.gif" passed as one argument.

These functions are a collection of miscellaneous utilities that perform common tasks necessary when setting up a file transfer operation. FTGetProtocolName(nProtocolIndex); FTGetProtocolName will return the name of the protocol (as a string) associated with the index passed in. This is useful when setting the FT ActiveX object's protocol property which takes a name rather than an index.

nProtocolIndex	The 1-based index of the protocol name you wish to retrieve. The value stored in the .TPX file is zero-based, meaning that you must add one to it before calling this function.

FindSessionFromFTObj(ft); This function returns the zero-based index of the FT session associated with the passed in FT ActiveX object. It returns –1 if it cannot find a session. See also the public variable section for a description of the variables that make up the FT sessions.

ft	The ft ActiveX object that you wish to find the associated FT session for.

FindFTFromStatus(oDlg);
oDlg	The status dialog object that you wish to find the associated FT object for.
This function returns the ActiveX FT object associated with a given file transfer status dialog object. It returns nil if it cannot find an associated FT object.

FindSessionByFT(oFT);
oFT	The ft ActiveX object that you wish to find the associated TE session for.

FTStartSend(oFT, nSess); FTStartSend is a callback function that is triggered when a file transfer SEND or XFER is initiated. More precisely, it occurs as the first when the internal callback function ft_StartBatchSend is called, which itself is fired by the FT ActiveX control when a SEND or XFER operation is performed.

oFT	is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess	is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTEndSend(oFT, nSess); FTEndSend is a callback function that is triggered when a file transfer SEND of XFER has finished. Specifically, it is called first in the internal callback function ft_EndBatchSend, which is fired by the FT ActiveX control when a SEND or XFER operation has completed.
oFT	is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess	is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTStartReceive(oFT, nSess); FTStartReceive is a callback function that is triggered when a file transfer GET or RECV has been started. Specifically, it is called first in the internal callback function ft_StartBatchReceive, which is fired by the FT ActiveX control when a GET or RECV operation has been initiated.

oFT	is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess	is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.

FTEndReceive(oFT, nSess); FTEndReceive is a callback function that is triggered when a file transfer GET or RECV has finished. Specifically, it is called first in the internal callback function ft_EndBatchReceive, which is fired by the FT ActiveX control when a GET or RECV operation has completed.

oFT	is the actual FT ActiveX object that is performing the transfer in question. This can be used to get information from the control, check error status or even change parameters (though this is not recommended, and doesn't work with all settings.)

nSess	is the numeric index of the TT session that is currently associated with this transfer. This can be used to check properties of the session, display information to the TE control, change sessions or any number of other things. This parameter will be set to -1 in the case of FTP file transfers, as these are not directly associated with a single session.