iFTP "Intelligent FTP" Version 3.3 (c) copyright 1997-2006 Santronics Software Inc contact: support@santronics.com Updated: February 23, 2006 ================================= iFTP Script Language Introduction ================================= iFTP offers a powerful, yet easy to learn, enhanced FTP script language to create and run sophiscated and robust FTP automated sessions. The #1 clear enhancement of iFTP over typical standard FTP commands is the extra script commands in iFTP to perform logical conditions and copy/move from a target to source with the ability to check for errors. But iFTP is basically a "DOS LIKE" language with many similar capabilities that you have in DOS batch files. iFTP views the remote ftp site as a "special drive" ftp: which you can use to distinguish which directories are being used, local DOS drive or the remote FTP "drive". A powerful example of how you can use the iFTP script language is the ability to check for the existence of a file before proceeding with more commands, or you may wish to download multiple files and delete each file if the file download is successful, thus preventing duplicate downloads during restarts. The iFTP script language offers similar standard FTP commands but enhanced and easier to use. For example, the FTP get and mget commands were combined as one extended GET command; you can define your host name, userid and password all on the same OPEN command; and you can call other scripts recursively. You can use the new COPY or MOVE commands like in DOS to perform file transfers. iFTP scripts are flat ascii text files which you can create using a normal text editor. Example Scripts: examples.zip contains an assortment of examples using the iFTP script language. ftphub.zip contains a batch file and script to handle the FTP HUB operations for Platinum Xpress Customers with various FTP Mail Server Hubs on the internet. ============================================================ Required iFTP Files, Log file and Script locations ============================================================ In order to run iFTP, the follow files are required (bare mininum) in the same location IFTP.EXE is located: REQUIRED iftp.exe REQUIRED iftplp.dll REQUIRED iftp.ini INI file for iFTP | REQUIRED ssreg.ini Registration file (OBSELETE as of v3.0) OPTIONAL iftphelp.txt For console mode help display REQUIRED** wininet.dll Microsoft's Winsock Internet Library (** See WININET.DLL section below) iFTP can be placed in a PATH directory and iFTP will automatically use the complete IFTP.EXE directory location to read the above files. iFTP.INI will be searched first in the current directory. If not found, the iFTP.INI must be located in the iftp.exe program directory. If not found, an error will be reported. WININET.DLL Microsoft' Winsock Internet Library ----------------------------------------------------- The iFTP package comes with WININET.ZIP. It contains an early original copy of Microsoft's Winsock internet library file WININET.DLL. iFTP is based on this library and it is required in order to run. If it is not found, you will get a Windows Popup message saying it was not found. You may already have this file in your Windows System directory since it comes with NT 4.0, IE 4.0+ and all the new Microsoft software. So if you already have this special WININET.DLL file, you don't need to unzip WININET.ZIP. To quickly find out if you need it or not, simply type IFTP at the DOS BOX and if you see Windows immediately returns a pop up error message: "Application Requires WININET.DLL" or "Missing WININET.DLL" or something close to that effect, then you don't have WININET.DLL on your system and you will need to unzip the WININET.ZIP file. You can keep WININET.DLL in the IFTP directory or you can copy it over to the Windows System directory. Either way will work. However, if you ever do install IE 4.0+ or NT 4.0 or any of the new Microsoft software, the odds are very good it will come with their current version of WININET.DLL and there WILL BE conflicts if IE 4.0 is using its version and iFTP is using an older version. So our recommendation is to copy the WININET.DLL file to the Windows System Directory and make sure there isn't a second copy any where is on your system. Delete the copy in the IFTP directory. There will never be a problem unless there are different versions of this library loaded into memory by different applications. By copying it into the Windows System directory, you will make sure all Win32 applications who need this library will find and use the same version of the file. If IE 4.0 installs a new one, then IFTP benefits from using this new version (we hope so). iFTP Script file Location ------------------------- When running scripts, by default iFTP looks for script (without a directory path) in this order: - Current directory, - IFTP.EXE directory, - The directory defined by the AltScriptPath= key word in the IFTP.INI [Setup] section. If a script file has a specific directory on it, then it expects the script to be specifically at the location defined. The above search is only done if just a file name is provided (with no directory). By default, iFTP will use the file extension "FTP" for all scripts. iFTP is a powerful script system. Hence it is very possible that you will or can create many generic scripts which can be reused but other scripts. You can store these either in the IFTP directory or use the AltScriptPath= to define a directory where you place your generic scripts. iFTP.INI Configuration File --------------------------- iFTP will automatically read the iFTP.INI file for system configuration options and account setups. The INI file is a typical "Windows Based" INI file, with sections, keys and values. Read the iFTP.INI. The file has self help for all the options. Much information can be found in the INI which may not be found in this guide. iFTP Log File and Script Log Files ---------------------------------- iFTP keeps a very details log of its operations in the log file with a default file name of IFTP.LOG. By default, the log file is created in the same directory location IFTP.EXE is located. This allows you to run IFTP from any where on the harddrive and the IFTP.LOG will always be found in the iFTP directory. There are three ways to change the log file iFTP will use: Using the command line switch, /LOG iFTP /LOG This allows you to change the directory location where IFTP.LOG will be placed. It does not change the file name. Only the location. Using the INI [SETUP] option LogFilePath= The keyword LogFilePath= in the INI [SETUP] session will define the directory location where IFTP.LOG will be placed. Once again, this does not change the file name. Only the location. Using the script command LOGFILE LOGFILE [filename] The LOGFILE script command is the only way to change the log file name. This command useful when you wish to create a log file for different IFTP script operations. Once the script is finished, the default LOG file is automatically reset (or the last log file defined is reset for situations where you have scripts calling other scripts). Example: The top script call main.ftp calls two other scripts: MAIN.FTP Log Starting Main.ftp........... Call script1.ftp Call script2.ftp Log Done! The individual sub scripts, script1 and script2 has a LOGFILE command at the top of each script to create a specific log file for that script. Like so: SCRIPT1.FTP Logfile script1.log Log Hello! We are now in Script 1 SCRIPT2.FTP Logfile script2.log Log Hello! We are now in Script 2 Once each sub script has finished, iFTP will automatically reset the default log before it reads the next line in the MAIN.FTP script. Use the LOGFILE command when you have multiple scripts which create big logs and you want to separate the operations into their own separate logs for easier reading. ============================== iFTP Script Language Reference ============================== --------------- Language Syntax --------------- All commands that have parameters are either required or optional. The following delimiters are used to define the required or optional parameter. [] optional parameter <> required parameter Comment lines in scripts all begin with the following character(s) on column 1. // Double slash inline comment. ; Semi-colon : Colon ----------------------- General Script Behavior ----------------------- To run a script, use the /RUN command line option, like so: iFTP /RUN getmail.ftp You can also call a script from within a script by using the CALL command. All script files have a default file extension of "FTP". So the FTP extension is not required when specifying the script file name. If the extension is different, it must be specified. An iFTP script is a DOS based text file. You can use NOTEPAD, the DOS editor called EDIT or your favorite text editor to create script files. When iFTP first reads a script, it starts at the very top and reads down the text, ignoring all comment lines. All scripts end by themselves. Once the last line is encountered, the script ends and iFTP exits. Since iFTP offers the power of calling scripts within scripts, there are several commands to end iFTP or scripts. EXIT [X] Exit current script with optional errorlevel, Does not abort iFTP. Returns to calling script or ends iFTP if top script. The errorlevel, if used, can be detected with the IF ERRORLEVEL X command. QUIT Exit all scripts, ends iFTP, normal end, errorlevel 0 ABORT Exit all scripts, aborts iFTP with errorlevel 1 HALT [X] Exit all scripts, aborts iFTP with optional errorlevel X. The default is 0. Use ABORT when you view the error as critical and you want an simple errorlevel. Use Halt when you want a different error level other than 1. iFTP offers GOTO xxxx commands where it will jump to the script line with the line LABEL xxxx. It can search UP or DOWN the script but only the first line in the script with the LABEL xxxx will be used. In other words, do not define two labels with the same XXXX name. ------------------------------------------------------------ DOS File Names vs Unix File Names (special remote FTP drive) ------------------------------------------------------------ In general, when using some of the iFTP script commands, such as CD, DIR, IF EXIST, COPY, MOVE etc, it is important to understand the difference between DOS file naming vs UNIX file naming to determine the direction of the file transfer; local to remote (upload) or remote to local (download). The key difference is the usage between the forward slash (/) vs the back slash (\). When specifying file names relative to DOS, use the back slash (\). For example: c:\iFTP\export\*.* When specifying file names relative to UNIX, use the forward slash (/). For example: /inbin/*.* or you can use the special remote drive letter, ftp: ftp:/inbin/*.* Although, iFTP will allow you to use DOS back slashes for UNIX directories and file names in many of the remote file I/O commands, it helps if you understood the distinction. Many of the new iFTP commands rely on this distinction of back slash (/) versus forward slash (/) and using the ftp: drive letter to determine which direction is the file transfer or location of the file. In this document, a file name or directory having unix back slashes, refers to a file or directory at the remote site. Similarily, a file name or directory having DOS back slashes, refers to a file or directory at the local site. Here are some examples: // download from remote /*.* to local \import directory copy /*.* \import // upload all files in \export to remote /import directory copy \export\*.* /import As you can see, iFTP uses the same command, but uses the / or \ to determine the direction. New with Version 2.0! When no relative paths are defined, iFTP will assume the local drive. However, you can now switch to the remote drive using the FTP: command to make all the FILE I/O commands relative to the remote drive. For example: open ftpsite // show dos directory dir // show remote directory dir / // show remote directory FTP: dir In other words, the FTP: command switches the relative drive to the remote site to make it easier to use the DIR and CD commands. This is very useful when using iFTP in console mode (iFTP /con). =========================================== iFTP Asynchronous vs Synchronous Operations =========================================== When performing FTP operations under Win32, it can done in two modes: - Asynchronous or non-blocking - Synchronous or blocking Blocking basically means that iFTP makes a request and waits for a response. In a non-blocking environment, iFTP will make a request and do something else while waiting for the response. In a non-blocking state, more information is obtained. It has more overhead and thus can be slightly slower (probably not noticable). This concerns iFTP for only two things: - For Debugging, to watch whats going on at various states. - To offer a progress indicator during file transfers. So after its all said and done, the only reason why you would want to use Asynchronous operations is to turn on the progress indicator. Otherwise, when you issue a GET or PUT, iFTP will not log or say anything until the request is complete. Under normal and working script operations, this would be the best mode of operations. Turning on Asynchronous operations iFTP opens the windows internet sockets in async or sync mode based on the initial Socket= value in the iFTP.INI [Setup] session. If 1, the socket will be open up in Asynchronous mode, thus making all FTP commands available for non-blocking operations. However, even if the socket is open in async, you still have the power to turn on various file transfer async modes. You can also use the script command ASYNC to disable or enable asynchronous operations. ASYNC [ON|OFF|CONNECT|GET|PUT|DIR] The Async command toggles Asynchronous operations globally or specific parts of a network session. There are four parts iFTP can perform Asynchronous communications: CONNECT when connection to a ftp host/server GET when downloading files PUT when uploading files DIR when issues a directory command Use ON to globally turn on async communications for all four processes, use OFF to turn them off. Since one of the main reasons for asynchronous operations was to allow for a progress indication, the PROGRESS command is available to automatically enable or disable asynchronous operations during the GET or PUT operations. PROGRESS [ON:OFF] The PROGRESS Command will show a download/upload transfer indicator to show how many bytes were transmitted. Examples: Async On // open socket in async mode Open ftpsite // connect to ftpsite Progress On // turn on progress indicator Get /*.* \iFTP\import // download files ========================== iFTP Download File Caching ========================== iFTP offers built-in file caching when downloading files. What this means is that it is possible to download a file and try it again, and if the file is already in the cache, iFTP will not download it again. You can turn this behavior on or off with the iFTP.INI [Setup] session key UseCache=1/0 In addition, you can use the CACHE script command. CACHE ON|OFF New CACHE script command allows disabling/enabling of download caching. If off (default) all downloads are not saved on local drive cache. The main reason why you may wish to turn it off (default) is to conserve disk space. Cache is only required if you want iFTP to remember your downloads. Re-attempts of downloading the same file will be checked in the cache to see if the file is there. NOTE: The cache feature is a feature of the Microsoft WININET.DLL library. iFTP simply turns it on or off. iFTP itself does not have a cache system. ======================================================================= iFTP Set Variables, Internal, Environment Strings and Script Parameters ======================================================================= With iFTP scripts, you can define and use variables defined 4 different ways: - User Defined Set variables - Internal Variables always available - Environment Strings - Script parametners Variables are items that are defined and used in scripts in a generic fashion. This featured concept is similar to DOS with its set environment strings and batch file parameters. They add tremendous programming power to your scripts by allowing you create scripts that are re-usable by others or yourself, and more maintainable. User Defined Set Variables -------------------------- Within iFTP scripts you can define variables called SET VARIABLES or KEYS. Up to 30 set keys can be defined using the SET script command. To define a key, type SET key=value example: set file=whatever.zip To access the key, use the % character to surround the key, like so %key%. iFTP will substitute the value for the %key% when it is encountered in a script line. example #1: Write Ready to download file = %file% Get %file% example #2: set url1=http://www.santronics.com/iftp21.zip set url2=http://www.santronics.com/pxw20td.exe webget %url1% webget %url2% To erase a key, type SET key= To erase all keys, type: SETCLR To show all the keys or just one key, type: SET SET key Internal Variables ------------------ iFTP automatically provide some global variables to be used within your scripts besides the ones you can define. These global are always available to you: %input% Defined when the INPUT command is used %rashost% Currently connected RAS Host Entry Name %rasip% Currently connected assigned RAS IP Address %ftphost% Currently connected FTP host %errorlevel% Current ErrorLevel %lasterror% Last Error %lastkey% Last Key pressed (Ascii Code 0-255) %lastchar% Last Char pressed %script% Current Script Running %date% Current date in MM/DD/YYYY format, i.e, 06/28/1998 %time% Current time in HH:MM:SS format, i.e, 18:24:00 %day% Current day (abbreviation), i.e, Mon, Wed, Sat.. Example #1: Dial MyISP if not success then abort Log Connected to ISP! Assigned IP address is %rasip% Example #2: // // Dial ISP, and store IP address at your web site. // This allows other people to use a get the file // to see what your currently IP addrss is. This // useful for non-dedicated connections where you // might want to publish your 1 or 2 hour internet // connection // Dial MyISP if not success then abort Log Connected to ISP! Assigned IP address is %rasip% open ftp.mywebsite.com userid password if not success then abort writefile ftp:/assigned.ip %rasip% close Another iftp user can use this script to get the ip address. // // Get IP address and put it in set variable serverip // if exist assigned.ip then erase assigned.ip Webget http:://www.mywebsite.com/assigned.ip if not exist assigned.ip then abort "Service not alive" readfile assigned.ip serverip Log Server is available at IP address = %serverip% As you see, all kinds of iFTP programming power is available to you! Environment Strings ------------------- iFTP also supports the system environment strings within your scripts. For example: copy ftp:/usenet/*.* %import% The import environment string can be defined in a batch file and when you call the script, iFTP will translate the %import% environment string. Example: -- DoFTP.BAT --- @echo off set import=iFTP\import iFTP /run getfiles.ftp -- Getfiles.ftp -- Dial FtpSite if not success then abort Open FtpSite if not success then abort copy ftp:/usenet/*.* %import% Hangup iFTP Script Parameters ---------------------- Like batch files, you can pass up to 9 parameters to scripts. To access the script parameters, use %1, %2 ... thru %9. Do not use %1%. You can pass them via the iFTP command line: iFTP /run script [param1, param2...param9] or when calling a script with the CALL command: CALL script [param1, param2...param9] This adds tremendous programming power to your scripts making it possible to develop generic scripts with variables defined script parameters. Example: // File: PlayHalt.ftp // script to play wav file and halt playwav %1 halt 1 Now you can call this script like so: open ftpsite if not success then call playhalt badconnect.wav Comparing or Checking for Variables ----------------------------------- Whether you the set variables, internal environment strings or parameters, there are times where you have to check to make sure they exist. For this you use the IF condition EQUAL: IF EQUAL THEN ...... For example: if not equal "%ftpin%" "" goto ok Log Environment string FTPIN is not defined Log Please define it before calling this script Abort LABEL OK Use the double quotes around the string to make sure iFTP can read the two strings. If you don't use the "" the syntax would not be correct. The string comparison is not case sensitive. =============================================== Remote Access Service, Dial up Networking (DUN) =============================================== iFTP has a built-in Dial Up Networking (DUN) dialer. It works for all versions of Windows. Under Windows 95-based systems (Windows 95/98/ME), it is knowned as DUN. Under Windows NT-based systems (2000/XP/2003), most people know it as RAS (Remote Access Server). +-[ NOTE ]-----------------------------------------------------+ | As of version 2.1C, you no longer need RAS installed on the | | computer to use iFTP. This is useful for pure LAN/WAN FTP | | server operations where RAS is not installed and no dialing | | is required from a workstation. | +--------------------------------------------------------------+ When iFTP first starts, it will always check to see if there is a current connection. This allows you to use iFTP with the current connection. If you attempt to dial when there is already a connection, iFTP will skip the dial command. You must hangup to dial again. There is two ways to dial with iFTP: - Using the /DIAL command line switch option - Using the DIAL script command Using the command line switch /DIAL: Syntax: iFTP /DIAL [entry] [userid] [password] The entry name must match one in the iFTP.INI file or in the DUN Phone Book in your system. If no entry name is provided, iFTP will use the default [PPP] account stored in the iFTP.INI file. The userid and password parameters are optional and can be stored in the iFTP.ini file. Under NT 3.51, it can stored in the DUN phone book. Only under Win95 or NT 4.0, is it necessary to store it in the | iFTP.INI file. Please note the actual behavior of the DUN dialer is | based on the version of IE you have installed on your machine. +-[ IMPORTANT NOTE! ]-------------------------------------------+ | | | It is important to note that when using the /DIAL command, | | iFTP will not hangup. You must hangup the line yourself using | | a subseqeunt iFTP /HANGUP command. | | | +---------------------------------------------------------------+ Examples: 1) iFTP /dial MyISP iFTP /run script iFTP /hangup 2) iFTP /dial /run script /hangup 3) iFTP /dial MySecondPPPaccount Using the DIAL Script command: DIAL [entry] [username [password]] The DIAL command will dial the entry name defined. The entry record must be created on your system. Under Win95, the entry is created with your Dialup Network Manager. Under NT, it is created with the Remote Access Server Manager. Under Win95 and WinNT 4.0, the username and password is required. Under WinNT 3.51, the username and password is not required. If no parameters are provided, the defaults are obtained from the iFTP.INI ([PPP] section). HANGUP Hangup the current RAS connection (carrier is drop). This is command is not necessary for a script. iFTP will automatically drop the line unless the DIALOPTIONS option /KEEP is used. DIALOPTIONS [-STATUS] [-KEEP] [-TIMEOUT ] [-REDIAL ] The DIALOPTIONS command defines how the RAS dialing behaves. -STATUS This will show the dialing status information while it is dialing. This information can be very verbose. To minimize your iFTP.LOG file, do not use this option. Only use it when you need to investigate the dialing status to your provider. -KEEP By default, iFTP will automatically hangup the RAS connection when it exits. You can also hangup using the HANGUP command in your scripts. However, if you want to write a simple script to dial a system and keep the RAS connection alive, then option /KEEP tells iFTP to not hangup when it exits. This is useful when you want to use iFTP to dial up a system and keep the line active for other applications to use. -TIMEOUT The timeout option defines how long the dialer will wait before exiting with a time out ever. By default, the time out is 90 seconds. If you want to use Windows RAS default timeout value, then use 0 for the seconds. This will set an infinite wait value and will allow Windows to inform iFTP when it is complete. Normally, this is about 3-5 minutes under Win95/NT. -REDIAL The redial option is not implemented yet. Examples: ; Dial the default PPP account, show dial status, timeout in ; 60 seconds if fails to connect DialOptions /Status /Timeout 60 Dial if not success then abort ... hangup =========================== Session/Connection Commands =========================== OPEN [host or alias] [userid] [password] Opens a session with the remote ftp host site. If no parameters are provided, defaults are taken from iFTP.INI file. It is a good idea to use the IF condition to determine the success of the open. For example: Open ftp.microsoft anonymous hector@santronics.com If not success then abort If a session is already open, when this command is issued, the current session will be automaticalled closed. iFTP will always close a session (and the socket) when it exits back to the system. You can define an alias in the iFTP.INI file to get the parameters of the connect and login. For example: OPEN WebSite iFTP will search for the section [WebSite] in the inifile and read the host, userid and password key values. Using aliases makes it easier to design generic scripts to distribute to others without putting your userid and password in the scripts. If no alias is found, iFTP will assume the name to be DNS host name and attempt to resolve it. You can also use iFTP within a LAN where there is a FTP server. Simply type in the FTP server machine name and it will be found. You can also type in IP addresses as well. CLOSE Closes current session. QUIT Closes current session and exits script. When scripts are finished, iFTP will automatically close the session and close the socket. So CLOSE and QUIT are not necessary. CLOSE is only useful if you are OPENING and CLOSING multiple sessions in the same script. =============================== Directory and File I/O Commands =============================== iFTP was designed to offer a rich set of FILE I/O commands similar to that of DOS. All of the following commands work with either the local drive or the remote drive. To work with the remote directory, use the special FTP drive letter (ftp:) or the respective / or \ characters to distinquish direction. DIR [file spec] LS [file spec] Display files spec. LS displays the files in wide format similar to the unix format. Examples: Dir c:\bin\*.* Display files in c:\bin Dir ftp:/bin\*.* Display files in remote \bin directory. CD [directory] Change directory. If no directory is provided, the LOCAL current directory is displayed. To display the REMOTE current directory use ftp:. Examples: cd display local current directory cd ftp: display remote current directory cd ftp:/ return to remote root directory cd ftp:/inbin change to the remote /inbin directory MD MKDIR Make a new directory. Use the ftp: drive letters to indicate a remote directory. Examples: md \new create new local \new directory md ftp:/new create new remote /new directory RD RMDIR Remote directory. Use the ftp: drive letters to indicate a remote directory. Examples: rd \new remove local \new directory rd ftp:/new remove remote /new directory ERASE DEL Deletes one or more file(s). Use the ftp: drive letters to indicate remote files. Examples: erase \import\*.zip delete files in local import directory erase ftp:/import/*.zip delete files in remote import directory BINARY [ON:OFF] For file transfers, you may define how file transmissions are to be uploaded or downloaded using any of the file transfer commands. BINARY is enabled (ON) by default. If BINARY is disabled (OFF), then all files will have the linefeed character converted to carriage return/linefeed pairs during downloads and vice versa during uploads. This is considered a text mode transmission. Use Binary OFF when you are absolutely sure you are transferring text files only, such as *.txt or html files. Make sure binary mode is disabled when transmitted binary files such as ZIP files, Fidonet mail bundles or packets, etc. GET [local storage path] [-KILL] Downloads remote files. If operation local storage path is defined, this is where the files will be locally stored. If the -KILL option is defined, the remote file is deleted after a successful download. examples: ; download remote files into current directory, kill remote ; file after each successful download get /export/*.zip -kill ; download remote files into storage directory get /export/*.zip \import see COPY, MOVE command PUT [remote storage path] [-KILL] Uploads local files to the remote site. If operation remote storage path is defined, this is where the files will be remotely stored. If the -KILL option is defined, the local file is deleted after a successful upload. examples: ; Upload local files in current directory, kill local file ; after each successful upload put c:\pxw\export\*.* -kill ; Upload local files into remote directory. put c:\pxw\export\*.* /import -kill see COPY, MOVE command COPY MOVE Copies or moves one or more files from the source to the target. These commands offer you the DOS like similarities of the DOS copy and move commands. The move command is basically like the PUT -KILL options where it will copy the file and then delete it. This is useful in situations where they might be a connection drop. On restart, only the remaining files will be uploaded. examples: ; Copy local files to remote system copy \iFTP\export\*.* /import ; Move local files to remote system move \iFTP\export\*.* /import RENAME The RENAME command will remame the old file name to new file name. Both files must be on the same machine. When using DOS files, the new file name can be on a different directory or dos drive. So effectively, you can use this as a move operation with the ability to rename the file at the same time. For example: rename c:\file1.txt d:\backup\file3.txt When working with remote files on a FTP server, there might be some FTP servers who may or not honor the concept of moving a file when using the rename command. Be aware that some FTP servers, may not allow operation. For example: rename /file1.txt /textfiles/file20.txt The above command may work for FTP some servers. | UPDATE [DosPath] [-kill] [-s] The Update command allows you to download Remote files which are newer than the local files with the same name. If the local file does not exist, the files are copied. The UPDATE command works by using the remote file date and compares it with the local file date. So even of the option INI UseSaveDate is disabled, Update can be used to copy updated ftp files to the local drive. The -kill option works like the move. Updates remote files will be downloaded and then deleted from the remote site. | The -s option indicates to recurse the subdirectories. This will | effectively mirror the remote files and folders on the local | drive. NOTE: The Update command only works in one direction (Remote to Local). It does not work updated local files to the remote site. Consider using the XPUT command archive option. examples: ; Copy only new files from remote site update /reports/*.* \reports | ; Copy only new files and folders from remote site | | update /reports/*.* \reports -s XPUT [Storage] [-A -M -E -T] XPUT is a very powerful command. It is similar to the DOS xcopy command but for putting (uploading) files to the remote site. Using XPUT without the options makes it work like the normal PUT command. But when used with options, you can perform massive copies including subdirectories from the local drive to the remote site. -E Copy files including subdirectories. New directories on the remove site will be checked and/or created. -A Copy only archive files to the remote site. Archive files are local files which have the archive bit. The archive bit is always set by the PC file system when the file is first created or modified. -M Same as -A but will remove the archive attribute of the file after the upload is finished. This is useful for backups or for mirroring a directories. The next | time the XPUT -M command is used, it will only copy the new files. -T This option is used for TESTING purposes. It gives you the ability to see what XPUT will do when copying files without actually performing the copy. Use -T to see that it will do what you want first. Examples: ; Copy the entire local web directory and subdirectories ; Run in test mode to see the results first. xput j:\website\*.* ftp:/ -e -m -t WRITEFILE [string] This command opens a file and writes the optional string to it, then closes the file. This command is useful for creating a semaphore file like it is done in the PAONLINE.FTP example. READFILE [line#] Read a line in the file and set the result into the variable "var". The variable can then be used as a set variable. FINDFIRST FINDNEXT FINDCLOSE FINDFIRST can be used to perform a directory I/O operation to obtain file information per file found in the file spec. FINDFIRST returns the first first. To find the next file, the FINDNEXT file is used. If no file is found, the global SUCCESS flag is set to false. When no more files are found, the global ERRORNO variable is set to 18 (no more files). It is important that a FINDCLOSE command is used when FINDFIRST is successful to remove the memory reserved to remember the file returned. How it works: FINDFIRST will perform a complete file listing check and create an internal table of file records. You can access the first and next records using the following environment variables: %file.total% - index or total files %file.name% - name of file %file.size% - size of file %file.date% - date of file in MM-DD-YYYY format %file.date.day% - day of file date %file.date.month% - month of file date %file.date.year% - year of file date %file.time% - time of file in hh:mm:ss format %file.time.hour% - hour of file time %file.time.mins% - minutes of file time %file.time.secs% - seconds of file time %file.age.days% - age of file in days %file.age.hours% - age of file in hours %file.age.secs% - age of file in seconds FINDFIRST will set the %FILE.xxxx% environment strings for the first file found and FINDNEXT will set the %FILE.xxxx% environment strings for next file found until no more are found. example: FindFirst /newdata/*.* if not success then begin Log "no files found!" exit endif while not errorno 18 do Log "[%file.total:2%] %file.date% %file.size:-12% %file.name%" findnext wend Log "Total Files: %file.total%" FindClose ================ Generic Commands ================ STATUS Show iFTP Status Information. This command will display the current state of affairs with internal information such as RAS or IP connections, asynchronous or synchronous states or debugging states and so on. It is useful to use during console mode when you are testing your scripts. Here is an example output: * iFTP Status Information: * RAS Connection : Vincent * RAS IP Address : 209.4.200.151 * RAS Connect Time : 1232 secs * FTP Connection : * Socket Mode : Sync Dial Mode : Sync * Connect Mode : Sync Search Mode : Sync * Download Mode : Sync Upload Mode : Sync * Save File Date : OFF Transfer Type : Binary * Download Cache : OFF Show Progress : ON * Server Debug : OFF Async Debug : OFF * Script Debug : OFF Verbose Debug : OFF * Show I/O Errors : OFF Error Level : 0 * Last Error # : 0 System Error : 0 * Last Error Msg : The operation completed successfully DEBUG [ON|OFF|LOG|ASYNC|SCRIPT] Turns on/off the debugging of scripts, verbosity of the log file and the result of asynchronous communications. This is only useful under debugging situations. BEEP Sound the speaker PLAYWAV This allows the playing of wav files (Sounds card required). Useful for signaling certain events. Example: open ftpsite if not success then playwav BadConnect.Wav See the provided SOUND.ZIP for example wav files that can be used with your scripts. POPUPMSG Display a POPUP Messages. It is a simple OK buttom message box. Useful to pause the script for certain events. EXEC DOS This command will start the application specified. DOS does the same thing but will use the DOS command interpreter to run the application. Use DOS when you want to use DOS commands within scripts. Examples: ; Run dos command dos ping ftp2.paonline.com CALL Runs another script file and return the calling script. This is useful for running multiple scripts during the same iFTP execution. Example: Suppose you have two independent scripts; script1.ftp, script2.ftp, you can do this: iFTP /RUN script1.ftp iFTP /RUN script2.ftp or you can create another script called runall.ftp which has the following lines: call script1.ftp call script2.ftp and run iFTP once by doing the following: iFTP /RUN runall.ftp ABORT [string] Aborts the current script and exits iFTP. If optional string is provided, it is written to the log and screen. A process error level of 1 is set. This process error level can be detected by a batch file. HALT [errorlevel] Similar to the ABORT command, but allowing you to define an process error level. This process error level can be detected by a batch file. See example #6 (exam6.ftp) EXIT [errorlevel] Exits current script, exits iFTP or calling script with optional errorlevel. EXIT simply exits the current script and returns to the calling script. If its the top script, then iFTP ends. With the optional errorlevel, you can use this to test scripts errorlevels, for example: main script: call subscript ftpsite *.* if errorlevel 1 then Abort "Bad Connection!" if errorlevel 2 then Abort "Bad Download!" Log Success! Exit 0 subscript: open %1 if not success then exit 1 get ftp:/%2 if not success then exit 2 Exit 0 ERRORLEVEL [errorlevel] Change the current error level as remembered by IFTP. ERRORQUIET [ON|OFF] Enable or disable the internal I/O error logging. By default, iFTP scripts commands will be quiet, like GET /*.*. This allows you more control with your scripts to log the results yourself. See the IF ERRORQUIET discussion below. GOTO