CD

Syntax: cd dirname

What it does: Changes the current folder on the current FTP site to dirname where dirname is the name of a folder on the site.

Note: This command can be executed only if a connection to an FTP site has been established.


CLOSE

Syntax: CLOSE

What it does: Closes the current FTP connection.


CONNECT

Syntax: CONNECT (hostname or %env_var_name) [port_# or %env_var_name]

What it does: Attempts to connect to the FTP site, where

•	the host name or IP address of the FTP site is specified by hostname or by an environment variable

•	the port number is specified in port_# or in an environment variable.

Note: If no port number is specified, the standard FTP port 21 is used.


DEL

Syntax: DEL filename

What it does: Deletes a single file named filename from the current FTP site.

Notes:

•	This command can be executed only if a connection to an FTP site has been established.

•	Use MDELETE to delete multiple files. Use RDEL if you need to delete folders with subfolders.


DIR

Syntax: DIR filemask

What it does: Issues a LIST command to the current FTP site using filemask and displays the output to the screen.

Note: This command can be executed only if a connection to an FTP site has been established.


GET

Syntax: GET (sourcefile or %env_var_name) [destloc or %env_var_name] [modeswitch]

What it does: Retrieves sourcefile from FTP site, where:

•	sourcefile or environment variableis the name of the source file on the FTP site.

•	destloc or environment variableis the name of the transferred file on the local system. If the last character in the destloc is a '/', the destloc is assumed to be a folder and sourcefile is placed in that folder. If destloc is not specified, the local current working folder is used as the destination.

•	the transfer mode is modeswitch (0=ASCII, 1=binary). If the transfer mode is not specified, ASCII mode is used.

Notes:

•	This command is executed only if a connection to an FTP site has been established.

•	Use MGET to delete multiple files. Use RGET to delete folders with subfolders.


GOTO

Syntax: GOTO labelname

What it does: Jumps to labelname and continues processing the script from that point.

Note: LABEL labelname may be before or after the GOTO statement


LABEL

Syntax: LABEL labelname

What it does: Establishes a labeled point in the script for using with GOTO commands, where labelname can be any combination of numbers and letters.


LCD

Syntax: LCD dirname

What it does: Changes the current folder on the local system to dirname.

Note: This command is not dependent on a connection.


LOG

Syntax: LOG (Screen or filename or Off)

What it does: Sends the log of FTP events to the specified location.

•	Screen - Sends output to the screen

•	filename - Sends output to a file. If a file named filename does not exist, it is created; otherwise, it is opened for appending and logging output is written to this file. (If LOG is later redirected to the screen or turned off, the file is closed and no more information is written to it.)

•	Off - Turns off output of LOG information.

Note: This command is most effective when used at the very beginning of a new script; it provides information that is extremely useful in getting a script up and running.


MDELETE

Syntax: MDELETE filenames or folders

What it does: Deletes filenames or folders from the current FTP site. The names of the files on the FTP site to retrieve is specified in filenames. Wild cards of * or ? are acceptable.

Note:

•	This command is executed only if a connection to an FTP site has been established.


MGET

Syntax: MGET (sourcefile or folders or %env_var_name) [destloc] [modeswitch]

What it does: Retrieves source files or folders from an FTP site, where

•	sourcefile or environment variableis the name of the source file on the FTP site.

•	destloc or environment variableis the name of the transferred file on the local system. If the last character in the destloc is a '/', the destloc is assumed to be a folder and sourcefile is placed in that folder. If destloc is not specified, the local current working folder is used as the destination.

•	the transfer mode is modeswitch (0=ASCII, 1=binary). If the transfer mode is not specified, ASCII mode is used.

Notes:

•	This command is executed only if a connection to an FTP site has been established.

•	Use GET to delete a single file. Use RGET to delete folders with subfolders.


MKDIR

Syntax: MKDIR dirname

What it does: Creates a folder of dirname on the current FTP site.

Note: This command is executed only if a connection to an FTP site has been established.


MPUT

Syntax: MPUT (sourcefile or folders or %env_var_name) [destloc] [modeswitch]

What it does: Sends source files or folders to the current FTP site

•	sourcefile is the name of the file to send to the FTP site. Wild cards of * or ? are acceptable in the source file specification.

•	destloc or environment variableis the name for the transferred file on the FTP site. If the last character in destloc is a '/', destloc is assumed to be a folder and sourcefile is placed in that folder. If destloc is not specified, the current folder on the FTP site is used as the destination.

•	the transfer mode is modeswitch (0=ASCII, 1=binary). If no transfer mode is specified, ASCII mode is used.

Note:

•	This command is executed only if a connection to an FTP site has been established.

•	MPUT doesn’t transfer subfolders; to transfer subfolders, use RPUT.


ONERROR

Syntax: ONERROR [GOTO labelname or SHELL commandline or EXIT or CONTINUE]

What it does: If an error is encountered, from this point on perform the specified action. The possible actions are:

•	GOTO labelname - Jump to labelname and continue processing from that point.

•	SHELL commandline - Open an MS-DOS shell, and execute commandline on the local system.

•	CONTINUE - Continue processing the script.

•	EXIT - Terminates any further execution of the script. However, any connection with an FTP site is not disconnected unless the script is terminated or a CLOSE command is executed.

Note: If no action is specified, the script continues processing.

The CONTINUE and EXIT commands can be used only within an ONERROR or ONSUCCESS command.


ONSUCCESS

Syntax: ONSUCCESS [GOTO labelname or SHELL commandline or EXIT or CONTINUE]

What it does: For any successful completion of a command from this point on perform the specified action. Possible actions are:

•	GOTO labelname - Jump to labelname and continue processing from that point.

•	SHELL commandline - SHELL out and execute commandline on the local system.

•	CONTINUE - Continue processing the script.

•	EXIT - Terminates any further execution of the script. However, any connection with an FTP site is not disconnected unless the script is terminated or a CLOSE command is executed.

Note: If no action is specified, the script continues processing.


PASS

Syntax: PASS (password or %env_var_name)

What it does: Sets the password to the value in password or in an environment variable.

Note: This command must precede the CONNECT command.


PUT

Syntax: PUT (sourcefile or %env_var_name) [destfile] [modeswitch]

What it does: Sends sourcefile to an FTP site, where:

•	sourcefile is the name of the file to send to the FTP site. Wild cards of * or ? are acceptable in the source file specification.

•	destloc or environment variableis the name for the transferred file on the FTP site. If the last character in destloc is a '/', destloc is assumed to be a folder and sourcefile is placed in that folder. If destloc is not specified, the current folder on the FTP site is used as the destination.

•	the transfer mode is indicated in modeswitch (0=ASCII, 1=binary). If no transfer mode is specified, ASCII mode is used.

Note:

•	This command is executed only if a connection to an FTP site has been established.

•	Use MPUT to delete multiple files. Use RPUT to delete folders with subfolders.


RDEL

Syntax: RDEL filename

What it does: Deletes filenames or folders (with subfolders) from the current FTP site.

Note: This command is executed only if a connection to an FTP site has been established.


RGET

Syntax: RGET (sourcefile or folders or %env_var_name) [destloc] [modeswitch]

What it does: Retrieves folders (with subfolders) from the current FTP site, where:

•	the name of the folder is specified by folders. Wild cards of * or ? are acceptable in the folder specification.

•	the name to use for the transferred file on the local system is specified by destloc or by an environment variable. If the last character in the destloc is a '/', the destloc is assumed to be a folder and the sourcefile is placed in that folder. If destloc is not specified, the current folder on the FTP site is used as the destination.

•	the transfer mode is modeswitch (0=ASCII, 1=binary). If no transfer mode is specified, ASCII mode is used.

Note:

•	This command is executed only if a connection to an FTP site has been established.


RMDIR

Syntax: RMDIR dirname

What it does: Removes a folder of dirname from the current FTP site.

Note: This command is executed only if a connection to an FTP site has been established.


RNFR

Syntax: RNFR filename

What it does: Specifies a file or folder to be renamed on the current FTP site.

Notes:

•	This command is executed only if a connection to an FTP site has been established.

•	This command must be followed by a RNTO command.


RNTO

Syntax: RNTO filename

What it does: Specifies a new name for a file or folder on the FTP site; the file or folder must be previously identified with a RNFR command.

Notes:

•	This command is executed only if a connection to an FTP site has been established.


RPUT

Syntax: RPUT (sourcefile or folders or %env_var_name) [destloc] [modeswitch]

What it does: Transfers folders (with subfolders) to the current FTP site

•	sourcefile is the name of the file to send to the FTP site. Wild cards of * or ? are acceptable in the source file specification.

•	destloc or environment variableis the name for the transferred file on the FTP site. If the last character in destloc is a '/', destloc is assumed to be a folder and sourcefile is placed in that folder. If destloc is not specified, the current folder on the FTP site is used as the destination.

•	the transfer mode is modeswitch (0=ASCII, 1=binary). If no transfer mode is specified, ASCII mode is used.

Note:

•	This command is executed only if a connection to an FTP site has been established.

•	Use PUT to delete a single file. Use MPUT to delete multiple files or multiple empty folders.


SHELL

Syntax: SHELL commandline

What it does: Opens an MS-DOS window to execute commandline.

Note: This command is executed only if a connection to an FTP site has been established.


TRACE

Syntax: TRACE (Screen or filename or Off)

What it does: Sends detailed information on the command to the specified location.

•	Screen - Sends output to the trace window.

•	filename - Sends output to a file. If a file of filename does not exist, it is created; otherwise, it is opened for appending and tracing output is written to this file. (If TRACE is later redirected to the screen or turned off, the file is closed and no more information is written to it).

•	Off - Turns off output of TRACE information.

Note: This command is most effective when used at the very beginning of a new script; it provides information that is extremely useful in getting a script up and running.


USER

Syntax: USER (userid or %env_var_name)

What it does: Sets the user ID to userid or to an environment variable.

Note: This command must precede the CONNECT command.


Overview of Scripting

The Scripting Utility lets you write, debug, and execute scripts that run the WS_FTP Pro classic user interface.

For writing and debugging scripts, use the Command, Trace, and Log windows. An MS-DOS window is also provided to show you the output of some commands.

To run scripts, use the MS-DOS prompt.

See also:

FTP Functions

Script Execution Control

Debugging Functions

Script Command Reference


FTP Functions

Your script can control the interaction between your PC and the FTP site as follows. (For a simple list of commands, click here.)

•	Logging On

Connect to an FTP site on a particular port (CONNECT)

Set the user ID for the log on to the FTP site (USER)

Set the password the log on to the FTP site (PASS)

•	Navigating and Viewing Files and Folders

Change the current folder on your PC (LCD)

Change the current folder on the FTP site (CD)

Issue a list command to the FTP site using a file mask (DIR)

•	Managing Files and Folders

Create a folder on the FTP site (MKDIR)

Delete a folder from an FTP site rmdir (RMDIR)

Delete a file from an FTP site (DEL)

Delete either multiple files or folders with contents from an FTP site (RDEL)

Rename a file or folder “from” on an FTP site (RNFR)

Specify the new file name or folder name (RNTO)

•	Transferring Files and Folders

Copy a file from an FTP site (GET)

Copy multiple files or folders with contents (RGET)

Copy a file to an FTP site (PUT)

Copy either multiple files or folders with contents to an FTP site (RPUT)

•	Other

Shell out to your PC to execute command line (SHELL)

Close an FTP connection you have opened (CLOSE)


Script Execution Control

Your script can control script execution. (For a simple list of commands, click here.)

•	Check for an error (ONERROR)

•	Check for successful completion of a command (ONSUCCESS)

•	Establish a labeled point in the script for use with goto commands (LABEL)

•	Go to a labeled point in the script (GOTO)


Debugging Functions

Your script can accomplish the following logging functions:

View a log of FTP events (LOG)

Trace the results of each script command (TRACE)


Command Reference
Script Command Reference

FTP Commands	Execution Control	Debugging
CD	MPUT	LABEL	LOG
CLOSE	PASS	GOTO	TRACE
CONNECT	PUT	ONERROR
DEL	RDEL	ONSUCCESS
DIR	RGET
GET	RMDIR
LCD	RNFR
MKDIR	RNTO
MDELETE	RPUT
MGET	SHELL
	USER


Command Line Syntax
Command Line Reference

Arguments (alphabetical)	What It Does	Important restrictions
-b	Specifies binary transfer mode.	If not specified, then ASCII transfer mode is assumed.
-c account	Specifies an account on the FTP site.	Overrides the account in the site configuration if used after the -p option; otherwise the -p setting takes precedence.
-d	Specifies the destination path and desired file name of the file you want to upload or download. Use the correct system syntax.	Only one of the systems specified by -s or -d can be remote. If both are remote, the local system is used as the destination.
-f	Specifies the script file.	-f settings have precedence over command line options.
-i inifile where inifile is the path and name of the .ini file	Specifies an .ini file. Use this argument if the WS_FTP.ini file is in a directory other than that of WS_FTP Pro, or if the WS_FTP Pro path is not in your Path statement.
-p sitename	Specifies a configured site in the default .ini file or in the .ini file specified with the -i argument.
-s	Specifies the source path and desired file name of the file you want to upload or download. Use the correct system syntax.	Only one of the systems specified by -s or -d can be remote. If both are remote, the local system is used as the destination.
-u	Specifies a user ID.	Overrides the user ID in the site configuration if used after the -p option; otherwise the -p setting takes precedence.
-w	Specifies a password to use.	Overrides the password in the site configuration if used after the -p option; otherwise the -p setting takes precedence.


Writing Scripts

You write scripts using the Command window.

•	To add a line, select Add from the Edit menu. Select the command you want and then type any parameters in the text box.

•	To insert a line, select the line above which you want to insert the line and select Add or Insert from the Edit menu.

Editing Scripts

•	To edit a line in the Modify Command window, double-click the command line in the Command window or select it and select Modify form the Edit men.

•	To delete a command line, select the line and select Delete from the Edit menu.

•	To edit commands in text edit mode, click the Edit button and type directly into the Command window. When finished editing, click End edit.


Sample Script

TRACE SCREEN
LOG SCREEN
USER anonymous
PASS wsftp60@unknown
CONNECT ftp.ipswitch.com
CD Ipswitch\Product_Downloads
DIR
GET readme.txt
CLOSE


Debugging Scripts

To debug a script:

1	Open the script file.

2	Make sure you have TRACE and LOG commands at the beginning of the script.

3	Step through the script using the Step button and use the information in the Trace and Log windows to determine which commands are executing as desired and which are not.

4	Use online Help to look up any commands that are not executing as desired and correct the command syntax.


Executing Scripts

1	Write and save your script.

Do one of the following:

•	In the Scripting Utility, click Go.

•	Go to the MS-DOS prompt and type ftpscrpt followed by the appropriate command line parameters. For example,

ftpscrpt -p Ipswitch -s bigfile.txt -f script1.scp

Note: To be able to run a script from any location on your hard disk, we recommend that you place the Scripting Utility folder in the Path statement in your Autoexec.bat file – if you are running Windows 95 or Windows 98. If you’re using Windows NT, add the WS_FTP Pro folder to the path variable in the System Environment. Otherwise, change to your .ini file folder before you enter the commands.


Editing Scripts

There are several ways to edit scripts:

•	To insert a line, select the line above which you want to insert the line and select Add or Insert from the Edit menu.

•	To edit a line in the Modify Command window, double-click the command line in the Command window or select it and select Modify form the Edit men.

•	To delete a command line, select the line and select Delete from the Edit menu.

•	To edit commands in text edit mode, click the Edit button and type directly into the Command window. When finished editing, click End edit.


Using Environment Variables

You can use MS-DOS environment variables to pass certain parameters to your script. The parameters you can store in environment variables are listed below; the script commands that can use each parameter are shown in parentheses.

•	Host name (CONNECT)

•	Port number (CONNECT)

•	User ID (USER)

•	Password (PASS)

•	The name of the source file (GET, PUT)

•	The name of the destination file (GET, PUT)

•	Transfer mode (GET, MGET, PUT, MPUT, RGET, RPUT)


Add/Insert Command
Add/Insert/Modify Command

Enter or edit a command and the appropriate arguments (if any).


Basic Syntax

To run a script, you type ftpscrpt followed by xxx. For example,

ftpscrpt -p xxx -s xxx -f script1.scp


Configured FTP Site

A configured FTP site is an FTP site about which you have saved some information in the Site Properties dialog box in WS_FTP Pro:

The General tab contains the following site properties: site name, host name/IP address, host type, user ID, password, and account.

The Startup tab specifies the startup folders for the FTP site and your PC, any initialize commands, the local and remote file masks, and the time offset.

The Firewall tab contains your firewall user ID and password, as well as the firewall’s host name, port, and type.

The Advanced tab contains settings for retrying the connection, network timeout, remote port, and passive transfers.


Connect

When you "connect" to an FTP site, WS_FTP Pro sends messages to the FTP site and -- if the connection is successful -- receives messages back from the site. These messages use the Internet's File Transfer Protocol.


Environment Variable

An MS-DOS environment variable such as can be created or viewed using the SET command at the MS-DOS prompt.


System syntax
Specifying the FTP Site or Local System

If you use the -s or -d parameters when you execute a script from the MS-DOS prompt, indicate a particular sytem (whether an FTP site or the local system), use one of the following formats:

//hostname/path_filename or hostname:/path_filename

where hostname is the host name or IP address of either the FTP site or the local system and path_filename is the complete path you want to use.