Overriding FTP protocol commands - Revision history

JAL at 20:51, 6 May 2014

2014-05-06T20:51:52Z

← Older revision		Revision as of 20:51, 6 May 2014
Line 20:		Line 20:

	You may override the following FTP operations:		You may override the following FTP operations:
	<table>		<table class="thJustBold">
	<tr><th><i>FTP command</i></th>		<tr><th><i>FTP command</i></th>
	<th><i>Operation</i></th></tr>		<th><i>Operation</i></th></tr>

JAL: /* The Override API $functions */

2014-05-06T20:49:54Z

The Override API $functions

← Older revision		Revision as of 20:49, 6 May 2014
Line 43:		Line 43:
	This allows you to scan for syntax errors on		This allows you to scan for syntax errors on
	an interactive thread before running them on a the server.		an interactive thread before running them on a the server.
	<table>		<table class="thJustBold">
	<tr><th>$Ftp_Fail </th>		<tr><th>$Ftp_Fail </th>
	<td><div id="$Ftp_Fail"></div>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. </td></tr>		<td><div id="$Ftp_Fail"></div>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. </td></tr>
Line 56:		Line 56:
	</p>		</p>

	[[#Writing overrides\|"Writing overrides"]] provides specific comments about overriding each of these commands, and it includes some sample overrides. </td></tr>		[[#Writing overrides\|Writing overrides]] provides specific comments about overriding each of these commands, and it includes some sample overrides. </td></tr>

	<tr><th>$Ftp_Get_Current_File </th>		<tr><th>$Ftp_Get_Current_File </th>
Line 65:		Line 65:

	<tr><th>$Ftp_Get_Operand </th>		<tr><th>$Ftp_Get_Operand </th>
	<td><div id="$Ftp_Get_Operand"></div>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\|"Writing overrides"]] for what this function returns in each context. </td></tr>		<td><div id="$Ftp_Get_Operand"></div>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\|Writing overrides]] for what this function returns in each context. </td></tr>

	<tr><th>$Ftp_Get_Old_Name </th>		<tr><th>$Ftp_Get_Old_Name </th>

JAL2: /* The Override API $functions */

2012-02-22T15:53:43Z

The Override API $functions

← Older revision		Revision as of 15:53, 22 February 2012
Line 71:		Line 71:

	<tr><th>$Ftp_Get_Prefix </th>		<tr><th>$Ftp_Get_Prefix </th>
	<td><div id="$Ftp_Get_Prefix"></div>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:		<td><div id="$Ftp_Get_Prefix"></div>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:
	<ul>		<ul>
	<li><code>.</code> (period)		<li><code>.</code> (period)

JAL2 at 15:23, 22 February 2012

2012-02-22T15:23:43Z

← Older revision		Revision as of 15:23, 22 February 2012
Line 3:		Line 3:
	(that is, of an FTP "service command" like <code>STOR</code>,		(that is, of an FTP "service command" like <code>STOR</code>,
	typically implemented as <code>put</code>).		typically implemented as <code>put</code>).
	~~As described in~~ <var>[[#JANUS FTP ON\|JANUS FTP ON]]~~</var>,~~		You specify such an override using the <var>[[Janus FTP Server command reference#JANUS FTP ON\|JANUS FTP ON]]</var> command.
	~~you specify such an override using the <var>JANUS FTP ON~~</var> command.
	The override can apply to a specific folder or to all folders.		The override can apply to a specific folder or to all folders.

Line 22:		Line 21:
	You may override the following FTP operations:		You may override the following FTP operations:
	<table>		<table>
	<tr><th>FTP command </th>		<tr><th><i>FTP command</i></th>
	<th>Operation </th></tr>		<th><i>Operation</i></th></tr>
	<tr><th~~><var~~>STOR~~</var>~~ </th>		<tr><th>STOR </th>
	<td>FTP <code>put</code> </td></tr>		<td>FTP <code>put</code> </td></tr>
	<tr><th~~><var~~>RETR~~</var>~~ </th>		<tr><th>RETR </th>
	<td>FTP <code>get</code> </td></tr>		<td>FTP <code>get</code> </td></tr>
	<tr><th~~><var~~>RNFR/RNTO~~</var>~~ </th>		<tr><th>RNFR/RNTO </th>
	<td>FTP <code>rename</code> </td></tr>		<td>FTP <code>rename</code> </td></tr>
	<tr><th~~><var~~>DELE~~</var>~~ </th>		<tr><th>DELE </th>
	<td>FTP <code>delete</code> </td></tr>		<td>FTP <code>delete</code> </td></tr>
	<tr><th~~><var~~>LIST~~</var>~~ </th>		<tr><th>LIST </th>
	<td>FTP folder list (<code>ls</code>, <code>dir</code>) </td></tr>		<td>FTP folder list (<code>ls</code>, <code>dir</code>) </td></tr>
	</table>		</table>

JAL2: /* See also */

2012-02-21T16:55:12Z

JAL2 at 16:54, 21 February 2012

2012-02-21T16:54:28Z

← Older revision		Revision as of 16:54, 21 February 2012
Line 208:		Line 208:
	Many FTP clients parse LIST output and expect the exact <code>ls -l</code> format.		Many FTP clients parse LIST output and expect the exact <code>ls -l</code> format.
	The client program may crash or produce odd results if the format it wrong.		The client program may crash or produce odd results if the format it wrong.

			==See also==
			The following topics complete the description of <var class="product">Janus FTP Server</var> support:
			<ul>
			<li>[[Janus FTP Server]]
			<li>[[Janus FTP Server examples]]
			<li>[[Janus FTP Server command reference]]
			<li>[[]]
			</ul>

	[[Category:Janus FTP Server]]		[[Category:Janus FTP Server]]

JAL2 at 22:20, 17 February 2012

2012-02-17T22:20:52Z

← Older revision		Revision as of 22:20, 17 February 2012
Line 1:		Line 1:
	For custom processing, you can develop a <var class="product">User Language</var> procedure		For custom processing, you can develop a <var class="product">User Language</var> procedure
	to replace the native Janus FTP implementation of an FTP operation		to replace the native <var class="product">[[Janus FTP Server]]</var> implementation of an FTP operation
	(that is, of an FTP "service command" like <code>STOR</code>,		(that is, of an FTP "service command" like <code>STOR</code>,
	typically implemented as <code>put</code>).		typically implemented as <code>put</code>).

JAL2: Created page with "For custom processing, you can develop a `User Language` procedure to replace the native Janus FTP implementation of an FTP operation (that is, of an FTP..."

2012-02-17T22:19:12Z

Created page with "For custom processing, you can develop a <var class="product">User Language</var> procedure to replace the native Janus FTP implementation of an FTP operation (that is, of an FTP..."

New page

For custom processing, you can develop a <var class="product">User Language</var> procedure
to replace the native Janus FTP implementation of an FTP operation
(that is, of an FTP "service command" like <code>STOR</code>,
typically implemented as <code>put</code>).
As described in <var>[[#JANUS FTP ON|JANUS FTP ON]]</var>,
you specify such an override using the <var>JANUS FTP ON</var> command.
The override can apply to a specific folder or to all folders.

You run an override procedure using a <var class="product">Model 204</var> command
that is specified as part of the <var>CMD</var> clause of <var>JANUS FTP ON</var>.
The <var>CMD</var> clause can be an <var>INCLUDE</var>
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 <var>CMD</var> 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:
<table>
<tr><th>FTP command </th>
<th>Operation </th></tr>
<tr><th><var>STOR</var> </th>
<td>FTP <code>put</code> </td></tr>
<tr><th><var>RETR</var> </th>
<td>FTP <code>get</code> </td></tr>
<tr><th><var>RNFR/RNTO</var> </th>
<td>FTP <code>rename</code> </td></tr>
<tr><th><var>DELE</var> </th>
<td>FTP <code>delete</code> </td></tr>
<tr><th><var>LIST</var> </th>
<td>FTP folder list (<code>ls</code>, <code>dir</code>) </td></tr>
</table>

===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-<var class="product">FTP Server</var> thread,
they do nothing, and they return either a zero length string or <code>0</code>,
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.
<table>
<tr><th>$Ftp_Fail </th>
<td><div id="$Ftp_Fail"></div>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. </td></tr>
<tr><th>$Ftp_Get_Command </th>
<td><div id="$Ftp_Get_Command"></div>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:
<p class="code">DELE
LIST
NLST
RETR
RNTO
STOR
</p>

[[#Writing overrides|"Writing overrides"]] provides specific comments about overriding each of these commands, and it includes some sample overrides. </td></tr>

<tr><th>$Ftp_Get_Current_File </th>
<td><div id="$Ftp_Get_Current_File"></div>Returns the <var class="product">Model 204</var> file mapped to the current folder, if any. If no such file exists, this function returns a null (zero length) string. </td></tr>

<tr><th>$Ftp_Get_Current_Folder </th>
<td><div id="$Ftp_Get_Current_Folder"></div>Returns the name of the current folder, (for example, <code>/PUB</code>). </td></tr>

<tr><th>$Ftp_Get_Operand </th>
<td><div id="$Ftp_Get_Operand"></div>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|"Writing overrides"]] for what this function returns in each context. </td></tr>

<tr><th>$Ftp_Get_Old_Name </th>
<td><div id="$Ftp_Get_Old_Name"></div>Returns the name of the procedure being renamed. <var>$Ftp_Get_Old_Name</var> is used only for overriding rename (RNTO). If called in a context other than rename, it returns a null (zero length) string. </td></tr>

<tr><th>$Ftp_Get_Prefix </th>
<td><div id="$Ftp_Get_Prefix"></div>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:
<ul>
<li><code>.</code> (period)
<li><code>/</code> (slash)
<li><code>''</code> (null string) </ul> </td></tr>
<tr><th>$Ftp_Get_Transfer_Type </th>
<td><div id="$Ftp_Get_Transfer_Type"></div>Returns the current FTP transfer mode, as specified by the FTP client. Its value is either of these:
<ul>
<li><code>I</code> (binary)
<li><code>A</code> (ASCII text) </ul> </td></tr>
</table>

===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.

<var>$Ftp_Get_Operand</var> returns the name of the procedure being stored.

To read procedure 0 for processing, you can use the Sirius
$functions <var>[[$ProcOpn]]</var>, <var>[[$ProcGet]]</var>, <var>[[$ProcCls]]</var>, and <var>[[$ProcDat]]</var>.

Below is a skeleton of a STOR override:
<p class="code">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
</p>

====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.

<var>$Ftp_Get_Operand</var> returns the name of the procedure being fetched.

To place the data in procedure 0, you may use one of the following techniques:
<ul>
<li><var>$Bldproc</var>
<li><var>USE PROC 0</var>
</ul>

Below is a skeleton of a RETR override:
<p class="code">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
</p>

====Overriding RNTO (rename)====
In a rename override, <var>$Ftp_Get_Operand</var> returns the new name of the procedure,
while <var>$Ftp_Get_Old_Name</var> 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, <var>$Ftp_Get_Operand</var> 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.

<var>$Ftp_Get_Operand</var> 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:
<ul>
<li>Narrow mode (<var>$Ftp_Get_Command</var> returns <code>NLST</code>).
You must place a simple list of file names, one per line, in procedure 0.
<li>Wide mode (<var>$Ftp_Get_Command</var> returns <code>LIST</code>).
You must place a list of files, in UNIX <code>ls -l</code> format, in procedure 0.
</ul>

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

[[Category:Janus FTP Server]]

← Older revision		Revision as of 16:55, 21 February 2012
Line 215:		Line 215:
	<li>[[Janus FTP Server examples]]		<li>[[Janus FTP Server examples]]
	<li>[[Janus FTP Server command reference]]		<li>[[Janus FTP Server command reference]]
	<li>[[]]		<li>[[Integrating Janus FTP and Janus Web Server]]
	</ul>		</ul>

	[[Category:Janus FTP Server]]		[[Category:Janus FTP Server]]