RTR - RSTS to RSX Transfer ========================== Users' Guide ============ 1. Introduction =============== RTR is a small program which provides two facilities. The first is to allow a limited form of copying files from a RSTS disk to an RSX-11M disk, without having to bother with shutting down the RSX-11M system and transferring the files to tape first. The second facility allows the user to examine a (possibly corrupted) RSTS directory structure - in particular allowing him to bypass the MFD in accessing the UFD. 2. Command-Line Format ====================== For all purposes the RSTS/E disk must be loaded onto a drive on the RSX-11M system, but not mounted. The command then takes the standard form of:- RTR The format of files as held on a RSTS/E disk are completely different to those on an RSX-11M disk (unless they are RMS files) and, even worse, they are not as well documented. Thus it helps to know what sort of file you are copying before asking RTR to copy it. The format of a copy command is:- RTR = where the input-filespec may contain wildcards in UIC and/or filename the output-filespec may contain just a disk/UIC in which case the input filename(s) are used for the new files, or a filename as well in which case (all) the input file(s) is copied into that filename switches are discussed below RSTS/E disks are very fussy about their directory structure, and should one link break are often thereafter unusable from RSTS itself. RTR attempts both to list out RSTS directories, and to circumvent them where possible. The standard command-line for listing a directory is:- RTR where the output-filespec, if given, is where the listing is to be put the input-filespec may contain just a directory (possibly wildcarded) or a filename (possibly wildcarded) as well. switches are discussed below 3. Switches =========== By default files are transferred as variable-length records, where any linefeed or carriage-return character (or any combination thereof) is regarded as a record terminator. This is OK except for BASIC-PLUS files which use linefeed as a continuation marker, and the /BA switch simply transfers them in a format that can be passed through the BASIC-PLUS-2 Translator Utility (after going through FORMAT first). It simply regards each record of the input file as terminating at a carriage-return/linefeed pair, and passes all other carriage-returns and linefeeds through unchanged. /IM is used for copying files in Image Mode - i.e. copying the file a block at a time, and creating (as output) a fixed-length 512. byte file. This switch is particularly useful for copying RMS-11 Indexed Files - where most of the control information resides in the first few blocks - but in that case it is vital to update the RSX-11M File Header with the special RMS-11K values (RTR is not yet intelligent enough to do that). /DI produces a listing of the MFD - that is, a listing of each UFD followed by the password for the UFD. Note that as RSX-11M is an octal system the UFD numbers are output in octal rather than the original decimal. Naturally this will only work if the directory is not corrupt. /LI is used to produce a listing of the contents of a given UFD or UFDs as specified in the commandline. The listing will be output into a file, if one was specified, or on the terminal otherwise. If the UFD links are corrupt, RTR will list as far as it can and then give up. All UFD Headers in the MFD are linked together in a list. Normally the way to find a UFD is to start at the first such link and follow the list through. However a common accident that occurs to a RSTS/E disk is losing one of the MFD blocks, and as the linked list twists and turns from block to block that virtually guarantees that the link will be broken very early on. However, in such cases, most of the UFDs (and their files) are usually intact. If /NM:xxxxxx is specified the RTR will simply check each blockette in the MFD in turn looking for one which matches the UFD given in the UFD field, and the password given (xxxxxx) in the password field. The password is required to guard against corruption of the MFD producing a blockette which looks like the desired UFD header. /NM may be used either in a directory listing, or a file transfer, but obviously only when a single UFD is specified. /SP requests that the output file be spooled when finished. It is usually used with a directory listing, and is ignored if no output file was specified. 4. Error Messages ================= RTR may produce the following error messages:- 1. RTR - CMD READ ERROR The input command-line could not be read succesfully. 2. RTR - CMD SYNTAX ERROR An error was detected in the syntax of the input command. Correct it and respecify the line. 3. RTR - ERROR IN INPUT SPEC The input filespec was invalid (possibly a decimal UFD was specified). Correct the mistake and respecify the line. 4. RTR - ERROR IN OUTPUT SPEC The output filespec was invalid. Correct the mistake and respecify the line. 5. RTR - PARSE ERROR The output filespec could not be parsed successfully (possibly an invalid UIC). Correct the mistake and respecify the line. 6. RTR - OPEN ERROR ON OUTPUT An error occurred while trying to open the output file. 7. RTR - NO SUCH FILE(S) No files could be found to match the specification the user gave. 8. RTR - ERROR = nnnnn WHILE READING DISK RTR detected an error of some kind while reading the input disk. Determine from the error code given what the problem is and take any possible action. 9. RTR - Pack is not a RSTS-E Pack! RTR could not find the block signalling the start of the MFD and so has concluded that the pack is not a valid RSTS/E pack. RTR - RSTS to RSX Transfer ========================== System Guide ============ RTR is written as one program, split into several logical 'modules' as follows:- 1. RTR ======= This is the main routine. It calls GETCMD to get the next command-line. If /NM was specified it sets up default values for searching the disk, and if not it calls GETMFD to find the MFD. If a copy was requested it then calls FILCPY and returns for the next command. If an MFD list was requested it then calls LSTMFD. If a UFD list was requested it then calls LSTUFD. If anything was listed, and /SP was specified, the output file is spooled and then the routine returns to get the next command. 2. GETCMD ========== GETCMD merely requests and parses a commandline via GCML and CSI in a virtually standard format. The only major difference is that the input filespec is parsed as three separate parts (device, UIC & filename) as the disk will be accessed by direct QIOs and the UIC may contain wildcards. 3. GETMFD ========== The first block of the MFD starts in Cluster 1 of the disk (the bootstrap block starts in cluster 0) but it is not easy to tell what the cluster-size of a disk is, so this routine simply checks the first few (10) blocks until it finds one whose second word (the MFD ID) is -1 and assumes that to be the start of the MFD. 4. GETUFD ========== This routine calls NXTUFD to get the next UFD entry and checks to see if it is one the user requested. If not it branches back to get the next one (exiting with an indicator if there are no more). Else it reads in the first UFD block and returns to the caller. 5. LSTMFD ========== This routine simply repetitively calls NXTUFD to find the next UFD in the MFD, and outputs a line for each. 6. LSTUFD ========== This routine simply repetitively calls GETUFD to find the next UFD that the user wanted, and for each such repetitively calls NXTFIL to find the next file in the UFD, and if it matches the user's specifications outputs a line describing it. At the end of each UFD it outputs a line totalling up the number of files and blocks allocated in the UFD. 7. FILCPY ========== FILCPY is similar to LSTUFD in finding each file to copy. Having done so it then copies all the data from that file to the output device via OUTREC. 8. OUTREC ========== This routine simply outputs the next record to the output file, depending on which (if any) of the switches /BA and /IM have been given. 9. NXTUFD ========= If /NM was specified, this routine merely returns the next blockette marked as a UFD header. Else it calls CNVLNK to convert the link word and gets the blockette that points to. 10. NXTFIL ========== This routine simply reads the next block in the UFD via GETBLK. 11. GETBLK ========== This routine converts a link word via CNVLNK, and then converts the resultant cluster number to a block number via CNVCLS. If the block is not already in memory it is read in. 12. CNVLNK ========== This routine simply decodes a standard RSTS/E link word into its constituent block number, cluster number, blockette number, blockette offset and use flag. 13. CNVCLS ========== This routine simply converts a cluster number into a block number. 14. CNVDAT ========== This routine simply converts a date in RSTS/E format into an ASCII string. 15. CNVUIC ========== This routine simply converts a binary UIC into ASCII. RTR is a non-privileged task with a taskname of ...RTR, which uses 4 units (of which 2 and 4 should be assigned to TI:).