Admin Alert: Darn Good FTP Commands You’ve Probably Never Heard Of
November 16, 2005 Joe Hertvik
While most i5/OS and OS/400 administrators are familiar with using FTP for file transfers between i5, iSeries, AS/400, Windows, Linux, and Unix machines, they may not be familiar with a number of valuable OS/400 FTP subcommands that can make their FTP transfers run more efficiently. To that end, let’s look at some lesser-known OS/400 FTP subcommands that can make a big difference when you are transferring data.
Please note that this article was written and tested in an i5/OS V5RX environment, and that you may see some differences running these subcommands in earlier OS/400 versions.
QUOTE TIME xxxx yyyy: This subcommand changes the file transfer timeout (xxxx) and the inactivity timeout values (yyyy) on the remote system FTP server. The QUOTE TIME subcommand is valuable because it changes the length of time the remote FTP server will wait before timing out your client FTP session due to long-running file transfers or through inactivity. By default, the file transfer timeout value is set to 420 seconds (seven minutes) and the inactivity timeout value is set to 300 seconds (five minutes). Each value is set in seconds so if I wanted to set both values to ten minutes (600 seconds), I would issue the following QUOTE TIME subcommand:
QUOTE TIME 600 600
The inactivity timeout value (yyyy) is an optional parameter that is not required in the subcommand. So if I just wanted to change the file transfer timeout interval, I could do that by only entering a new xxxx value, like this:
QUOTE TIME 600
The default value for a FTP session’s Inactivity timeout value can be changed in the inactivity timeout parameter (INACTTIMO) on the Change FTP Attributes command (CHGFTPA). You can display and change this value on the green-screen by entering the CHGFTPA command and pressing the F4 key to prompt for command values. But while OS/400 allows you to change the default inactivity timeout value, there is no way to change the default File transfer timeout value.
The important thing to remember about these values is that they refer to the amount of time the remote FTP server will wait before ending an attached client session. This means that, for inactivity timeouts, the clock is ticking from the last second when your FTP client issued a command to the FTP server to the next time it sends another server command. So even though you may be working inside your FTP client session, if you do not communicate with the server during the inactivity timeout period, your session can still be closed due to inactivity.
SUnique 0 | 1: Control Overwriting of Files. This subcommand determines whether existing file members on the remote FTP server are overwritten when using an FTP PUT or MPUT subcommand to transfer a new version of those files to the remote FTP server. You can turn SUNIQUE off (0) by using this FTP subcommand.
SUNIQUE 0
When SUNIQUE is turned off, PUT subcommand transfers will overwrite existing files and members on the remote FTP server, if those files already exist. For example, a simple PUT subcommand for transferring a file and member named JOE in the ADMIN library might look like this.
PUT ADMIN/JOE.JOE
The name following the period (.) in the PUT subcommand designates the member to be transferred; if you do not designate a file member name, FTP will automatically transfer the first member of the file. When this subcommand is executed with SUNIQUE 0 in place, any existing data in the JOE member of the ADMIN/JOE file on the remote FTP server would be overwritten with the new transferred data from the FTP client.
But the scenario changes if I toggle SUNIQUE on (1) by using the following FTP subcommand.
SUNIQUE 1
Now, if I transfer the JOE member of the ADMIN/JOE file with the same PUT statement, FTP will no longer overwrite the target member on the remote server. Instead, the PUT subcommand will create a new file member named JOE1 in ADMIN/JOE on the remote server. If I ran the PUT a second time, it would create a third file member in ADMIN/JOE called JOE2. When SUNIQUE 1 is in place, PUT and MPUT transfers create new unique file member names on the remote server file by adding a number to the end of your existing file name.
There is one caveat when using SUNIQUE 1 for DB2/UDB files. In order for FTP to automatically create new file members for a target file, the maximum number of members for the target file (its MAXMBRS parameter) must be large enough so that OS/400 allows FTP to create a new file member. So if the file is set up with a default MAXMBRS value of one (maximum number of file members equals one), your PUT subcommand will error out because OS/400 will not let FTP create a second member for that file. SUNIQUE 1 can only be used on files where the maximum number of members is large enough to create a new member as needed. You can check the MAXMBRS parameter by running the green-screen Display File Description command (DSPFD) to display all file parameters.
If I find that the MAXMBRS value for a target file is set too low for FTP to add new members, I could change MAXMBRS to a higher value by running one of the following two Change Physical File commands (CHGPF).
To set MAXMBRS to a specific higher number, I would run the command like this:
CHGPF FILE(ADMIN/JOE) MAXMBRS(xxxxx)
|
Where xxxxx is equal to a number between one and 32,767.
If I wanted to change MAXMBRS so that it could contain any number of members, I would run the CHGPF as follows.
CHGPF FILE(ADMIN/JOE) MAXMBRS(*NOMAX)
This version tells OS/400 that there is no maximum amount of members that can be added to this file and that any number of new file members can be created.
It’s also worth noting that the rules are simpler when using SUNIQUE 1 in conjunction with transferring stream files residing in the AS/400 IFS. For stream files that cannot be overwritten, a new file is created for the transferred data. This file has the same characteristics as the original transferred file, but its name is modified slightly to protect the server’s data. Like the member names that are added to DB2/UDB files, new AS/400 IFS stream file names are created by adding a unique number to the end of the original file name. This number is added to the last character of the file so that, for example, a SUNIQUE 1 file transfer for a stream file named bitmap.bmp would create a new file named bitmap.bmp1.
PWD: Display the current directory or library of the remote FTP server. If you forget or need to know what the current working directory (CWD) is on the FTP server that your client is attached to, run the PWD subcommand without any parameters. If you are running an FTP session with another i5, iSeries, or AS/400 server, the format of the displayed CWD will vary depending on whether your FTP server is set to a file naming format of ‘0’ or ‘1’ through the NAMEFMT subcommand. When the remote server’s naming format is set to ‘0’ (DB2/UDB native file system only), your CWD will be displayed as a native DB2/UDB library name (ex; QGPL). But when the naming format value is set to ‘1’ (AS/400 Integrated File system notation), a DB2/UDB CWD of QGPL will be displayed as ‘/QSYS.LIB/QGPL.LIB”, the same as it would be for any other FTP subcommands when NAMEFMT equals ‘1’.
Besides reminding you what your current CWD is, you can also use PWD (and the LPWD command I’ll discuss next) to document your FTP directories during an automated FTP transfer. By putting these commands in an FTP script, command output will automatically be inserted into your FTP output file, which can be reviewed later in case of problems.
LWPD: Print Working Library, Folder, or Directory. In contrast to PWD, LPWD displays the working library, directory, or folder used in the local FTP client. All the same rules that apply to the PWD command also apply to the LPWD command.
STAT: Retrieve Status Information. This command is used to display the current status of the remote FTP server the client is attached to. STAT displays a number of values including the IP address, the current naming format used in the session, how the system trims trailing blanks and handles database files with null values, what the user name is, and what the file transfer timeout and inactivity timeout values are. Like PWD and LPWD, this is a valuable command both for retrieving remote system value and for documenting those values inside an FTP output file.
RELATED STORIES
Copying IFS Directories Between Two iSeries, Part 1
Copying IFS Directories Between Two iSeries, Part 2
Making OS/400 Automatically FTP to Windows
