Within BS2000, each FTP user opens his or her own FTP client task. By using the open command, the client establishes a link to the required FTP server on the remote host.
Figure 2: FTP clients in BS2000
Starting and terminating the client
You start the FTP client as follows:
START-FTP or FTP
The commands for terminating the FTP client are quit or bye.
Opening and closing a connection
Before any operation that (also) affects a remote host can be executed, a connection must be set up. This is done by using the open command. If an access protection mechanism exists on the remote host, FTP will first request the required entries. In BS2000, the transfer admission (i.e. the access authorization) typically consists of the values for the user ID, password and account number. These values are system-dependent, as can be seen in the following table.
If the partner is an FTAC-protected BS2000 system, the transfer admission must be specified in accordance with the FTAC setting
System | Login name | Account number | Password |
BS2000 without FTAC protection | 1 - 8 alphanumeric characters | 1 - 8 alphanumeric characters | C string, 1 - 8 characters long |
BS2000 with FTAC protection | $FTAC or relevant string defined for server installation | C string, 8 - 32 characters long | |
Unix system | 1 - 32 characters | The Unix system does not recognize any account numbers locally | Alphanumeric characters (the length is system dependent); a distinction is made between uppercase and owercase |
Windows | 1 - 36 characters | Windows does not recognize any account numbers locally | C string, 8 - 32 characters long |
MVS | 1 - 7 alphanumeric characters | Max. 40 characters including uppercase letters, digits and special characters $, @, # | 1 - 8 alphanumeric characters |
The connection to the remote host can be cleared with the close command.
In interactive mode, FTP responds with a version number and the input prompt ftp>. If the authorization entries following the open command are invalid, the connection to the remote host is kept open, provided the task switch 1 is not set. The correct entries can then be
made via the user command. Setting task switch 1 enables a SPIN-OFF mechanism (but see FTP client commands jobvar and svar). If the entries passed to the access protection mechanism are invalid, the FTP client is terminated. Prompting is enabled automatically on starting FTP in interactive mode and can be disabled with the prompt command.
In batch mode, after the open command, the authorization entries (user ID, password, account number) must be specified individually on continuation lines if they are required by the remote host. If these entries are invalid, the FTP client terminates. In batch mode, commands are read with RDATA and must be entered in lowercase letters. Prompting is disabled on starting FTP in batch mode.
Note that task switch 1 must be set for batch mode.
Command | Function | Link/Page |
open | Open connection to a remote host | |
close | Close connection to the remote host | |
! | Switch to BS2000 command mode | |
bye | Exit FTP | |
quit | = bye |
Commands to control FTP
The following commands return current information on the client and server settings, command states and on trace and debug settings:
Command | Function | Link/Page |
help | Display summary information on FTP commands | |
? | = help | |
status | Display FTP STATUS information | |
remotehelp | Display information on functions of the remote FTP server | |
debug | Enable/disable DEBUG output | |
trace | Enable/disable TRACE output | |
verbose | Enable/disable server responses | |
system | Display information on FTP server |
General information on FTP
Directories
After a connection has been successfully established, a working directory is defined on the local host as well as the remote host. If desired, you can obtain information on the current local and remote working directories with lpwd and pwd, respectively. Existing files in
the local working directory can be listed with the command ldir or lls, and files in the remote working directory can be listed with dir or ls. When files are not identified by their full path names in commands, they are considered to be relative to the currently set working directory.
Local file names must comply with the conventions of the local host, and remote file names must comply with the conventions of the remote host. Special attention must be paid to the use of uppercase and lowercase characters.
Command | Function | Link/Page |
ldir | Information on local file(s) | |
lpwd | Output local working directory | |
lls | List names of files on local host |
Information on local files and directories
Command | Function | Link/Page |
dir | Information on remote file(s) | |
mdir | Information on remote file names in multiple directories on the remote host | |
ls | List names of files on remote host | |
mls | List names of files in in multiple directories on the remote host | |
mlsd | Output information on remote files/directories in machine readable format | |
mlst | Output information on one remote file or directory in machine readable format | |
pwd | Output remote working directory |
Information on remote files and directories
BS2000 can optionally work with two different file systems: the proprietary DMS file system and the POSIX file system (based on a Unix system). In BS2000, directories are emulated by addressing groups of files using partial qualifiers. The complete or absolute path in BS2000 corresponds to the fully-qualified file name (e.g.:CATID:$USERID.FILENAME). The lpwd command can be used to check which file system is currently enabled on the local host. Setting the working directory enables you to switch between the DMS file system and the POSIX file system.
In order to access files in either the DMS or POSIX file system, you must be in the current working directory of the corresponding file system. It is not possible to access POSIX files from within the DMS file system, or vice versa. This principle must be observed for all FTP commands and functions.
Some operating systems (e.g. Unix or Windows systems) recognize a hierarchically organized system of directories.The structure of the POSIX file system corresponds to that of the Unix file system (UFS), i.e. is organized in a hierarchy.
In the DMS file system, directories are emulated by addressing groups of files using partial qualifiers.
Example
:5:$TCPTEST.AAA.FILE1 :5:$TCPTEST.AAA.FILE2 :5:$TCPTEST.AAA.BBB.FILE3 :5:$TCPTEST.AAA.BBB.FILE4 :5:$TCPTEST.AAA.CCC.FILE5 :5:$TCPTEST.DDD.FILE6 :5:$TCPTEST.FILE7
Here :5:$TCPTEST is the main directory containing all files. AAA and DDD are subdirectories of the main directory. BBB and CCC are subdirectories of AAA. The part of the file specification consisting of the directory names is designated as the path name (for example, :5:$TCPTEST.AAA.BBB is the path name for the files FILE3 and FILE4).
Switching between the DMS and POSIX file systems
Switching from the DMS to the POSIX file system, or vice versa, is achieved by entering the character string that was set for this purpose. Note that the entry is case-sensitive.
The default string is:
%POSIX / %posix to switch to the POSIX file system
%BS2000 / %bs2000 to switch to the DMS file system
The first character in this string (% character) can be changed for the local system with the client command modchar and for the remote system with the server function site modc. There is no separate client command for the server function site modc, so site modc has to be invoked with the client command quote.
The client command for changing the file system is either lcd or cd, depending on whether you want to change the local or remote working directory. For example, the command for switching to the POSIX file system on the local computer is lcd %POSIX.
A switch always takes you to the HOME directory of the target file system. In the POSIX file system, the system administrator defines the name of the HOME directory, whereas in the DMS file system, it corresponds to :CATID:$USERID.
TVFS (Trivial Virtual File System)
TVFS is a method described in RFC 3659 for addressing the files that can be accessed from the FTP server with Unix-like path names in which the subdirectory names are each separated by "/".
For POSIX files, the changes are therefore only minimal.
In the case of the TVFS implementation selected in the BS2000 FTP server, files in the DVS are accessed via a virtual directory /%BS2000, where the name %BS2000 is identical to the string described in the previous section, which can be used to switch from the POSIX to the DVS file system without TVFS (the version written in lowercase is not supported). In other words, the name of the virtual directory changes if the first character of the string changes with the site modc server function.
You can enable or disable the TVFS globally using the FTP server option (-TVFS ON/OFF) or for specific FTP sessions using the server command (site svfs on | off).
If the TVFS is enabled, this means the following for switching from POSIX files to DVS files:
you enter either the absolute path /%BS2000 (instead of simply %BS2000 without TVFS),
or you specify a relative path, which leads from the current POSIX directory to this virtual directory, which therefore contains %BS2000 as the last directory.
The /%BS2000 directory contains subdirectories in the form :<catid>:$<userid>, which in turn contain only the associated BS2000 file names but no further subdirectories. In other words, there is no emulation of subdirectories – contrary to the non-TVFS case – using partially qualified file names that end with a period.
If an FTP session is established, /%BS2000 initially contains only one entry with the default pubset of the respective login user ID. If the user switches to different combinations of catid and user ID using the cwd or xcwd server command, these are then cached. In other words, when listing the /%BS2000 directory, all combinations of catid/user ID visited since the beginning of the session are listed.
TVFS offers few advantages to human users; rather, the discontinuation of the emulation of subdirectories using partial qualifiers presents disadvantages. GUI FTP clients, on the other hand, work more reliably and in a more easily understandable way for the user if they can be supported by a standardized TVFS file system instead of having to operate on a file system using heuristics whose rules they often do not (fully) know. If GUI FTP clients are used, they should be instructed to send a site svfs on to the BS2000 FTP server at the beginning of the FTP session. How this can be achieved in each case is described in the documentation for the respective client.
File management commands
The following file management commands are available for local and remote files and directories:
Command | Function | Link/Page |
lcd | Change local working directory |
Modifying local files and directories
Command | Function | Link/Page |
mkdir | Create a remote working directory | |
rmdir | Remove a remote working directory | |
cd | Change remote working directory | |
delete | Delete remote file | |
mdelete | Delete multiple remote files | |
rename | Rename remote file | |
cdup | Change to the next higher directory (one level up) |
Modifying remote files and directories
Metacharacters in file names
File names for local and remote files are operands in many FTP commands. In some commands, the file name must designate only one file; in other cases, you may also specify file groups by entering metacharacters (e.g. * and ?).
The syntax and semantics of metacharacters are not standardized and depend on the special implementation. Since special implementations are, for the most part, supported by existing operating system calls, the permitted metacharacters are identical to those generally allowed in the operating system. In most situations, the FTP server determines whether and which metacharacters are allowed, though this can also be done by the FTP client in some cases. The following table contains an overview of the metacharacters allowed in BS2000, Unix and Windows systems.
Function | BS2000 system | Unix | Windows | |
DMS | POSIX | |||
Match any string (including the null string) | * | * | * | * |
Match exactly one character | / | No equivalent | ? | ? |
Match the listed strings | <s1,...> | No equivalent | No equivalent | No equivalent |
Match a string that lies between strings s1 and s2 in lexical order | <s1:s2> | No equivalent | [s1-s2] (*) | No equivalent |
Exclude the corresponding files | -s1 | No equivalent | No equivalent | No equivalent |
Metacharacters in file names
(*) only single characters are permitted
Backslash
File passwords
In BS2000, individual DMS files may also be protected by file passwords. The BS2000 FTP server expects function calls with file names in the form:
<filename>,C'<password>' or <filename>,X'<password>'.
This does not apply to the DMS file system.
Example
Overwrite the BS2000 file ANTON protected by the read password OTTO from within a Unix system with the file name ZWATON:
put ZWATON ANTON,C'OTTO'
File conversion on transfer (not 1:1 transfer)
When transferring files from one operating system to another using FTP, two viewpoints need to be taken into account:
Different operating systems recognize and accept different file types. For example, BS2000 recognizes, for example, SAM, ISAM and PAM files; Unix and Windows systems recognize only unstructured files.
Different operating systems use different codes to represent characters. For example, BS2000 systems encode characters in EBCDIC; Unix and Windows systems use ASCII.
If XHCS is used, it is possible to switch between any of several ASCII/EBCDIC code conversions. The client command for switching conversion modes is setcode. The corresponding server command is quote site setc (see "quote - Call server functions").
The type of transfer influences the conversion of file types and codes. The following applies locally for a BS2000 FTP client:
When the transfer type is ASCII (default value), code conversion takes place from EBCDIC to ASCII (send) or vice versa (receive). It is possible to read SAM files, ISAM files (without key) and PAM files (without PAMKEY). By default, a SAM file with a variable record length is generated, but this default can be changed with a command.
When the transfer type is BINARY, no code conversion occurs. It is possible to read SAM files, ISAM files (without key) and PAM files (without PAMKEY). A PAM file
is generated by default, but this default can also be changed with a command.When the transfer type is EBCDIC, no code conversion occurs. It is possible to read SAM files, ISAM files (without key) and PAM files (without PAMKEY). A SAM file with a variable record length is generated.
In addition, file attributes and the processing type can be modified by using the quote site file or quote site ftyp commands:
quote site file:
The file attributes for a file to be created can be preset by defining whether a PAM file or SAM file is to be created. All file attributes supported by C (BS2000) for STREAM I/O are also supported here.quote site ftyp
:
The processing type when writing a SAM file can also be preset. The processing type determines whether the files are to be processed as text files (i.e. organized in records or lines) or as binary files (stream of bytes) when they are written.
- PAMKEYs are not transferred. This means that it is not possible to interchange executable files between two BS2000 systems. This restriction can be overcome by packaging executable files in PLAM libraries.
- ISAM files lose their ISAM keys on transfer and must hence also be always packaged in PLAM libraries before being transmitted.
How you transfer BS2000 disk files while still retaining their attributes is described in the section “1:1 transfer of BS2000 disk files”.
Command | Function | Link/Page |
user | Specify user ID for remote host | |
ascii | Initiate ASCII transfer type | |
binary | Initiate BINARY transfer type | |
copymode | Enable 1:1 transfer of BS2000 disk files | |
file | Change DMS file attributes | |
ftyp | Change or query DMS file processing type | |
modchar | Modify string for switching between BS2000 and POSIX file systems | |
setcode | Change code tables | |
setfile | Enable/disable usage of special EOF markers and filling of dummy records with blanks | |
tenex | = binary | |
type | Change or query transfer type | |
mode | Change or query transfer mode | |
struct | Change or query transfer structure | |
form | Change or query transfer format | |
runique | Set unique target file name on overwriting with get | |
sunique | Set unique target file name on overwriting with put |
Commands to control data transmission
Transferring files
The actual file transfer can be initiated for one or more files, regardless of the direction of transfer. When transferring multiple files interactively, the prompt command can be used to control whether or not confirmation is required for each individual file.
An abort of the file transfer initiated by the client is implemented by the FTP server via the server command abor. In such cases, the BS2000 FTP server reports a successful abort with the messages below. Note, however, that this abort will not function if the FTP access occurs via FTAC.
226 Abort successful
426 Transfer aborted. Data connection closed.
The FTP client in BS2000 recognizes a user ́s intention to abort a file transfer by pressing the K2 key. If the K2 key is pressed repeatedly, it will no longer be possible to return to FTP.
Command | Function | Link/Page |
append | Append a local file to a remote file | |
get | Fetch a file | |
recv | = get | |
mget | Fetch multiple remote files | |
reget | Fetch a file after a transfer abort | |
put | Send a local file | |
send | = put | |
mput | Send multiple local files | |
reput | Send a local file after a transfer abort |
Transferring files
Forwarding commands
Functions that have been implemented on the FTP server of the remote host and for which there are no corresponding calls on the own FTP client can be initiated directly by using the quote command. The required parameters are passed transparently, without any validation on the FTP client The remotehelp command can be used to determine which functions have been implemented on the FTP server of the remote host.
One possible server function that must be initiated by using quote is site exec. In the BS2000 implementation, site exec permits commands to be forwarded to the operating system of the remote computer. Note, however, that site exec cannot be used in combination with the FTAC functionality, unless different behavior has been configured using the server option -disableSiteExecCommand (see the “interNet Services Administrator Guide”).
Command | Function | Link/Page |
bell | Enable/disable bell | |
hash | Enable/disable transfer progress indicator | |
quote | Transfer parameters to the remote FTP server | |
glob | Enable/disable expansion of metacharacters | |
prompt | Enable/disable prompting | |
sendport | Enable/disable port command | |
settime | Set timeout value for server responses | |
exit | Define parameters for local exit routines | |
rexit | Define parameters for remote exit routines | |
jobvar | Enable/disable usage of a job variable | |
svar | Enable/disable usage of an S variable (SDF-P) | |
passive | Enable/disable PASSIVE mode |
Other FTP functions
Restart capability of the FTP client
With the restart capability of the FTP client, aborted FTP transfers can be resumed at the position in the target file at which the FTP transfer was interrupted. The restart capability of the FTP client is implemented with the FTP client command reget (see "reget - Fetch a file with restart support") and reput (see "reput - Send a local file with restart support").
Batch capability of the FTP client
The FTP client can be used in (batch) procedures. The batch capability of the FTP client allows the procedure to establish the command for which the error occurred. The faulty client command or the associated faulty server command and the associated error messages are stored in a previously specified job variable and/or SDF-P variable so that the calling procedure can respond suitably. The batch capability is supported by the FTP client commands jobvar (see "jobvar - Store error information in a job variable") and svar (see "svar - Store error information in an SDF-P variable").
Example of an FTP session between a PC and BS2000
