Checked FTP is a general purpose command line utility that will transfer a directory of files to and from an FTP server. The transfer, however, is performed in a controlled manner. The purpose of Checked FTP is to automate the file transfer while allowing the sending and receiving system to perform additional processes during the transfer process. The list below indicates the normal workflow of the system:

1. The sending system performs required processes, if any.
2. The sending system notifies Checked FTP that it is ready to transfer.
3. Checked FTP transfers the files to the receiving system.
4. Checked FTP notifies the receiving system that the transfer is complete.
5. The receiving system performs required processes, if any.
6. The receiving system notifies Checked FTP that the transferred files are processed.
7. Checked FTP clears or archives the directories on both sending and receiving systems.

Please read the following for additional information:

• Usage: command line syntax and usage logic
• Return codes
• How Checked FTP works
• Limitations

Checked FTP is can be run from the command line. To use it you need a Java runtime environment (version 1.2.2 or better). The command line is:

    java com.djinnsoft.jade.tools.CheckedFtp
	     remote[:port]
	     username[/password]
	     directory
	     upload|download
	     [-archive]
	     [-PASV]
	     [-quiet|-verbose]

remote[:port]

The domain name or IP address of the remote system, with an optional port.

username[/password]

The username and (optional) password on the remote system.

directory

Is the directory to be copied to or from the FTP server.

upload|download

Defines which way the directory should be copied.

-archive

If this flag is set Checked FTP will archive directories by renaming rather then deleting them. Directories are renamed to directory.YYYYMMDD.HHMMSS where YYYYMMDD.HHMMSS is the current timestamp for the Checked FTP process.

-PASV

If this flag is set Checked FTP will use passive mode when performing ftp operations.

-quiet

Run without any output, except errors.

-verbose

Run with additional status messages.

It is possible to invoke Checked FTP programmatically rather than the command-line. To do so, an instance of the CheckedFtp class should be created, the appropriate properties set, and its process method invoked. See the api for details.

Checked FTP command line generates the following return codes to the operating system:

Return Code	Meaning
0	Execution was successful. This may mean that no files where transferred and Checked FTP is waiting for the sending or receiving systems to complete processing.
1	Checked FTP was interrupted during processing or has detected a recoverable error. Subsequent invocations of Checked FTP should be able to complete the transfer.
2	Checked FTP was not able to connect to the remote system.
-1	A non-recoverable error occurred reading the remote directory.
-2	A non-recoverable error occurred reading the local directory.
-3	An internal error in Checked FTP.

For non-0 return codes a text error message giving more details of the error is written to standard error.

Checked FTP is intended to be run repeatedly to complete a file transfer. It is recommended that it is scheduled using a chron job (on UNIX), the at command (on Windows) or any other scheduling mechanism.

When the sending system wants to send files to the receiving system, the sending system must do the following:

1. Create the directory to be sent (if not already present).
2. Fill it with files to be transferred.
3. Perform any additional processing, as needed.
4. The last action must be the creation of a file named directory/commands. This file may be empty but must be readable by Checked FTP when all data is ready to be sent (not before). Its presence signals Checked FTP to transfer the files the next time Checked FTP is invoked.
5. Once the file transfer has been acknowledged by the receiving systems (see the steps below), Checked FTP will delete or archive the directory.

In order to process a directory the receiving system must do the following:

1. Query for the presence of a directory/commands file. The presence of this file indicates that the file transfer is complete and the directory may be processed.
2. Perform any processing against the files in the directory.
3. When processing is finished create a file named directory/done. This file may be empty but must only be readable by Checked FTP. Its presence signals Checked FTP that the transferred files have been processed. The next invocation of Checked FTP will delete or archive the files on both the sending and receiving systems.
4. If the receiving system wishes the files to be resent, it should delete the directory/commands file. The absence of this file will trigger a file transfer the next time Checked FTP is invoked.

In a sense, Checked FTP is a state machine. When invoked, it reads files on both the local and remote system to determine what action to take. It then completes the action and exits. Here is a summary of the actions taken:

State	Source Files	Destination Files		Action
	command	command	done
0	absent			Waiting for sender: Either the directory is not readable or the source system has not finished writing it. No action will be taken.
1	present	absent		Upload directory: The transfer is either (a) not started (b) interrupted or (c) re-requested by the receiving system. CheckedFTP will re-transmit all files. The last file created in the destination directory will be command. This file will indicate a successful transfer.
2	present	present	absent	Waiting for receiver: Receiver is processing files. No action taken.
3	present	present	present	Transfer confirmed: Receiver has completed processing files. Checked FTP will attempt to delete or archive the directory.

Please note that the state is independent of the command-line return values.

The following is a list of restrictions of the Checked FTP use:

• Checked FTP is an ftp client. It always runs from a client machine and connects to an ftp server.
• All files are transferred in binary mode.
• To transmit files in two directions, two directories are needed (one for each direction). It is not possible to use the same directory for bi-directional operation.