Operations Equipment and Measurement Division - Systems Group __________ _________ ___ ___________ ________ _ _______ _____ Software Documentation ________ _____________ Subject DOS Tape Exchange Program DTX _______ Author R J Carpenter ______ Software Version Y02.20 ________ _______ Document File DTX ________ ____ Document Version Y02.00 ________ _______ Issue Date 29-Mar-84 _____ ____ Copyright (C) Shell Research Ltd. 1984 USER DOCUMENTATION FOR THE DOS TAPE EXCHANGE PROGRAM 'DTX' Author : R. J. Carpenter DISCLAIMER __________ The copyright in the computer program described in this document and in the associated user instructions is the property of Shell Research Ltd.. The information in this document is subject to change without notice and should not be construed as a commitment by Shell Research Ltd. Shell Re- search Ltd. assumes no responsibility for any errors which may appear in this document. The software described in this document is supplied under a licence and may only used or copied in accordance with the conditions of such a licence. The licence conditions state that this software shall be supplied free of charge and shall not be sold or otherwise disposed of by means of trade or otherwise for any form of profit or advantage. Possesion or use of the software shall be deemed as acceptance of the conditions of the licence. No guarantee is given or may be implied as to the adequacy of the program or its suitability for any particular purpose and no liability is accepted for any loss or damage arising out of its use. Shell Research Limited Thornton Research Centre Operations Equipment and Measurement Division P.O. Box 1 CHESTER CH1 3SH U.K. March 1984. CHAPTER 1 Introduction DOS formatted tapes are the nearest Digital have got to a standardised tape format. All other PDP-11 (and VAX) operating systems provide a facility for reading/writing DOS tapes as does, it is believed, the DEC 10/20 operating systems. If RT supported this format, the picture would be complete and a standard tape interchange format would exist for ALL Digital operating sys- tems. This program was written to overcome this deficiency. This manual follows normal Digital documentation standards with following exceptions; computer output (in examples) is underlined and the symbol __________ means the 'RETURN' key. CHAPTER 2 Overview The utility 'DTX' is a program to handle DOS formatted tapes under RT11. This current version, Y02.20, supports any peripheral for which a driver is available under RT11 for RT-11 format input or output, and any Digital sup- plied, RT supported, mag-tape drive for DOS formatted input or output; or more specifically, any tape drive and handler which is correctly handles the required .SPFUN monitor requests. For further details of modifying DTX to use non-Digital mag-tape devices and/or handlers, please see appendix A. 2.1 File Formats. ____ ________ DTX will only copy from DOS-tape to RT-11 or RT-11 to DOS-tape format on an image i.e. word for word, basis. No account is taken of any internal struc- ture of the file(s) being copied. 2.2 Calling and Terminating DTX. _______ ___ ___________ ____ To call DTX from the system device, respond to the keyboard monitor prompt by typing :- R DTX Type ^C to halt DTX when it is waiting for console terminal input and re- turn control to the monitor. To restart DTX, type R DTX or REENTER in res- ponse to the monitor's dot. 2.3 Command Syntax. _______ _______ DTX uses the standard command string interpreter (CSI) and commands are en- tered in the normal fashion, i.e. output-filspec/switch:option=input-filespec/switch:option Overview Page 2-2 2.3.1 User Identification Codes For DOS format devices, a user identification code (UIC) in form [nnn,mmm] may be specified. Note that square brackets ([]) are part of the UIC; you must type them when you specify a UIC. If a UIC is not specified, a default is supplied. On DOS input the default is [*,*]; on DOS output, DTX will warn you, and offer to supply the default of [1,1]. 2.3.2 Use of Wild Cards Wild cards in file names or extensions are valid for most operations (and may be mandatory), including embedded wildcards such as FIL*.EXT or A%%FIL.EXT. Wild cards are also valid for a complete element in an input UIC. However, you cannot use embedded wild cards; that is, [*,100] is valid but [1*,100] is not. CHAPTER 3 Operations DTX is capable of performing four basic operations. They are :- 1. Transferring files from RT-11 to DOS mag-tape format. 2. Transferring files from DOS mag-tape to RT-11 format. 3. Producing a directory of a DOS format mag-tape. 4. Initialising a DOS format mag-tape. Please note that DOS to DOS or RT to RT file transfers are invalid. 3.1 Transferring files from RT-11 to DOS mag-tape format. ____________ _____ ____ _____ __ ___ ________ _______ To transfer a file from an RT-11 device to a DOS format mag-tape, enter a command with the following syntax :- ddev:[[nnn,mmm]]/S=input-filespec[/switch] where :- ddev represents a valid DOS format mag-tape device name. [nnn,mmm] is an optional UIC (if omitted, the program will print a warning and request permission to use the de- fault UIC [1,1]). /S is the switch that designates a DOS mag-tape device. input-filespec is any valid RT-11 device, file name and extension (if the device is not file structured, you may omit the file name and extension). /switch is one of the three modifier switches /Q, /P or /N. For more details on these modifier switches please see chapter 4, section 3 Operations Page 3-2 NOTE Output file specifications for the DOS mag-tape (other than * or *.*) are ignored since the output file name is always taken from the input (RT-11) file. The 'Are you sure' query for using the de- fault output UIC of [1,1] is not suppressed by using the /Y switch. The following example transfers all the files from DL2: to a DOS format tape on MS0: *MS0:/S=DL2:*.* _ ?DTX-W-Defaulting output UIC to [1,1]; Are you sure ? Y _________________ ______ ___ __ ______ ___ ___ ____ _ Files copied: _____ _______ DL2:DTXLIB.COM to MS0:[001,001]DTXLIB .COM ______________ __ ___________________ ____ DL2:DTXLNK.COM to MS0:[001,001]DTXLNK .COM ______________ __ ___________________ ____ DL2:DTXASM.COM to MS0:[001,001]DTXASM .COM ______________ __ ___________________ ____ DL2:DTXBLD.COM to MS0:[001,001]DTXBLD .COM ______________ __ ___________________ ____ * _ The next example transfers user selected .MAC files from DM0: to a DOS for- matted tape on MM1: into UIC [200,200] *MM1:[200,200]/S/Q=DM1:*.MAC _ Files copied: _____ _______ DM1:DTX .MAC to MM1:[200,200]DTX .MAC ? Y _______ ____ __ ________________ ____ _ DM1:DTXUTL.MAC to MM1:[200,200]DTXUTL .MAC ? N ______________ __ ___________________ ____ _ DM1:DTXR2D.MAC to MM1:[200,200]DTXR2D .MAC ? ______________ __ ___________________ ____ _ DM1:DTXSUB.MAC to MM1:[200,200]DTXSUB .MAC ? Y ______________ __ ___________________ ____ _ * _ 3.2 Transferring files from DOS mag-tape to RT-11 format. ____________ _____ ____ ___ ________ __ _____ _______ To transfer a file from a DOS format mag-tape to an RT-11 device, enter a command with the following syntax :- output-filespec=ddev:[[nnn,mmm]]input-filespec/S[/switch] where :- output-filespec represents a valid RT-11 device name, the file name * and optionally the wild card extension .* (if the device is not file structured, you may omit the file name and extension). ddev represents a valid DOS format mag-tape device name. [nnn,mmm] is an optional UIC (if omitted the default UIC of [*,*] will be used). input-filespec is any valid DOS file name and extension. Operations Page 3-3 /S is the switch that designates a DOS mag-tape device. /switch is one of the three modifer switches /Q, /N or /M. For more details on these modifier switches please see chapter 4, section 3 NOTE Some operating systems (e.g. RSX11-M) 'bend' the DOS tape header block structure and cre- ate nine character file names. These are al- ways truncated on transfer to the first six characters since that is all RT-11 will per- mit. However be warned that this can lead to succesive DOS tape format files being copied to the 'same' RT-11 file. Output file names other than * or *.* are ig- nored since the output RT-11 file name is al- ways taken from the input DOS file name. The following example tranfers all the .COM files in UIC [300,300] on a DOS format tape on MT0: to DY0: *DY0:*=MT0:[300,300]*.COM/S _ Files copied: _____ _______ MT0:[300,300]DTXLIB .COM to DY0:DTXLIB.COM ___________________ ____ __ ______________ MT0:[300,300]DTXASM .COM to DY0:DTXASM.COM ___________________ ____ __ ______________ MT0:[300,300]DTXLNK .COM to DY0:DTXLNK.COM ___________________ ____ __ ______________ MT0:[300,300]DTXBLD .COM to DY0:DTXBLD.COM ___________________ ____ __ ______________ * _ 3.3 Producing a directory of a DOS format mag-tape. _________ _ _________ __ _ ___ ______ _________ To produce a directory of a DOS format mag-tape, enter a command with the following syntax :- [output-filespec=]ddev:[[nnn,mmm]]input-filespec/S/list-switch[/switch] where :- output-filespec represents an optional valid RT-11 device name and file name and an optional extension. If omitted com- pletely the directory listing is produced on the con- sole. If a device name is specified and the device is file structured, the file name must be specified; however, the extension is optional and the default extension of .DIR will used if omitted. If the device is not file structured, you may omit the file name and extension. ddev represents a valid DOS format mag-tape device name. Operations Page 3-4 [nnn,mmm] is an optional UIC (if omitted the default UIC of [*,*] will be used). input-filespec is any valid DOS file name and extension. /S is the switch that designates a DOS mag-tape device. /list-switch is the directory operation switch. A full directory may be obtained by using /L or a summary directory containing only UIC's and file names by using /F /switch is the optional modifer switch /M. For more details on this modifier switch please see chapter 4, section 3 The following example produces a full directory of an entire DOS tape on the terminal. *MM0:/S/L _ 31-Oct-83 _________ [333,327]DTX .MAC <233> 31-Oct-83 27. (000033) ____________ ____ _____ _________ ___ ________ [333,327]DTXPFX .MAC <233> 31-Oct-83 19. (000023) _______________ ____ _____ _________ ___ ________ [333,327]DTXPZU .MAC <233> 31-Oct-83 6. (000006) _______________ ____ _____ _________ __ ________ [333,327]DTXR2D .MAC <233> 31-Oct-83 12. (000014) _______________ ____ _____ _________ ___ ________ [333,327]DTXD2R .MAC <233> 31-Oct-83 6. (000006) _______________ ____ _____ _________ __ ________ [333,327]DTXDLS .MAC <233> 31-Oct-83 7. (000007) _______________ ____ _____ _________ __ ________ [333,327]DTXDIN .MAC <233> 31-Oct-83 4. (000004) _______________ ____ _____ _________ __ ________ [333,327]DTXSUB .MAC <233> 31-Oct-83 50. (000062) _______________ ____ _____ _________ ___ ________ [333,327]DTXFNM .MAC <233> 31-Oct-83 4. (000004) _______________ ____ _____ _________ __ ________ Total of 135. (000207) blocks in 9. files. _____ __ ____ ________ ______ __ __ ______ * _ The next example produces a fast directory of group number 200 on LP:. *LP:=MM0:[200,*]/S/F _ (directory appears on the line printer) * _ 3.4 Initialising A DOS Format Mag-tape. ____________ _ ___ ______ _________ To initialise a DOS format mag-tape, enter a command with the following syntax :- ddev:/S/Z[/Y] where :- ddev represents a valid DOS format mag-tape device name. /S is the switch that designates a DOS mag-tape device. /Z is the initialisation operation switch. /Y inhibits the DTX confirmation message. Operations Page 3-5 The following example initialises a DOS format tape on MM0:. *MM0:/S/Z _ ?DTX-W-MM0:/Initialise; Are you sure ? Y _______________________ ___ ___ ____ _ * _ CHAPTER 4 Switches. Switches are required to inform the program of the exact operation re- quired. They fall into three categories; device, operation and modifier. Each switch is described below on an individual basis. 4.1 Device Switches. ______ _________ Device switches indicate the file structure used by the device involved in the operation. 4.1.1 The DOS switch /S This switch indicates that device (input or output) is a DOS formatted mag-tape. It is position dependent and must be specified. File specifica- tions without a /S switch are assumed to be RT11 format. 4.2 Operation Switches. _________ _________ Operation switches perform other functions in addition to the (default) data transfer. They are all position independent. 4.2.1 The Fast Listing switch /F This switch causes only a fast listing of file name and UIC to be produced. Otherwise all the notes for the /L switch apply. If /L and /F are applied to the same command, the /F takes precedence and only a fast listing is produced. 4.2.2 The Listing switch /L This switch specifies that a full directory of the DOS tape is to be pro- duced. It is only valid with a /S switch on the input side. (Use DIR if you want a listing of your RT device !). The output file specification is op- tional. If it is omitted, the listing is produced on the terminal. If the PHYSICAL output device is non file structured (e.g. LP:) only the output Switches. Page 4-2 device name is required. If the PHYSICAL output device is file structured, a file name MUST be specified. The extension must either be explicit or missing. If missing, the program will create a file called xxxxxx.DIR. 4.2.3 The Initialisation switch /Z This switch specifies that the DOS tape is to be initialised (or zeroed.) It is only valid together with a /S switch on the output side. DTX will warn you if a foreground (or system) job is present, and also asks you to confirm the initialisation by asking 'Are you sure'. To confirm the opera- tion, respond with anything begining in a 'Y'. All other responses are as- sumed to mean 'no'. 4.3 Modifier Switches. ________ _________ Modifier switches cause operations to be performed in a certain manner and are all position independent. 4.3.1 The Tape Positioning switch /M The /M switch provides control over the initial tape operation and is only valid for data transfers from DOS mag-tape to RT-11 format or directory op- erations. The exact effect is determined by the option field applied to the switch. The option field may either 0 or -1. If the /M switch, or its op- tion, is omitted, or the option field is 0 (i.e. /M:0), the tape is rewound before any operation begins. If the option is -1 (i.e. /M:-1), the tape is not rewound and the operation starts from the current tape position. Note that all other values for the option field are invalid. If you use the 'no-rewind' option (/M:-1) it may be important to you to know how the program attempts to synchronise itself with the tape. The al- gorithm it uses is as follows. The program initially reads in the next data block from the tape and checks to see if it is a valid DOS header block. If this succeeds the program is synchronised with the tape and operations con- tinue as normal. If the first data block is not a valid DOS header block, the program skips to the next EOF mark and tries to interpret the succeed- ing data block as a DOS header block. If this succeeds then the program is synchronised. If not, the program assumes the tape is not DOS format, prints a suitable error message and returns for a further command. 4.3.2 The 'No-Log' switch /N This switch suppresses the terminal log of files copied. It is overridden by the /Q switch. Switches. Page 4-3 4.3.3 The Protection Code switch /P This switch allows a protection code to be applied to the file(s); valid protection codes are octal numbers in the range 0-377. It may only used when transferring files from RT-11 to DOS tape format, and will be applied to all files transferred as a result of that command. If not supplied, the default protection code is 233. 4.3.4 The Query switch /Q This switch is used during copy operations to specify that confirmation is required for every file to be transferred. To confirm the copying of that file, respond with anything begining in a 'Y'. All other responses are as- sumed to mean 'no'. 4.3.5 The Confirmation switch /Y This switch is only meaningful with the /Z switch and suppresses the 'Are you sure' question. CHAPTER 5 Error Messages. DTX provides plenty of error messages, most of which are self explanatory. There is, however, one set of messages which might be a little obtuse. These are messages of the form :- ?DTX-F-Hard error on tape read. Code = may theorectically have values of 0 to 6. In practice, error codes 5 & 6 are trapped internally and may not actually be errors. The other codes are defined as follows:- 0 No additional information. 1 Tape drive not available. 2 The controller lost position. 3 Nonexistent memory accessed 4 Tape is write locked. For more information on these codes and their causes, please see the RT11 Software Support Manual. APPENDIX A Release Notes A.1 Operating Systems. _________ ________ This version of DTX (Y02.20) has been tested and found to work satisfacto- rily with the following versions of RT-11 :- RT-11 V04.00 SJ, FB or XM (but see note below) RT-11 V05.00 SJ, FB or XM RT-11 V05.01 SJ,FB,XM RTEM-11 V01.00, RSX-11M/M+ Variant RTEM-11 V02.00, RSX-11M/M+ Variant NOTE This version will work with V04.0 XM provided that all the required handlers are loaded be- ___ fore calling the program. A.2 Restrictions. _____________ At the time of writing there is only one known bug in the software. A.2.1 Program Hangs with ^C Inoperative. _______ _____ ____ __ ____________ This is, in fact, a bug in the magtape handler. So far, it has only been seen when using a TE16 drive (MM:) (because that's all the writer has !) but may exist in all the magtape-handlers. The effect seems to be caused by some combination of bad blocks and EOF marks on the tape causing the handler to loop at BR5 (hence ^C doesn't work). An SPR has been sent to DI- GITAL. Until they come up with a patch, the only solution is force an error by putting the tape off-line and reading the rest of the tape with the help of the /M:-1 switch. Some form of /IGNORE switch wouldn't help since the handler never returns to the user program ! Release Notes Page A-2 A.3 Distribution Kit. ____________ ____ The distribution kit consists of four (4) files. The save image file (DTX.SAV), the map file (DTX.MAP), the RUNOFF file for this document (DTX.RNO) and this document file itself (DTX.DOC). The distribution is in save image only for the following reasons:- 1. This program makes use of non-RT11 proprietary software from DIGI- TAL. 2. This program makes extensive use of Shell written macros and su- broutines. To release these would be to give away some 50% of Shell's software effort in this area over the last few years, let alone the amount of disk space the software would occupy. 3. By making the software essentially unalterable, all bugs will (hopefully) be reported to the author. This means that everybody will benefit by the bug fixes as and when new versions are re- leased. A.4 Bug Reporting. ___ __________ Should you discover any bugs please submit a psuedo-SPR with as much detail as you possibly can to the following address :- Ray CARPENTER EMT/33 Shell Research Ltd. Thornton Research Centre P.O. Box 1 CHESTER CH1 3SH U.K. NOTE Neither Shell nor the author undertakes to respond to any correspondence regarding this software or to act upon any such correspon- dence. A.5 Adding New Tapes Systems. ______ ___ _____ ________ In order to protect itself from unnecessary errors, DTX has table of device-identifier bytes. The code from the user specified DOS device is compared with the values in this table to ensure that it is a valid DOS mag-tape device. If you have a non-standard tape handler then DTX may not recognise the device-identifier and will reject the device as invalid. To solve this problem you will need to patch the device table. Release Notes Page A-3 The device table is a 8 byte long table of device-identifiers. If less than 8 slots are used, the first empty entry contains a null. As a piece of as- sembler code, the table resembles the following :- .PSECT $DTXRO RO,D,GBL,OVR ; ; Device codes ; DC.MM = 20 DC.MT = 11 DC.MS = 35 ; ; Table of valid DOS device codes (0 = end of table) ; $DDTBL: .BYTE DC.MM ;device code for MM: .BYTE DC.MT ;device code for MT: .BYTE DC.MS ;device code for MS: .BYTE 0 .BYTE 0 .BYTE 0 .BYTE 0 .BYTE 0 ; $EOTBL: .WORD 0 ;end of table guard word Thus to add a new device, you will need to know the device-identifier byte (byte 56 of the handler). To add the device to the table, locate the global symbol '$DDTBL' (in the PSECT '$DTXRO') in the task map. Using SIPP, locate the first null byte ____ after $DDTBL and before $EOTBL and modify that byte to contain the new dev- ice identification code. Ensure the next byte is zero, (it usually will be) and exit from SIPP. DTX will now recognise your device as a valid DOS mag-tape device. NOTE Please ensure you only perform this modifica- tion on a copy of the task to prevent loss of ____ the task through mistake or accident. If you are creating a mag-tape handler and want DTX to be able to use it, then you must write it such that all of the .SPFUN requests for device de- pendent operation of a mag-tape drive are implemented in exactly the same way as for the Digital supplied handlers. You will also, of course have to patch the device table as described above. INDEX /F . . . . . . . . . . . . . . . . . 4-1 /L . . . . . . . . . . . . . . . . . 4-1 /M . . . . . . . . . . . . . . . . . 4-2 /N . . . . . . . . . . . . . . . . . 4-2 /P . . . . . . . . . . . . . . . . . 4-2 /Q . . . . . . . . . . . . . . . . . 4-3 /S . . . . . . . . . . . . . . . . . 4-1 /Y . . . . . . . . . . . . . . . . . 4-3 /Z . . . . . . . . . . . . . . . . . 4-2 Adding New Devices . . . . . . . . . A-2 Bug Reporting . . . . . . . . . . . . A-2 Command Syntax . . . . . . . . . . . 2-1 Directories of DOS mag-tapes. . . . . 3-3 Distribution Kit . . . . . . . . . . A-2 Error Messages. . . . . . . . . . . . 4-3 Initialising DOS tapes . . . . . . . 3-4 Operating Systems . . . . . . . . . . A-1 Operations . . . . . . . . . . . . . 3-1 Release Notes . . . . . . . . . . . . A-1 Restrictions . . . . . . . . . . . . A-1 Switches. . . . . . . . . . . . . . . 3-5 Transferring DOS to RT . . . . . . . 3-2 Transferring RT to DOS . . . . . . . 3-1 UIC's . . . . . . . . . . . . . . . . 2-1 Wild cards . . . . . . . . . . . . . 2-2