Janus FTP Server

Janus FTP support allows you to set up one or more FTP servers within a Model 204 online. You use JANUS commands to define and start a TCP/IP listening port for each Janus FTP Server, and you use JANUS FTP commands to specify operating and access rules for each server. Janus FTP servers can then be accessed with the FTP client of your choice to copy procedures into and out of Model 204 procedure files.

The FTP client may be running on any platform that can make a TCP/IP connection to the online. Many tools such as code management systems and editors have built in FTP clients which can now be used with Model 204 procedures and procedure files.

Janus FTP servers can peacefully coexist with any other FTP servers you may be running.

You must be licensed for Janus Sockets and Janus TCP/IP Base in order to use Janus FTP support.

Feature description

This section provides an overview of the capabilities and features of Janus FTP Server support. The section includes these topics:

• "Feature summary"
• "Key concepts"
• "Command overview"
• "Socket and procedure handling"
• "Security and Janus FTP Server"
• "FTP features not currently supported"
• "Supported FTP protocol commands"

Feature summary

The following capabilities are provided by the Janus FTP Server.

• Model 204 procedures may be downloaded to a local platform using any FTP client.
• Model 204 procedures may be added, replaced, deleted, and renamed with any FTP client.
• Procedure listings are supported (the FTP protocol LIST command). This permits GUI FTP clients such as WS_FTP< and others to render lists of Model 204 procedures.
• EBCDIC/ASCII translation in both directions is automatic and transparent for FTP ASCII text transfers.
• Binary file transfers (FTP TYPE I are supported to permit transfer of binary files such as images (.JPG, .GIF, etc.) and Java applets (.class, .jar, etc.).
• JANUS FTP commands are used to map the standard UNIX folder structure that FTP clients expect to Model 204 procedures and procedure files. Multiple Model 204 procedure files may be accessed from a single port with a Janus FTP server. This mapping effectively creates folders that can be navigated by FTP clients using the standard FTP cwd command (change working directory/folder). For more information, see "Folder mapping".
• FTP user authentication is based on Model 204 user IDs and passwords. It automatically uses whatever security package (for example, RACF), that your online uses to authenticate logins.
• Anonymous FTP is available. For security, anonymous FTP is off by default when an FTP Server is created with JANUS DEFINE. Extra syntax is required to enable anonymous FTP, which makes it impossible to accidentally enable it when you are creating an FTP server. For more information, see "Anonymous FTP".
• Active and passive FTP are supported. Passive is more secure, and Sirius recommends using passive FTP where possible. However, some older and simpler FTP clients only work with active FTP (for example, the Windows command line FTP client). Passive FTP is considered "firewall friendly," since it does not require the FTP client to open up TCP/IP server sockets, which is commonly viewed as a security exposure, thus prevented by many firewalls.
• All three operating systems are supported (MVS, VM, and VSE).
• Within an online, you can run as many FTP servers as you want, using different port numbers for each. There is no requirement to use the default FTP port number (21). This lets you run another FTP server on the default FTP port and run Janus FTP servers on any other port numbers you want. However, it is desirable to use the default port when possible, since client software will have to be reconfigured otherwise. (By default, all FTP clients try to connect to port 21.)
• For advanced applications, you can write "overrides" for FTP commands, where you provide a custom implementation for a command to perform application-specific processing. Overrides are written in User Language. A possible use of an override is to read and write records from a Model 204 file using FTP. For more information, see "Overriding FTP protocol commands".
• You can use the procedure name suffix (for example, .HTML) to control the transfer mode of a file (text vs. binary). For more information, see JANUS FTP SUFFIX.

Key concepts

This section covers the key concepts to master to use the Janus FTP Server. It is vital to grasp these concepts before learning specific commands.

Folder mapping

The most important concept to understand when using the Janus FTP Server is the concept of folder mapping. FTP clients are typically designed to work with a UNIX-style file system, that is, a hierarchy of folders, where folder names are separated by forward slashes (/). Model 204 files are basically a flat list of procedures without any concept of hierarchy.

Janus FTP Server provides a command (JANUS FTP ASSIGN) that lets you create folders. Folders are referenced by an FTP client to locate procedures, which the FTP client sees as files. A folder is essentially a logical name an FTP client references as a UNIX-style folder.

Janus FTP Server also has the concept of a "current folder." A Janus FTP server returns the name of the current folder in response to the FTP PWD (print working directory) command. The current folder is where FTP operations such as get and put (RETR and STOR) look for the procedures referenced; it functions like a current directory or folder in UNIX or MS DOS.

When a folder is defined, it may be associated with a Model 204 file. A folder defined with a file can be the target of FTP get, put, rename, and delete operations, if the client user has appropriate permissions. Folders without files are legal. They can be used for modelling intermediate levels in a hierarchy, or they can be used in conjunction with overrides.

This level of indirection in the server lets FTP clients avoid storing procedure file names (the friendlier FTP clients remember server path information). This permits the system manager to switch procedure files without breaking users' FTP client setups. A user simply changes the folder mapping to point to the new procedure file.

Folder names

The names of FTP folders must obey the following syntax rules:

• They begin with a forward slash (/), are 2 to 63 characters in length, and may not end with a slash.
• They consist of groups of alphanumeric characters, separated by single forward slashes (in UNIX or URL style).
• They may not contain consecutive slashes (//AA and /A//B are not permitted).
• They are case insensitive.
• They may not contain embedded blanks.

Examples of valid FTP folder names include:

/HOME /G/L/W /STOOGES /STOOGES/HOME

Prefixing

By default, a folder mapping is simply a way to connect a folder seen by the FTP client to a Model 204 file. However, the prefixing option permits the folder name to be automatically made part of the procedure name in a manner transparent to the FTP client. Prefixing is off by default, but it can be enabled using the PREFIX parameter on the #JANUS FTP ASSIGN command.

Prefixing a folder has the characteristics listed below. In the examples, assume /STOOGES is a folder with prefixing turned on, and MOE and LARRY are procedure or file names.

• Procedures/files stored in a prefixed folder are stored with the procedure name prefixed with the folder name. For example, MOE is stored as /STOOGES/MOE.
• When an FTP client asks to fetch a procedure, the FTP Server looks for it by prefixing its name with the folder name. For example, if the FTP client asks for LARRY, the server searches for /STOOGES/LARRY.
• On requests for folder listings (FTP LIST command), only those procedures whose names are prefixed with the folder name are returned. For example, /STOOGES/MOE and /STOOGES/LARRY are listed, but the procedures FOO and /JETSONS/GEORGE are not.
• Mapping several folders that have prefixing enabled to one procedure file lets you segregate work by developer within one procedure file. Since security for Janus FTP is administered at the folder level, it can easily be set up so that each developer can only update their own files.
• Normally, the folder name is used as a prefix with its slash (/) or slashes, and a slash separates the folder from the file name. However, optionally, a period can be used to replace all such slashes (for example, /STOOGES/MOE becomes .STOOGES.MOE).

  Note: This replacement is only done internally: the FTP clients see only the slashes.

Folder security

FTP folder access rights are granted to one or more users in either of the following ways:

• When a folder is created with JANUS FTP ASSIGN, default access rights for all users (not including anonymous access) may be assigned.
• A user, user group, all users (except anonymous), or the anonymous user may be given access rights to a folder using JANUS FTP ALLOW.

In addition, either of these types of access to the folder may be granted to the user or users given access:

READ	FTP get (RETR command) and directory listings are permitted. Also, the FTP client or user can change directory (FTP protocol CWD command) into this directory.
WRITE	READ privileges plus permission for FTP put, delete, and rename (STOR, DEL, RNFR, and RNTO).

A user other than the anonymous user might be granted access rights from more than one source:

• He or she might be granted access explicitly with JANUS FTP ALLOW.
• He or she might be a member of one or more groups granted access with JANUS FTP ALLOW.
• JANUS FTP ALLOW might be specified with ALL.
• The folder might have its default access set by JANUS FTP ASSIGN with DEFAULTPRIVS.

If multiple sources are granting access, the user is granted the highest access specified by any of the sources giving the user access. (The access rights are aggregated.)

Home folders

Much like UNIX and other folder-tree based systems, FTP has the concept of a home folder location, where the user is placed after successfully connecting to and logging in to the FTP server. Janus FTP Server implements this concept with a JANUS command (JANUS FTP HOME) that permits setting up a home folder for a user, a group of users, all users (excluding anonymous), or the anonymous user.

A user must have a home folder specified, or FTP login is rejected. In addition, the user must have at least READ privileges for the folder specified as their home folder. This is checked at login; a login is rejected if the user does not have at least READ access to their home folder.

The root folder ( / )

In UNIX systems, the root folder is indicated by a forward slash (/). In Janus FTP Server, you may not define this folder; it is automatically defined for you. If you navigate (change directory) to folder "/" in your FTP client, you see a list of all first-level folders. First-level folders are those that have only one part (for example, /STOOGES, /JETSONS).

Anonymous FTP

Within the context of Janus FTP Server, anonymous FTP is defined as FTP access that does not require a valid Model 204 user ID. Off by default when an FTP server is created, anonymous access is enabled by the ANONYMOUS parameter on JANUS DEFINE.

By default, anonymous access is achieved by connecting as user anonymous, but you can change that value with the JANUS DEFINE command. An anonymous user's password is not verified.

Command overview

A detailed reference of the Janus commands that pertain to FTP servers is presented in "Janus FTP Server command reference". The following overview is intended to introduce the commands and make it easier to understand the examples in the "FTP Server examples" section.

JANUS DEFINE name num FTPSERVER ...

Creates FTP servers in the online.

JANUS FTP ASSIGN

Creates FTP folders and maps them to Model 204 files, as described in "Folder mapping".

JANUS FTP DEASSIGN

Removes FTP folders.

JANUS FTP ALLOW

Grants read or write access to a folder created with JANUS FTP ASSIGN.

JANUS FTP DISALLOW

Revokes read or write access to a folder.

JANUS FTP HOME

Specifies a home folder (initial location at login) for a user. Once connected and logged in, a user may navigate to folders to which they have been granted at least read access.

JANUS FTP ON

Sets up overrides, by specifying files to be opened and commands to be executed when a specific FTP operation is performed.

JANUS FTP SUFFIX

Allows specification of the transfer mode (text or binary) of procedures/files by suffix (for example, .html, .xml).

JANUS DISPLAYSOCK

Displays a report of the rules created with FTP ASSIGN, FTP ALLOW, FTP HOME, FTP ON, and FTP SUFFIX if executed for an FTPSERVER port.

Socket and procedure handling

This section provides notes about how Janus FTP Server works with sockets and Model 204 procedures.

Sockets

• The Janus FTP Server is implemented as a special type of Janus server socket. Consequently, the JANUS SRVSOCK command may be used to control access to an FTP Server.
• When an FTP Server performs active mode file transfers, it opens a client TCP/IP socket back to a server socket that the FTP client opens. If you want to enable active file transfers, you must set up a Janus CLSOCK socket that the FTP server can use. See JANUS DEFINE, below, for more information. This lets you have additional security controls: you may place whatever restrictions you like on the client socket based on your site's security policies. A useful way to think about the difference between active and passive file transfer mode is the following:
  • In passive mode, FTP is a true client/server protocol where the server only opens server sockets and the client only opens client sockets.
  • In active mode, FTP is more like a peer-to-peer protocol where both the client and server open both client and server sockets.

The example in "FTP client and server interaction" contains a small demonstration of passive FTP socket handling.

Procedures

• When a procedure is renamed via FTP, the standard Model 204 rename operation is performed. This leaves the old name as an alias. While this is not standard FTP behaviour, it is the standard way rename operations work in Model 204.
• When a binary file (for example, a .jpg file) is uploaded by the Janus FTP Server in binary transfer mode, it is stored in standard base64 binary format. Procedures that were stored by Janus Web Server in either binary or base64 format may be retrieved using Janus FTP Server.
• All uploaded files are copied into CCATEMP. This way, if a network or browser problem prevents the entire file from being transferred, the request can be discarded without a risk of leaving partial data in a procedure. Once all the data from a request has been received into Model 204, the file is simply copied into the target procedure, perhaps being converted to the base64 format if the file consists of non-text data. When a procedure is being updated, Janus FTP attempts to get an exclusive lock on the procedure before doing the update. If it is unable to obtain an exclusive procedure lock, the request fails. The exclusive lock is only held while data is copied from CCATEMP to the procedure. This means the following:
  1. Once the copy operation starts, it completes regardless of the status of the network connection; there is no risk of leaving behind a partial procedure.
  2. The exclusive lock on a procedure is generally held very briefly (typically a few milliseconds), so it is not likely to disrupt a download for the same procedure.
  3. This is a simple "last-to-save, wins" approach, and it offers no update management for the procedure file.

Security and Janus FTP Server

A very security-centric approach was taken in the design of the Janus FTP Server. This is seen in the following characteristics:

• There is no FTP access at all unless a JANUS DEFINE command to create an FTP server is issued.
• No procedure file is available to FTP unless FTP access to it is specifically granted (using FTP ASSIGN and FTP ALLOW).
• By default, there is no anonymous access to Janus FTP servers.
• The ALL option on FTP ALLOW and the DEFAULTPRIVS option on FTP ASSIGN do not include anonymous access. Anonymous access must always be explicitly granted.
• Since active FTP is widely viewed as less secure, you can create an FTP (passive) server that does not permit active connections. To create a passive server, simply do not specify the CLIENTSOCKET parameter on the JANUS DEFINE command for the FTP server. Without CLIENTSOCKET, only passive data transfers are enabled.

FTP features not currently supported

The following FTP features are not currently supported by Janus FTP. They will be considered for possible future releases.

• Restart of aborted transfers
• Client side directory/folder manipulation with mkdir and rmdir (MKD and RMD)
• SSL (Secure Sockets Layer) data transmission

Supported FTP protocol commands

FTP is essentially a command response protocol, where a server responds to text commands. The FTP protocol specifies a set of commands to which a server must respond. Janus FTP support implements the following FTP protocol commands:

• USER and PASS, to process logins.
• QUIT, to end a session gracefully.
• PORT, to initiate active transfers.
• SYST, to respond to system type queries. Many FTP clients send SYST to probe the FTP server type. Janus FTP answers UNIX, then emulates a UNIX-style FTP server. This works with all FTP clients, since they all support UNIX. If Janus FTP answered VM/MVS/VSE, many FTP clients would not work.
• TYPE, to select between BINARY and ASCII (text) transfers.
• PASV, to initiate passive transfers.
• PWD/XPWD, to return the working directory/folder.
• CWD/CDUP, to change folders.
• RNFR/RNTO, to do renames.
• STOR, to store/put/upload files.
• RETR, to get/fetch/download files.
• DELE, to delete files.
• LIST/NLST, to get folder/directory listings.

Note: The syntax of these commands is not the same as that of the more or less standard command line FTP clients, nor is there an exact one-to-one correspondence between the command sets. An FTP client constructs these commands "under the covers" to communicate with the FTP server.

FTP Server examples

The following two short examples show how to set up Janus FTP Servers in an online. The Janus FTP commands in the examples are introduced in "Command overview" and described in greater detail in "Janus FTP Server command reference".

A simple development environment

In this example, a Janus FTP Server is set up for a development environment with the following characteristics.

• Test as well as production procedure files, each type defined within its own folder (/TEST and /PROD). These are set up with JANUS FTP ASSIGN.
• Everyone can read from the test procedure file. This is set up with the DEFAULTPRIVS parameter on the ASSIGN for /TEST.
• A Janus user group is used for the development team. This allows fewer FTP commands to be used, since the ALLOW commands can then reference the group using the USRGROUP parameter.
• All developers can update the test procedure file. This is set up with the JANUS FTP ALLOW for /TEST.
• All developers can read the production procedure file. This is set up with the first JANUS FTP ALLOW for /PROD.
• Only the team leader (Moe) can update production. This is set up with the second JANUS FTP ALLOW for /PROD.
• Everyone has the test area as a home folder. This is set up with the HOME that references ALL.
• There will be no anonymous FTP access (no ANONYMOUS parameter is specified on the JANUS DEFINE for the FTP Server).
• Active FTP is supported (perhaps the whole system is behind a firewall, so there is no exposure, and active permits a greater variety of FTP clients). Active is enabled by:
  1. Specifying a CLIENTSOCKET value on the JANUS DEFINE for the FTPDEVEL FTP server
  2. Defining a CLSOCK port whose name is the CLIENTSOCKET value

The commands for the development FTP Server follow. Notice that to enable active transfers, the client (CLSOCK) port must be started as well as the main FTP port.

* Create the development team JANUS DEFUSG STOOGES MOE LARRY CURLEY SHEMP GLW * FTP server on port 3000 JANUS DEFINE FTPDEVEL 3000 - FTPSERVER 4 - CLIENTSOCKET FTPDCLIENT - AUDTERM - PASVPORT 3001 - BINDADDR 198.242.244.100 * Client port definition for active transfers JANUS DEFINE FTPDCLIENT * - CLSOCK 5 REMOTE * * - SOCKPMAX 5 JANUS CLSOCK FTPDCLIENT ALLOW * Set up ftp access to test area. * By default, all users can read it. JANUS FTP FTPDEVEL ASSIGN /TEST TO FILE FTPTEST DEFAULTPRIVS READ * Set up ftp access to prod area. * There is no default access. JANUS FTP FTPDEVEL ASSIGN /PROD TO FILE FTPPROD * All developers can update test. JANUS FTP FTPDEVEL ALLOW /TEST - WRITE TO USGROUP STOOGES * All developers can read prod. JANUS FTP FTPDEVEL ALLOW /PROD - READ TO USGROUP STOOGES * Moe is the boss; he can update production. JANUS FTP FTPDEVEL ALLOW /PROD - WRITE TO USER MOE * All start out with test as a home folder. JANUS FTP FTPDEVEL HOME /TEST TO ALL * Start them up. JANUS START FTPDEVEL JANUS START FTPDCLIENT

A simple anonymous FTP Server

This example sets up a public anonymous FTP Server from which files may be downloaded — a great way to distribute files. It has the following characteristics:

• A single folder, /PUB, that anonymous users read from to download files.
• The big boss, Moe, is the only one who can upload files to the server.
• Prefixing, using the default slash character (/), is displayed (see the PREFIX parameter on the FTP ASSIGN command for /PUB).
• Only passive FTP file transfers are permitted (no CLIENTSOCKET is specified on the JANUS DEFINE command).

The commands for an anonymous FTP Server follow:

* Create FTP server on port 2121, anonymous allowed, * only passive access is provided. JANUS DEFINE FTPANON 2121 FTPSERVER 10 - ANONYMOUS * - AUDTERM - PASVPORT 2555 - BINDADDR 198.242.244.100 * Create public folder and use prefixing. JANUS FTP FTPANON ASSIGN /PUB TO FILE FTPTEST PREFIX * Grant Anonymous read access to the /PUB folder. JANUS FTP FTPANON ALLOW /PUB READ TO ANONYMOUS * Make user MOE the only person who can place files * in the Anonymous FTP area. JANUS FTP FTPANON ALLOW /PUB WRITE TO USER MOE * Make /PUB the home folder for Anonymous users and Moe. JANUS FTP FTPANON HOME /PUB TO ANONYMOUS JANUS FTP FTPANON HOME /PUB TO USER MOE JANUS START FTPANON JANUS DISPLAYSOCK FTPANON

After connecting to the FTP server from his FTP client, MOE puts/uploads the README file into his home folder, /PUB. A fragment from a DISPLAY PROC LIST result for the FTPTEST file confirms the prefixing used in the example. Procedure README is stored with the folder name as a prefix:

/PUB/README 10/07/04 12:08:28 124 MOE

FTP client and server interaction

To connect to the Janus FTP server, FTP clients must specify (in the way that is appropriate for the particular tool) both the host ID and port of the FTP server. A command line client trying to connect to the Janus FTP Server defined in "A simple anonymous FTP Server", for example, might use:

open 198.242.244.100 2121

The FTP server correctly handles the type of upload (text or binary) that the client FTP package indicates. This indication may be from an explicit user selection of a type, or it may be from an FTP client that auto detects the appropriate mode. By default, the server assumes type A (ASCII, with translation to EBCDIC) until notified otherwise.

Users can upload multiple files at a time (in the way that is appropriate for the particular client tool), although the protocol dictates that multiple-file requests be handled internally as multiple individual-file transfers. Users can also upload directories and subdirectories (if and only if a matching folder structure is predefined for the server). For more information about defining these folder structures, see JANUS FTP ASSIGN.

Since the Janus FTP Server uses a Janus socket port and supports the TRACE parameter (JANUS DEFINE command) and JANUS TRACE command for the port, you can debug your FTP application by setting TRACE and viewing the Model 204 audit trail, as well as by invoking debugging and viewing your client tool log. In the audit trail, Janus FTP server and client interactions are helpfully marked with arrow indicators that identify whether RK lines are messages from the client to the server or from the server to the client.

For example, the lines below show Janus SirScan output (when TRACE is set at its default value, X'00') for a failed upload of a file to an FTP server. FTP C->S: identifies messages from the FTP client to the server, and FTP S->C: the reverse.

19095422 2 1 RK TERM: FTP C->S: PWD 19095422 2 1 RK TERM: FTP S->C: 257 "/TEST/PUBS" 19095422 2 1 RK TERM: FTP C->S: TYPE A 19095422 2 1 RK TERM: FTP S->C: 200 ASCII mode enabled. EBCDIC conversion automatic. 19095423 2 1 RK TERM: FTP C->S: PASV 19095423 2 1 RK TERM: FTP S->C: 227 Entering passive mode (198,242,244,100,12,42) 19095423 3 2 AD MSIR.0114: Processing connection for port FTPPSV3004 from 198.242.244.36 19095423 3 2 RK TERM: FTP: PASV Server Socket connect. 19095423 2 1 RK TERM: FTP C->S: STOR COLORNOTES 19095423 2 1 RK TERM: FTP S->C: 150 storing: "/TEST/PUBS/COLORNOTES" 19095423 3 2 RK TERM: FTP: PASV Server Socket wakes up. 19095423 3 2 RK TERM: FTP: PASV Server Open. 19095424 3 2 RK TERM: *** M204.0620: FILE FTPTEST OPENED 19095424 3 2 RK TERM: *** M204.1203: FILE FTPTEST WAS LAST UPDATED ON 05.038 FEB 07 18.52.41 19095424 3 2 RK TERM: FTP: PASV Server Start XFER. 19095424 3 2 RK TERM: FTP: PASV Server End XFER. 19095424 3 2 LI 19095424 3 2 MS M204.1029: USER CONNECTION LOST (PHONE WAS HUNG UP) 19095424 3 2 AD M204.1022: USER RESTARTING SOFTLY 19095424 3 2 ST USERID='MOE' ACCOUNT='NO ACCOUNT' CNCT=12 SQWR=2 CPU=10 MOVE=7 AUDIT=13 DKPR=3 19095424 3 2 AD M204.0352: IODEV=15, OK MOE NO ACCOUNT LOGOUT 05.039 FEB 08 19.09.54 -52 C6F2F410 19095424 3 2 AD M204.1024: USER RESTARTED SOFTLY 19095425 3 1 RK TERM: FTP S->C: 500 Line too long, transfer aborted.

The FTP server in the example is defined much like the one in "A simple development environment", able to accommodate active and passive FTP mode. The audit trail above shows the use of passive FTP, as requested by the FTP client. The FTP Server dynamically creates a server socket (to which the FTP client connects for the transfer of the file), which runs on a separate thread in the online. When the transfer is done (successfully or not), the dynamically created socket thread terminates, and the audit trail records a soft restart.

In comparison, the following example shows the same attempted upload as the one above, but from a command-line client that uses active FTP only. The lines beginning with ftp> are the user entries in the client tool. The lines beginning with integers are the FTP server messages received by the client. The lines beginning with ---> are the commands the client actually sends to the FTP server, as reported by the client's debugging facility.

ftp> put colornotes ---> PORT 198,242,244,36,8,235 200 Port command OK: "198,242,244,36,8,235" ---> STOR colorNotes 150 Storing: "TEST/PUBS/COLORNOTES" 500 Line too long, transfer aborted.

The client's PORT command above signals an active FTP transfer. It identifies the data port (server socket) to which the FTP server's CLSOCK socket must connect for the upload. The first four decimal digits following PORT form the IP address of the FTP client host, and the last two digits form the TCP address of the port.

In addition to the Model 204 DISPLAY PROC LIST command (or the Sirius SirPro product), other useful FTP Server debugging and reporting commands are:

JANUS DISPLAY	For a display of the FTP Server port definitions
JANUS STATUS	For a display of the FTP Server port activity (or inactivity)
JANUS DISPLAYSOCK	For a display of the FTP-specific settings like folder mappings and user permissions

Janus FTP Server command reference

This section provides a reference for the Janus commands used to create and manipulate FTP servers.

To create a Janus FTP Server, you must specify:

1. A JANUS DEFINE command to define Model 204 as a server on the TCP/IP network, set a port number to which FTP clients connect, and indicate which remote hosts can establish connections with the port. The JANUS DEFINE also can set FTP-specific options to specify additional listening-port numbers (for the additional server sockets used to handle file transfers), allow unverified users (Anonymous FTP), and name a client socket port (if needed).
2. One of each of the following JANUS FTP commands to define FTP server rules:
   • FTP ASSIGN to identify the Model 204 procedure files you will expose and the folder names by which those files are identified by FTP clients
   • FTP ALLOW to specify users and grant access privileges to the FTP folders (may be bypassed for simple systems by specifying a default on FTP ASSIGN)
   • FTP HOME to associate client users with a default folder

The following commands are described in this section:

• JANUS DEFINE
• JANUS DISPLAYSOCK
• JANUS FTP
• JANUS FTP ALLOW
• JANUS FTP ASSIGN
• JANUS FTP DEASSIGN
• JANUS FTP DISALLOW
• JANUS FTP HOME
• JANUS FTP ON
• JANUS FTP SUFFIX

JANUS DEFINE

To define an FTP Server to the online, you use JANUS DEFINE with the type option FTPSERVER. This command must be issued before any other JANUS FTP commands. As with other Janus servers, the server will not be available for use until a JANUS START has been issued for it.

Syntax for JANUS DEFINE with FTPSERVER

JANUS DEFINE portname portnum FTPSERVER maxcon - [ ANONYMOUS maxanon | * ] - [ ANONUSER anonuserid ] - [ CLIENTSOCKET socketname ] - [ PASVPORT startportnum ] - [ other_parms ]

Syntax terms

portname	The name of the FTP port being created. This name can then be referenced by Janus FTP commands, as well as other Janus commands.
portnum	The port number to listen on for FTP connections. In FTP terminology, this is what is referred to as the control port.
maxcon	The maximum number of simultaneous FTP sessions supported by this server.
ANONYMOUS [maxanon | *]	Indicates that anonymous access is permitted. It must be followed by a number (maxanon) or an asterisk (*): maxanon is an integer in the range from 1 to maxcon that indicates how many of the maxcon sessions may be used for anonymous sessions. This allows the system manager to control the amount of resources that anonymous users can consume. Many FTP sites limit anonymous connections. An asterisk indicates that all maxcon sessions are available for anonymous FTP use. If the ANONYMOUS parameter is not specified, no anonymous access is permitted. If anonymous access is permitted, the default name of the anonymous user is ANONYMOUS. This name can be overridden with the ANONUSER parameter. The FTP Server does not attempt to verify an anonymous user password, but you must specify FTP HOME and FTP ALLOW rules for ANONYMOUS.
ANONUSER user	Lets you change the name of the anonymous user. It may be specified only if ANONYMOUS is also specified. user must be ten characters or less.
CLIENTSOCKET socketname	Names the client socket port to use to open connections back to the FTP client, if the client requests active file transfers. On active transfers, the FTP server is required by the protocol to open a client connection back to a server port opened by the FTP client. If this parameter is not specified, active file transfers are not permitted on this FTP server port. The name is not validated when the DEFINE command is issued, but when an active transfer is attempted.
PASVPORT startportnum	The first port number to use for passive sockets. For passive file transfers, an FTP server opens an additional server socket, to which the client is requested to connect for data transfers. Each such socket needs a port to listen on. For any given FTP server, a block of maxcon port numbers starting at startportnum is used for passive file transfers. If PASVPORT is not specified, its default is 5000. If it is specified, the value must be at least 1000 and no greater than 32K.
other-parms	One or more of the other options that are valid for a JANUS DEFINE that creates a Janus server socket port, with the exception of OPEN, CMD, NEWSESOPEN, and NEWSESCMD. Note: If you specify XTAB (a translate table, described in XTAB) the table you indicate is used on all file transfers initiated on this server, including active transfers done with a client socket port.

Examples

• The following JANUS DEFINE commands specify FTP Servers. The first defines a server with control port 1666 that is supportive of active and passive transfers. The second defines a server that supports only passive transfers.

  JANUS DEFINE FTP01 1666 FTPSERVER 8 - AUDTERM - XTAB FTP.X - ANONYMOUS 1 ANONUSER MOE - CLIENTSOCKET FTPDTP - BINDADDR 198.242.244.47 - TRACE 8 JANUS DEFINE FTP02 1667 FTPSERVER 2 - AUDTERM PASVPORT 2000

• The following JANUS DEFINE specifies the client socket for active transfers for the first FTP server defined above:

  JANUS DEFINE FTPDTP * CLSOCK 5 REMOTE * * - SOCKPMAX 5 - TRACE 8 JANUS CLSOCK FTPDTP ALLOW

JANUS DISPLAYSOCK

If JANUS DISPLAYSOCK (see also JANUS DISPLAYSOCK is issued for an FTP port, in addition to its usual output, it displays the FTP entities defined for the port. These include folders created with FTP ASSIGN and rules set up with FTP ALLOW, FTP HOME, FTP ON, and FTP SUFFIX.

For example, here is sample output from issuing JANUS DISPLAYSOCK output for the FTP Server defined in "A simple anonymous FTP Server":

JANUS DISPLAYSOCK FTPANON Folders: /PUB maps to file: FTPTEST prefixed, separator=/ Permissions: The Anonymous user can READ /PUB User MOE can WRITE /PUB Home folders: The Anonymous user has home: /PUB User MOE has home: /PUB Suffixes: ... None Overrides: ... None

JANUS FTP

The JANUS FTP command defines the rules for a Janus FTP Server running on a Janus Sockets FTP (FTPSERVER) port. These rules primarily control access to the files exposed by the FTP server.

JANUS FTP command syntax

JANUS FTP portname rule_type other_parameters

The first two parameters are positional and are required:

portname	The name (thirty characters or fewer) of the FTP port, or a pattern specifying a set of ports, for which the rule is being defined. Wildcards are allowed. The Janus definition of the port or ports must include the FTPSERVER parameter.
rule_type	The rule_type specifies the sort of rule being specified for the port(s). Valid rule_types are: ASSIGN Creates FTP folders and maps them to Model 204 Janus Sockets files, as described in "Folder mapping". DEASSIGN Removes FTP folders. ALLOW Grants read or write access to a folder created with FTP ASSIGN. DISALLOW Revokes read or write access to a folder. HOME Specifies a home folder (initial location at login) for a user. ON Sets up overrides, by specifying files to be opened and commands to be executed when a specific FTP operation is performed. SUFFIX Allows specification of the transfer mode (text or binary) of procedures/files by suffix (for example, .html, .xml).
other_ parameters	The additional parameters allowed for the JANUS FTP command depend on the rule_type that is specified. The various rule types and their parameters are described in the following alphabetically ordered sections.

You must specify at least three JANUS FTP commands — one each of FTP ASSIGN, FTP ALLOW, and FTP HOME — and it typically takes a set of JANUS FTP commands to fully specify the rules for an FTP server port. For instance, it may take a number of commands to specify the folders that are available for access, the users that may connect, and the privileges and home folders of the users.

In practice, the first of the JANUS FTP commands to issue is FTP ASSIGN.

JANUS FTP ALLOW

This command is used to grant user access to a folder in addition to any access granted via a DEFAULTPRIVS parameter on the FTP ASSIGN for the server port.

JANUS FTP ALLOW comand syntax

JANUS FTP portname ALLOW foldername READ | WRITE - TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL

Syntax terms

portname	Must be a previously defined Janus FTP Server port.
foldername	A folder previously created with JANUS FTP ASSIGN.
READ or WRITE	The folder access privileges being granted. One of these must be specified: READ FTP get (RETR command) and directory listings (LIST) are permitted. Also, the FTP client or user can cd (change directory, CWD) into this directory. WRITE READ privileges plus permission for FTP put, delete, and rename (STOR, DEL, RNFR, and RNTO).
TO	To whom access is being granted to foldername. One of these options must be specified, and only one of these per folder may be issued. To modify an earlier ALLOW rule, first use FTP DISALLOW. USER user A Model 204 user ID. The user is not checked for existence when this command is issued. USRGROUP usrgroup A user group created with the JANUS DEFINEUSGROUP command. The group is not checked for existence when this command is issued. ANONYMOUS Anonymous users (see "Anonymous FTP"). ALL All Model 204 users (except the ANONYMOUS user).

Examples of valid FTP ALLOW commands follow:

JANUS FTP FTP01 ALLOW /ANON READ TO ANONYMOUS JANUS FTP FTP01 ALLOW /GLWHOME WRITE TO USER GLW JANUS FTP FTP01 ALLOW /ALL READ TO ALL JANUS FTP FTP01 ALLOW /GLWHOME READ TO USGROUP FTP

For more information about folder access, see "Folder security".

JANUS FTP ASSIGN

This command creates an FTP folder for a previously defined FTP port. For more information about folder creation, see "Folder mapping".

JANUS FTP ASSIGN comand syntax

JANUS FTP portname ASSIGN foldername - [ TO FILE filename ] - [ DEFAULTPRIVS READ | WRITE ] - [ PREFIX [. | /] ]

Syntax terms

portname	Must be a previously defined Janus FTP Server port.
foldername	The name of the FTP folder being created. For more information about naming rules, see "Folder names".
TO FILE filename	The Model 204 procedure file being associated with foldername.
DEFAULTPRIVS	The privileges a user gets unless a JANUS FTP ALLOW rule gives them greater access. If DEFAULTPRIVS is not specified, no access is permitted except that granted by FTP ALLOW rules. Default privileges do not apply to ANONYMOUS access. Any ANONYMOUS access must be granted with an FTP ALLOW rule. The privileges allowed are READ and WRITE, one of which must be specified, as discussed in JANUS FTP ALLOW.
PREFIX	Invokes prefixing for this folder, as described in "Prefixing". Files uploaded to this folder by FTP clients are stored with the name of the folder prefixed to the filename. File MYFILE uploaded to folder ANNUAL becomes procedure /ANNUAL/MYFILE. PREFIX may be be followed by a "prefix character" — forward slash ( / ) or period (.) — which is used as the separator in folder names. The default is a forward slash. Note: The characters in the prefix string are added to and do increase the length of the procedure name, whose Model 204 limit is 255.

You can dynamically assign folders once a port is started, but you may not issue multiple ASSIGN commands for the same folder. To reassign a folder, you must first remove the assignment using JANUS FTP DEASSIGN). You may not deassign a folder once a port is started, however; in this case, you must first drain the folder using the JANUS DRAIN command.

If you use a single JANUS FTP ASSIGN to create a folder such as /A/B/C, the following FTP change directory command works as expected:

cd /A/B/C

However, you cannot use cd to move to the intermediate folder levels /A and /A/B, unless each of these levels is also defined with an individual JANUS FTP ASSIGN command. In addition to defining /A, /A/B, and /A/B/C as three separate folders with three ASSIGN commands, allowing navigation to all three levels also requires granting at least READ access at each level. The following statements create this three-level folder structure:

JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC DEFAULTPRIVS READ JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC DEFAULTPRIVS READ JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC DEFAULTPRIVS READ

The statements above create three folders that point to the same underlying procedure file. FTP clients will display and be able to navigate up and down this directory tree. In this case, however, clients will see the same procedures at any folder level they view. You can adjust this outcome by adding prefixing to the assignments:

JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC - DEFAULTPRIVS READ PREFIX JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC - DEFAULTPRIVS READ PREFIX JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC - DEFAULTPRIVS READ PREFIX

As a result:

• The names of all files uploaded to these FTP server folders are prefixed with the name of the folder to which they are uploaded. The INFO file uploaded to folder /A/B/C is stored as /A/B/C/INFO.
• To clients, a display of the list of the files in any folder contains only the files that are prefixed with that folder name.

  Note: Such a display may also include files that belong to a subfolder: for example, the /A/B/C/INFO file will be displayed in a list of the files in folder /A as /A/B/C/INFO, in a list of the files in folder B/ as /B/C/INFO, and in a list of the files in folder C/ as /C/INFO.

An alternative to prefixing in this case is to assign each folder to its own procedure file, as shown below. Then a display to a client of the list of the files in any folder contains all the files that are stored in that procedure file, without regard for prefixes, if any, or for how the files got there:

JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC1 DEFAULTPRIVS READ JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC2 DEFAULTPRIVS READ JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC3 DEFAULTPRIVS READ

Of course, in all the examples above, you can use FTP ALLOW commands (along with or in place of the DEFAULTPRIVS parameter of FTP ASSIGN) to diversify user access. For example:

JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC1 DEFAULTPRIVS WRITE JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC2 DEFAULTPRIVS READ JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC3 DEFAULTPRIVS READ JANUS FTP FTPJ1 ALLOW /A/B WRITE TO USGROUP DEV JANUS FTP FTPJ1 ALLOW /A/B/C WRITE TO USER SUPER

A benefit of predefining a folder tree like /A, /A/B, and /A/B/C is that, by making the folder names match the names of the directories on your workstation, you can then upload entire directories and subdirectories in one request, if your FTP client permits. The Janus FTP Server does not currently support client requests to create (or delete or rename) a folder, so the required directry/subdirectory structure must preexist on the server before a client can upload files arranged in such a structure.

JANUS FTP DEASSIGN

This command removes an existing FTP folder from a Janus FTP port.

JANUS FTP ASSIGN comand syntax

JANUS FTP portname DEASSIGN foldername

Syntax terms

portname	Must be a previously defined Janus FTP Server port.
foldername	A folder previously created with JANUS FTP ASSIGN.

Usage notes

Once an FTP Server port is started, no FTP DEASSIGN commands may be issued for it; the port must first be drained (using JANUS DRAIN).

A folder may not be removed with DEASSIGN if it is referred to by FTP ALLOW, FTP HOME, or FTP ON rules.

Example FTP DEASSIGN commands follow:

JANUS FTP FTP04 DEASSIGN /TEMPAREA JANUS FTP FTPANON DEASSIGN /JUNK

JANUS FTP DISALLOW

This command revokes folder access rights that were previously granted using JANUS FTP ALLOW.

JANUS FTP DISALLOW comand syntax

JANUS FTP portname DISALLOW foldername - TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL

Syntax terms

portname	Must be a previously defined Janus FTP Server port.
foldername	A folder previously created with JANUS FTP ASSIGN.
TO	Specifies whose access to foldername is to be taken away. Users not previously specified by FTP ALLOW are ignored. One of these options must be specified: USER user A Model 204 user ID. The user is not checked for existence when this command is issued. USRGROUP usrgroup A user group created with the JANUS DEFINEUSGROUP command. The group is not checked for existence when this command is issued. ANONYMOUS Anonymous (see "Anonymous FTP" users. ALL All Model 204 users (except the ANONYMOUS user).

An example DISALLOW command follows:

JANUS FTP FTP01 DISALLOW /PUB0 TO USER XXXX

JANUS FTP HOME

This command identifies the folder where an FTP user is placed when they log in. Home folders are described further in "Home folders".

JANUS FTP HOME comand syntax

JANUS FTP portname HOME foldername - TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL

Syntax terms

portname	Must be a previously defined Janus FTP Server port.
foldername	A folder previously created with JANUS FTP ASSIGN.
TO	The TO clause identifies for whom a home folder is to be set up. One of these options must be specified: USER user A Model 204 user ID. The user is not checked for existence when this command is issued. USRGROUP usrgroup A user group created with the JANUS DEFUSG command. The group is not checked for existence when this command is issued. ANONYMOUS Anonymous users (see "Anonymous FTP"). ALL All Model 204 users (except the ANONYMOUS user).

Note: All Janus FTP Server users must have a home folder assigned.

When a user logs in, the JANUS FTP HOME commands for the port are used as a rule set to select a home folder. The following steps are then applied to the home rule set to determine a home folder:

1. If the user is ANONYMOUS and there is an ANONYMOUS entry, use it; but if there is no ANONYMOUS entry, reject the login.
2. If the user is not ANONYMOUS, do the following:
   1. If an FTP HOME rule specifies the user on a USER clause, use that folder.
   2. If no USER clause matches, but the user is in a group specified in an FTP HOME rule USGROUP, use that folder.
   3. If no USGROUP group contains the user, but an ALL rule is present, use that folder.
   4. If no FTP HOME rule matches, the login is rejected.

Example FTP HOME commands follow:

JANUS FTP FTP01 HOME /GLW2HOME TO USER GLW2 JANUS FTP FTP01 HOME /ALL TO ALL JANUS FTP FTP01 HOME /GLWHOME TO USGROUP FTP

JANUS FTP ON

This command lets you override the default processing of an FTP operation (service command) with your own version. For additional information about writing JANUS FTP overrides, see "Overriding FTP protocol commands".

JANUS FTP ON comand syntax

JANUS FTP portname ON foldername | * - STOR | RETR | LIST | RNTO | DELE - [OPEN fg [[AND fg] ...]] CMD cmd [[AND cmd] ...] | DEFAULT

Syntax terms

portname	Must be a previously defined FTP Server port.
foldername	A folder previously created with JANUS FTP ASSIGN. If an asterisk (*) is specified instead of a folder name, the override is used for all folders on the port.
STOR | RETR | LIST | RNTO | DELE	Names the operation being overriden (one of the following must be selected). For a list of all the FTP commands supported by Janus FTP, including those not available for override, see "Supported FTP protocol commands". This option Overrides this operation STOR FTP put (upload files) RETR FTP get (download files) LIST FTP ls or dir (list files in wide or narrow format) RNTO FTP rename DELE FTP delete
fg	Lists one or more files or groups to open before the commands specified on the CMD clause (see below) are run. If you specify multiple files or groups, they must be separated by AND keywords. Each fg term has the following format, where you can specify individual open privileges (which default to X'0221'): [FILE | GROUP] fgname [[WITH] privs]
CMD cmd	Lists one or more Model 204 commands to execute to perform the override. If more than one is specified, they must be separated by AND keywords. Any command that contains blanks must be enclosed in quotes. The total length of commands plus one overhead byte per command may not exceed 255 bytes.
DEFAULT	Resets any previous FTP ON for the folder, restoring the default handling of the operation specified in that ON rule. In short, to reverse an ON, use DEFAULT. Note: For a given operation and folder, any previous ON rule must be be turned off with DEFAULT before a new FTP ON is issued.

Example FTP ON commands follow:

JANUS FTP FTP05 ON /SPLAT STOR - OPEN FTPTEST WITH X'BFFF' CMD 'I POV.STOR' JANUS FTP FTP05 ON /SPLAT LIST - OPEN FILE FTPTEST CMD 'I POV.LIST' JANUS FTP FTP05 ON * LIST CMD 'SUB1'

JANUS FTP SUFFIX

This command lets you specify any file types that a Janus FTP Server should treat as text data for storage and translation purposes (even if received under BINARY transfer mode). This permits Janus FTP to work with those FTP clients that incorrectly send all files in BINARY mode, even those that are text data.

JANUS FTP SUFFIX comand syntax

JANUS FTP portname SUFFIX suffix [TEXT | DEFAULT]

Syntax terms

portname	Must be a previously defined Janus FTP Server port.
suffix	A file-type suffix that ends a procedure name (preceded by a period in the procedure name). Forexample, you use HTML to match procedures whose names are of form WHATEVER.HTML.
TEXT	Procedures with names ending in suffix will be handled as text data (not binary), even if the FTP transfer mode is BINARY.
DEFAULT	Restores the default behaviour (no special handling); can be used to turn off a previously issued FTP SUFFIX command.

The FTP protocol is based on the assumption that the FTP client will toggle between ASCII and BINARY mode as needed based on the type of the file. It is the client's responsibility to select the proper file transfer mode. Some (poorly behaved) FTP clients, however, send all files in BINARY mode.

Janus FTP Server uses base64 encoded format to store files that are uploaded (FTP put or stor) in BINARY FTP mode (type I). The FTP SUFFIX command is used to prevent text file types from being stored in base64.

Janus file storage formats are described further in the Janus Web Server documentation.

Example FTP SUFFIX commands follow:

JANUS FTP FTP01 SUFFIX HTML TEXT JANUS FTP FTP01 SUFFIX XML TEXT JANUS FTP FTP01 SUFFIX FOO DEFAULT

Integrating Janus FTP and Janus Web Server

If you have Janus Web Server, you may have set up rules to simulate folders using JANUS WEB ON. For example, for your web server, you might have this rule:

JANUS WEB W3216 ON /CGIBIN/* - OPEN FILE FTPTEST WITH X'BFFF' - CMD 'INCLUDE /CGIBIN/*'

This invokes procedures whose names start with /CGIBIN/, such as /CGIBIN/HELLO.UL. With Janus FTP, you can set up a prefixed folder to automatically prepend the /CGIBIN/ when storing a procedure. For example:

* Map to web rule JANUS FTP FTP01 ASSIGN /CGIBIN TO FILE FTPTEST PREFIX JANUS FTP FTP01 ALLOW /CGIBIN WRITE TO USER GLW

If you then execute the following sequence of FTP commands from an FTP client, the HELLO.UL procedure is stored as /CGIBIN/HELLO.UL, which matches the web rule pattern above:

CD /CGIBIN PUT HELLO.UL

The procedure can then be accessed from a web browser as http://your-url-goes-here/cgibin/hello.ul.

Overriding FTP protocol commands

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 "service command" like STOR, typically implemented as put). As described in JANUS FTP ON, 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.

References

The best place for detailed information about FTP is Internet RFC 959, which specifies the protocol. This is available on the Internet ([1]). In addition, there are a number of open source FTP clients and servers that one may examine. They can be found using a search engine like Google.