Short documentation for FLX Revision 1.3, 18 September 1994 FLX is a program (written in C) that lets Unix or DOS systems read and write RSTS disks, or container files that contain disk data. It supports any size disk that RSTS supports (including "large" disks, those with device cluster size greater than 16), and any size file. Credits This program is dedicated to the memory of Simon S. Szeto, RSTS friend extraordinary. Thanks to Fred Knight for providing the original inspiration (RSTSFLX for VMS); to DJ Delorie for his DOS version of GNU C; to John Wilson for Ersatz-11, PDP-11 simulator for the PC; and to Bob Supnik for his help in making FLX generally available. Introduction The FLX command line has the following general form: command [switches... | files...] The command may be given as part of invoking the program (i.e., "flx" followed by the command line). In that case, the command line is executed and FLX exits. If no command is given, FLX prompts for a command, executes it, and prompts for another. Switches and file name arguments may be mixed in any order; unlike many Unix commands, there is no requirement to put the switches before the file names. However, if a switch has an argument, the argument must follow immediately after the switch. Commands and switches may be abbreviated to the shortest unambiguous abbreviation. They are case sensitive, and apart from a few switches are in lower case. There is no notion of "conflicting" switch (as DCL has) where one switch overrides a preceding switch of opposite meaning. If you include conflicting switches in a command, typically one will be ignored, but it doesn't depend on the order. So don't do that... Most commands take one or more filespecs as arguments. These may be wildcarded. Beware of shell wildcard expansion; that general isn't what you want. So if you use wildcards, you'll usually need to quote the filenames, or to let FLX prompt you for the command line. (When FLX prompts, shell wildcard expansion is not done.) However, with the "put" command the input filespecs are filespecs in the host system, not on the RSTS disk, and in that case you generally do want to let the shell do wildcard expansion for you. RSTS filespecs accepted by FLX generally conform to normal RSTS rules, with a few limitations and additions. The allowed field are PPN, name, extension, protection (in that order). Name and extension are not case sensitive. PPN can be a normal RSTS PPN spec [proj,prog] or -- to avoid some shell quoting -- a Unix style spec /proj/prog/ . If no other fields follow, the trailing / may be omitted. The special PPN characters (such as $) are not supported. For most commands, the default PPN is [1,2]. Unless otherwise stated below, the file name may not be null (but the extension may be). As in recent RSTS releases, trailing ? characters in name or extension may be replaced by a *. So "a?????" and "a*" are equivalent. The RSTS disk or container file is specified in one of three ways: 1. If the -disk switch is present, the argument of that switch is the disk filespec. 2. Otherwise, if environment variable RSTSDISK is defined, its value is the disk filespec. 3. Otherwise, container file "rsts.dsk" in the current directory is used. FLX uses read-only access to the disk or container file if the command only does reading (e.g., get, list), and requires read/write access only for commands that modify the disk. Protection code is as usual. The commands are: allocation Display disk block allocation information. The first and last pack cluster and the size of each free area is displayed, as well as summary data giving amount free, amount used, and size of largest free contiguous area. If -brief is specified, only the summary data is shown. delete Delete RSTS files. dump Display an octal and ASCII dump (and, if -wide is specified, RAD50) of a file. If a PPN is given but the name is not, the UFD is dumped. If neither is given, you get an NFS dump of the disk. (Note that currently you cannot get a file structured dump of MFD or GFD.) exit Quit FLX (useful when it's in prompting mode). get Copy files from RSTS disk to your host system. The last argument is an output filespec. It may be a directory name, in which case you get a lot of separate output files, each consisting of the directory name plus the input filename. If -tree was specified, each file ends up in a host system directory underneath the one you specified, whose name is derived from the RSTS directory it came from. If the output is not a directory name, you get a single output file, containing the concatenation of all the input data. An input filespec consisting only of a PPN will cause the UFD to be copied. hook Write the boot block. First argument is the device type (default DL), case insensitive. Second argument is the file to hook (default [0,1]init.sys). Third argument is the file from which to read the bootstrap code (default whatever argument 2 is). All arguments are optional. identify Display summary information about the disk, such as pack label, flags, and size. initialize Initialize the disk as an RSTS file structured disk. The pack ID is the first argument; the second argument, if present, supplies the RDS level desired. Default is RDS 1.2. list Show a directory listing. Default PPN is [*,*]. Default file name and extension are *. mkdir Create a directory (non-user account). The PPN specified must not be wild. protect Change the protection code on RSTS files, or set/clear the P (no-delete) flag. put Copy files from the host system to the RSTS disk. The last argument is a RSTS filespec. Default name and extension are *. The PPN must not be wild unless - tree is specified. With -tree, the output RSTS directory is derived from the last directory name in the input filespec, which must be numeric. The input filespecs are host system filespecs. rename Rename RSTS files. The new name is given as the output filespec. A PPN is not permitted. The default name and extension are *. Multiple input specs are allowed, and all are renamed according to the output spec. rmdir Delete a directory (account, user or non-user). The directory must be empty. Wild PPN is allowed. rts Set the RTS name attribute on RSTS files. The RTS name is the last argument. type Type one or more files. Some commands have synonyms: list, directory, ls type, cat exit, quit delete, rm rts, runtime rename, mv, move initialize, dskint Switches: Many switches apply only to some commands, but they are recognized at all times. If you use a switch on a command where it does not apply, it has no effect. -ascii Force line oriented transfer mode in "get" and "put". -binary Force block mode transfer in "get" and "put". -brief Brief directory listing (name.ext only, 5 across). -clustersize Output file clustersize in "put", pack clustersize in "initialize". May be negative for "put", in which case pack clustersize is used if supplied value is smaller. -contiguous Make the file contiguous in "put". -create Create the container file as part of "initialize". The argument is the container size; it may be a numeric argument or the (case insensitive) strings "RL01" or "RL02". -disk Argument is the filename of the RSTS disk or container file. Valid with all commands. -Debug Print various debug information while executing the command. Valid with all commands -end Specifies last block number (0-based) in "dump". If the argument has a leading 0, it is octal; otherwise it is decimal. If this switch is omitted, the dump ends on the last block. -filesize Meaningfule only if -contiguous is specified; forces the output file in "put" to be that size. (If omitted and -contiguous is specified, the file is pre-extended to the same size as the input file.) -full Full directory listing (includes file attributes) for "list". -image Same as -binary. -long Same as -full. -oattributes Display RMS attributes in octal in "list". -protect Set P flag in "protect" command. -replace Let "rename" supersede an existing file, if the new name already exists. -size Same as -filesize -start Specifies first block number (0-base) in "dump". If the argument has a leading 0, it is octal; otherwise it is decimal. If this switch is omitted, the dump starts at block 0. -tree Copy directory trees (see below). -unprotect Clear P flag in "protect". -wide Do wide dump (include RAD50) in "dump". -Write Override normal write protection: allows writing on disk initialized as read-only, and allows deleting and modifying files that are write- protected (e.g., protection code <62>). Does not override the protection provided by the P (no- delete) flag. -1column Brief directory listing (name.ext only), one file name per line. Some examples: get -v [0,1]*.rts [1,2]*.sav . Copy all .RTS files from [0,1] and all .SAV files from [1,2], and put them in the current host system directory. The resulting file names match those of the input files. put /usr/bin/ls [1,2]*.sav Copy "ls" to [1,2]LS.SAV. Since the extension is .SAV, the RTS name is set to RT11, and the runnable bit set in the protection code. (This is obviously a rather silly example...) rename [0,1]*.tmp [1,2]*.sav *.foo Rename all .TMP files in [0,1] and all .SAV files in [1,2], changing their extension to .FOO. (Note that, while no PPN may be specified on the "new" filename, the inputs may be in several different directories, or indeed have wildcard directory specs.) More details on certain commands: Get: The "get" command can either concatenate files, or produce multiple output files. It concatenates if a single filespec is given as the output spec, and produces separate outputs if a directory spec is used. The file transfer mode depends on whether concatenation is being done, on switches, and on the RMS attributes of the input files. If concatenation is done, line mode transfer is done unless - binary is specified. (Note that the case of a single input file spec, without wildcards, to a single output filespec, is not considered concatenation. However, if any wildcards are present, that is concatenation even if only one file ends up matching the wildcard spec.) If individual transfer is done, the transfer can be forced to line mode with -ascii, or to binary (block) mode with -binary. Otherwise, the properties of the input file control how that particular file is transferred: = No RMS attributes (RSTS native format): - Text file -- line mode - Others -- block mode = Copying a directory - block mode = RMS sequential format: - Fixed 512 byte records -- block mode - Otherwise line mode = Other RMS organizations -- block mode (Note that line mode transfer other than for Stream format files is currently unimplemented. More precisely, line mode transfer assumes that the file is a stream format file, even if RMS attributes are present that say otherwise. However, it will work correctly for stream_lf format files, i.e., files with only line feed as line terminator.) A "text file" is one whose extension indicates it contains text, as opposed to binary data. The extensions that are considered "text" are: txt lst map sid log lis rno doc mem bas b2s mac for ftn fth cbl dbl com cmd bat tec ctl odl ps c h In line mode, the input file is interpreted as a RSTS stream file, with cr/lf line delimiters. Lone line feeds without preceding carriage return are also treated as delimiters. In any case, the lines are written to the output file using standard Unix line delimiters ("newline"). Any trailing nulls in the file are ignored. In block mode, the input file is read block by block, and is copied exactly as is to the output file in binary mode. In this case, the output file size will be a multiple of 512 bytes. Tree transfer mode: If -tree is specified, the input directory name is made part of the output spec (this is meaningful only when doing individual transfer and the output spec is a directory spec). The PPN is converted to a 6-digit string and that directory name and the filename are appended to the output spec. If necessary, the directory is created. So the command get -tree [1,2]*.sav . would create (for example) a file ./001002/pip.sav . Put: The "put" command does transfer mode selection similar to "get", but since there are no attributes on the input files, the rules are simpler: The transfer can be forced to line mode with -ascii, or to binary (block) mode with -binary. Otherwise, the properties of the input file control how that particular file is transferred: = Text file -- line mode = Others -- block mode In line mode, the input file is read line by line. At each line ending, a standard RSTS line delimiter (cr/lf) is inserted. Normally, the input file has "newline" characters (line feed) at end of line, per Unix convention. If the input file has cr/lf pairs at end of line -- for example, if it was a RSTS text file copied in block mode from somewhere -- then the cr/lf is kept as the line end; no additional cr is inserted in that case. In block mode, the file is read in binary mode, and is written exactly as is to the output RSTS file. If the input file size is not a multiple of 512 bytes, the last block is filled with zero bytes (nulls) before being written. The output file protection can be specified explicitly. If it isn't, it defaults to 60 for non-executable files, 124 for executable files. Executable files are recognized by their extension (checked against the runnable extensions of the runtime systems I know of). An executable file will always have its RTS name set. The executable bit in the protection is turned on only if the protection was defaulted. Large files (those of size greater than 65535) have the RTS name cleared, and the executable bit in the protection code is forced off unconditionally. Tree transfer mode: If -tree is specified, the output PPN is normally wild. The input file spec is then used to construct not just the output file name but the output PPN as well. The last directory name in the path is expected to be a numeric string. If the output spec is of the form [x,*] then the numeric (decimal) value of the directory name is taken as the programmer number. If the output spec is [*,x] or [*,*] then the directory name must be at least 4 digits; the low order 3 digits are the programmer number and the high order digits the project number. (In the case of [*,x] the programmer number is then ignored.) Examples: put -tree 10/foo [2,*] produces [2,10]foo. put -tree 10/foo [*,*] is an error (too few digits) put -tree 4010/foo [*,*] produces [4,10]foo. put -tree 4010/foo [*.2] produces [4,2]foo. put -tree bar/foo [2,*] is an error (directory not numeric) If necessary, the output directory is created as part of the copy. What's on the kit The FLX kit contains: = Source (.C) and header (.H) files for FLX. = A Makefile, to build FLX under Unix or DOS (with GNU GCC, or probably with any other reasonable C compiler). This file may need minor changes; read the notes in the file for details. = FLX.EXE, a DOS executable file. This file was built with DJ Delorie's GCC package, but it does not depend on having that installed. = FLX.DOC, the source file for this document (Microsoft Word format), and FLX.PS and FLX.TXT, readable copies of same. Futures Several features are on the list for consideration in the future. Feedback would be appreciated on these or other candidates (but no promise is implied that any of this will be done, or that there will be a future release). Commands: rebuild "Rebuild" (a.k.a., "clean"), comparable to the ONLCLN utility or Refresh Rebuild feature in RSTS INIT. Switches: -query Ask about transferring each file in commands that do file operations. -r Do RMS variable length record format transfer in "put". -rv Same as -r. -rs Do RMS stream record format transfer in "put". -rc Do RMS stream-CR record format transfer in "put". -rl Do RMS stream-LF record format transfer in "put".