FTP commands

This section lists the FTP commands sent to the FTP server when the statement is executed (for a local host, no commands are sent). Some statements do not generate FTP commands. For such statements, the section is not present.

A parameter can have the following elements:

• A string surrounded by double quotes (for example, "double-quoted string").
• Names of environment variables preceded by a $ character (local host only).
• Names of script variables preceded by a % character.

APPEND

Append local file to file on FTP server.

• Syntax – APPEND localfile TO remotefile;
• Description – The APPEND statement appends a local file localfile to a remote file remotefile. If the file remotefile does not exist, it is created. The file localfile is not changed nor deleted.
• The localfile parameter must be an absolute path. The format of the path is system dependent.
• The remotefile parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• PORT <sp> host-port <crlf>
• APPE <sp> remotefile <crlf>
• Example:

CD

Change the current directory on the FTP server.

• Syntax – CD remotedirectory;
• Description – The CD statement changes the current directory on the FTP server. The remotedirectory parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• CWD <sp> directory <crlf>
• Example:

DEBUG

Log a partial FTP session in the message log.

• Syntax – DEBUG;
• Description – If a DEBUG statement is executed during execution of a script, Debug is turned on. By default, Debug is turned off. A receive script normally receives one or more messages. A send script normally sends a single message. Activator logs a session record in the message log under the following conditions.

• Condition	Session record contains
  Send or receive script terminates (with errors) with Debug on or off.	The entire FTP session.
  Send script completes (no errors) with Debug on.	The entire FTP session.
  Receive script completes (no errors) with Debug on.	The entire FTP session up to the command that received the given message. If the FTP session continued, which is the normal case, the last line in the session record consists of three periods (...). Statements (and the generated FTP commands) executed after the last statement that receives a message are not contained in any session record.

• In all cases for a remote host, the details logged include:
  • The FTP statements executed
  • The FTP commands sent by Activator
  • The replies sent by the remote host

DELETE

Delete a file on the FTP server.

• Syntax – DELETE filename;
• Description – The DELETE statement deletes the file filename on the FTP server. The filename parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• DELE <sp> filename <crlf>
• Example:

GET

Copy a file from the FTP server without processing by an activity.

• Syntax – GET remotefileTOlocalfile;
• Description – The GET statement copies the remote file remotefile to the local file localfile. If the file localfile exists, it is overwritten.
• The remotefile parameter can be an absolute or relative path. The format of the path is system dependent.
• The localfile parameter must be an absolute path. The format of the path is system dependent.
• The main difference between this statement and the RECV statement is that a file copied using the GET statement is not processed by the activity of which the method that contains the script is part.
• FTP commands
• PORT <sp> host-port <crlf>
• RETR <sp> remotefile <crlf>
• Example:

IF ELSE

Conditional execution.

• Syntax – IF (expression) { statements } [ELSE { statements } ]
• Description – The IF ELSE statement performs conditional execution of statements. The expression parameter is one of the following.

• Expression	The expression is true if variable
  variable = value	Is equal to value.
  variable <> value	Is different from value.
  variable < value	Is less than value.
  variable <= value	Is less than or equal to value.
  variable > value	Is greater than value.
  variable >= value	Is greater than or equal to value.
  variable IN list	Matches an exact value or is within a range of values in list.
  variable NOT IN list	Is not in list.

• The comparisons are string comparisons. The precise meaning of <, <=, >, and >= depends on the character set used by your operating system.
• Lists
• A list is a combination of exact values and/or range(s) of values separated by commas.
• A range of values is specified as a pair of values (each in double quotes), and the two values are separated by a minus sign, for example, "tcp006"-"tdz209".
• When a variable is compared to a range of values, the comparison is true if the variable is greater than or equal to the first value and less than or equal to the second value.
• Consider the range "val001"-"val100". The value "val010.tmp" is in this range because "val010.tmp" is greater than "val001" and less than "val100".
• Consider the range "val001.dat"-"val100.dat". All values from "val001.dau", "val001.dav", "val001.daw", "val001.dax" … "val001.dba", "val001.dbb" …"val099.zzy", "val099.zzz" etc. to "val100.das" are in the range.
• Example

LIST

Read the contents of a directory on the FTP server.

• Syntax – LIST remotedirectory INTO variable { statements }
• Description – The LIST statement reads the contents of a directory on the FTP server. If the variable does not exist, it is created. For each entry found, variable is set to the file name, and the statements block is executed.
• The remotedirectory parameter can be an absolute or relative path. The format of the path is system dependent.
• If the script is executed locally, you can use wildcard characters in the remotedirectory parameter.
• The wildcard characters are:
  • An asterisk, *, matches any substring.
  • A question mark, ?, matches any single character.
  • […] matches any one of the enclosed characters. For example, specifying [abc] matches a or b or c, but no other character.
• If the script is executed locally, the files are sorted by date, starting with the oldest. If the script is not executed locally, the sort order is undefined.
• FTP servers use different file-name formats. For example, some FTP servers include the directory prefix in the file name. Your script should not make assumptions about the file-name format.
• The directory listing is transferred using the ASCII representation type.
• FTP commands
• TYPE <sp> A <crlf>
• PORT <sp> host-port <crlf>
• NLST <sp> directory <crlf>
• TYPE <sp> original_type <crlf>
• Example 1

• Example 2

Local Command

Execute a command at the local site.

• Syntax – ! command;
• Description – The local Command statement executes a command at the local site. The command, enclosed as a string, is preceded by a ! character. The result of the command is available in the %EXEC reserved variable. If the result is nonzero, the script terminates, unless the statement is preceded by the “-” qualifier. The command is executed using the sh shell on UNIX and the command shell on Windows.
• Example

• On Windows systems, running a .bat or .cmd file using a Local Command statement fails with exit code 255. This is due to Windows problems with redirection of output. The workaround is to run a Message Builder program using r4edi. Here is an example. Write the following program filecopy.s4:

• The program simply copies a file. Compile the program. You can now copy a file using the following Local Command statement:

• The statement returns 0 if it succeeds and 1 if it fails.

MKDIR

Create a directory on the FTP server.

• Syntax – MKDIR remotedirectory;
• Description – The MKDIR statement creates a directory on the FTP server.
• The remotedirectory parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• MKD <sp> directory <crlf>
• Example

PUT

Copy a local file to the FTP server.

• Syntax – PUT localfile TO remotefile;
• Description – The PUT statement copies a local file localfile to the remote file remotefile. If the file remotefile exists, it is by default overwritten. The file localfile is not changed or deleted.
• The localfile parameter must be an absolute path. The format of the path is system dependent.
• The remotefile parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• If the value of the store-unique setting is off:
• PORT <sp> host-port <crlf>
• STOR <sp> remotefile <crlf>
• If value of the store-unique setting is on:
• PORT <sp> host-port <crlf>
• STOU <sp> remotefile <crlf>
• For details of the store-unique setting, see SUNIQUE.
• Example

QUIT

Stop the script.

• Syntax – QUIT;
• Description – The QUIT statement stops the execution of the script without error.

QUOTE

Send an FTP command.

• Syntax – QUOTE "command";
• Description – The QUOTE statement sends an FTP command to the FTP server. Normally, you would only send a command that is not supported by the script language. The command parameter is an FTP command.
• FTP commands
• command <crlf>
• Example

RECV

Receive a file from the FTP server.

• Syntax – RECV remotefile;
• Description – The RECV statement receives a file remotefile from the FTP server.
• The remotefile parameter can be an absolute or relative path. The format of the path is system dependent.
• If the statement completes (that is, a file has been received), Activator processes the message contained in the file as defined by the receive activity of which the method that contains the script is part.
• FTP commands
• PORT <sp> host-port <crlf>
• RETR <sp> remotefile <crlf>
• Example

RENAME

Rename a file on the FTP server.

• Syntax – RENAME file TO newfile;
• Description – The RENAME statement renames a file on the FTP server. If the source and target directories are different, the file is moved to the target directory and then renamed.
• The file parameter can be an absolute or relative path. The format of the path is system dependent.
• The newfile parameter can be an absolute or relative path. The format of the path is system dependent.
• The RENAME statement is often used in conjunction with the SEND or PUT statements to make sure that a file is not accessed until the transfer is complete.
• FTP commands
• RNFR <sp> file <crlf>
• RNTO <sp> newfile <crlf>
• Example

RMDIR

Remove a directory on the FTP server.

• Syntax – RMDIR directory;
• Description – The RMDIR statement removes a directory on the FTP server.
• The directory parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• RMD <sp> directory <crlf>
• Example

SEND

Send a file to the FTP server.

• Syntax – SEND remotefile [APPEND];
• Description – The SEND statement can be used only in send scripts (that is, scripts in an FTP send method). Activator passes a message to the send method. The SEND statement then sends a file containing this message to the FTP server. If the APPEND keyword is specified and the file remotefile exists, the file is appended to the file remotefile. If the APPEND keyword is not specified and the file remotefile exists, by default, the file overwrites the file remotefile.
• The remotefile parameter can be an absolute or relative path. The format of the path is system dependent.
• FTP commands
• If the value of the store-unique setting is off:
• PORT <sp> host-port <crlf>
• STOR <sp> file <crlf>
• If value of the store-unique setting is on:
• PORT <sp> host-port <crlf>
• STOU <sp> remotefile <crlf>
• If the APPEND keyword is specified:
• PORT <sp> host-port <crlf>
• APPE <sp> remotefile <crlf>
• For details of the store-unique setting, see SUNIQUE.
• Example

SUNIQUE

Toggle the value of the store-unique setting.

• Syntax – SUNIQUE;
• Description – The SUNIQUE statement toggles the value of the store-unique setting. It is useful for file transfers using the PUT or SEND statements:
• If the value of the store-unique setting is on, and the file exists on the FTP server, the transferred file is given a unique name. Unfortunately, Activator cannot tell if a unique name has been used or what that name is (this is due to a limitation of FTP), so a RENAME statement may fail when used with the SEND or PUT statements.
• If value of the store-unique setting is off, and the file exists on the FTP server, the file is overwritten.
• When a script starts, the initial value of the store-unique setting is off.
• Example

TYPE

Set the representation type for data transfers.

• Syntax – TYPE type;
• Description – The TYPE statement sets the representation type for data transfers. The type parameter takes one of the following values.

• Value	Description
  "I"	Binary files
  "A"	ASCII files
  "E"	EBCDIC files. The representation type used corresponds to Code page 500 (International Latin 1), which is the code page used on the AS/400 platform.

• FTP commands
• TYPE <sp> type <crlf>
• Example

WHILE

Loop control.

• Syntax – WHILE (expression) {statements}
• Description – The WHILE statement executes the statements in statements if the expression is true. If false, the statements are not executed. See IF ELSE for a full description of the expression parameter.
• Example