Overriding FTP protocol commands

For custom processing, you can develop a User Language procedure to replace the native Janus FTP Server implementation of an FTP operation (that is, of an FTP "service command" like STOR, typically implemented as put). You specify such an override using the JANUS FTP ON command. The override can apply to a specific folder or to all folders.

You run an override procedure using a Model 204 command that is specified as part of the CMD clause of JANUS FTP ON. The CMD clause can be an INCLUDE of a procedure, or it can be an invocation of a subsystem that implements the operation you are overriding. You may also specify one or more files or groups to be opened prior to running the CMD command(s).

An override needs to have access to certain values (such as a file name) to be able to perform the operation. It also needs to be able to signal whether an operation failed. These cababilities are provided as a series of $functions, which are described in the next section.

You may override the following FTP operations:

FTP command	Operation
STOR	FTP put
RETR	FTP get
RNFR/RNTO	FTP rename
DELE	FTP delete
LIST	FTP folder list (ls, dir)

The Override API $functions

The override functions, described below, provide the needed information and control to write overrides. They all take no arguments. If called on a non-FTP Server thread, they do nothing, and they return either a zero length string or 0, depending on whether the function returns a number or a string. This allows you to scan for syntax errors on an interactive thread before running them on a the server.

$Ftp_Fail	Returns a failure status code (500) to the FTP client when the override finishes. Unless this function is called, a success status code is returned when the override finishes.
$Ftp_Get_Command	Returns the FTP command that is the subject of the override. It is useful in a case where one override procedure implements multiple overrides. Its value is always one of the following: DELE LIST NLST RETR RNTO STOR Writing overrides provides specific comments about overriding each of these commands, and it includes some sample overrides.
$Ftp_Get_Current_File	Returns the Model 204 file mapped to the current folder, if any. If no such file exists, this function returns a null (zero length) string.
$Ftp_Get_Current_Folder	Returns the name of the current folder, (for example, /PUB).
$Ftp_Get_Operand	Returns the value of the entity being operated on by the FTP command that is being overridden. This value varies with the command being overridden. See the individual sections in Writing overrides for what this function returns in each context.
$Ftp_Get_Old_Name	Returns the name of the procedure being renamed. $Ftp_Get_Old_Name is used only for overriding rename (RNTO). If called in a context other than rename, it returns a null (zero length) string.
$Ftp_Get_Prefix	Returns the prefix character, if the folder is using prefixing; returns a zero length string if the folder is not prefixed. Its value is always one of the following: . (period) / (slash) '' (null string)
$Ftp_Get_Transfer_Type	Returns the current FTP transfer mode, as specified by the FTP client. Its value is either of these: I (binary) A (ASCII text)

Writing overrides

The following sections present the requirements for an override for a particular operation, along with the override API $functions that are applicable.

Overriding STOR (put)

Before an override for STOR is called, Janus FTP obtains the file from the client and places it in temporary procedure 0. It is the responsibility of the override to take that procedure and store it.

$Ftp_Get_Operand returns the name of the procedure being stored.

To read procedure 0 for processing, you can use the Sirius $functions $ProcOpn, $ProcGet, $ProcCls, and $ProcDat.

Below is a skeleton of a STOR override:

Begin VARIABLES ARE UNDEFINED %rc Float %buf String Len 255 * Loop on the lines in proc 0, * which was loaded by the JANUS FTP Server. %rc = $procopn(0) %buf = $procget Repeat While ($Len(%buf)) * Do something with the * data in %buf. Perhaps store * it in a file and use * $Ftp_Get_Operand as a key. %buf = $procget End Repeat * If the operation failed, * send a failure indicator to * the FTP client. If ( Some Failure Test ) Then %rc = $ftp_fail End If End

Overriding RETR (get)

If you are writing an override for RETR, you must place any data you want to send back to the FTP client in temporary procedure 0. After the override commands are executed, the contents of temporary procedure 0 are sent to the FTP client.

$Ftp_Get_Operand returns the name of the procedure being fetched.

To place the data in procedure 0, you may use one of the following techniques:

• $Bldproc
• USE PROC 0

Below is a skeleton of a RETR override:

DELETE PROC 0 USE PROC 0 Begin VARIABLES ARE UNDEFINED %rc Float * Find some records, maybe * use $Ftp_Get_Operand in the criteria. For Each Record Where .... * PRINT some info from * the file. Since USE is * active, the lines will * go to proc 0, which will * be sent by JANUS FTP * to the FTP client. Print whatever End For * If the operation failed, * send a failure indicator * to the FTP client. If ( Some Failure Test ) Then %rc = $ftp_fail End If End

Overriding RNTO (rename)

In a rename override, $Ftp_Get_Operand returns the new name of the procedure, while $Ftp_Get_Old_Name returns the old name. How this is implemented in the override is completely up to you.

There is no override for the RNFR command.

Overriding DELE (delete)

In a delete override, $Ftp_Get_Operand returns the name of the item to be deleted. How this is implemented in the override is completely up to you.

Overriding LIST (ls, dir)

Like a RETR override, a LIST override must place the listing to be returned in temporary procedure 0. After the override commands are executed, the contents of temporary procedure 0 are sent to the FTP client.

$Ftp_Get_Operand returns the wildcard pattern used to select file names, or it returns the null string (zero length) if no file pattern was specified.

A LIST override must work in two modes:

• Narrow mode ($Ftp_Get_Command returns NLST). You must place a simple list of file names, one per line, in procedure 0.
• Wide mode ($Ftp_Get_Command returns LIST). You must place a list of files, in UNIX ls -l format, in procedure 0.

Note: If you are overriding LIST, take extreme care with formatting. Many FTP clients parse LIST output and expect the exact ls -l format. The client program may crash or produce odd results if the format it wrong.

See also

The following topics complete the description of Janus FTP Server support:

• Janus FTP Server
• Janus FTP Server examples
• Janus FTP Server command reference
• Integrating Janus FTP and Janus Web Server