1 ETAPE ETAPE is a general-purpose program for handling EBCDIC tapes. It allows the user to move around at will within the tape, send output to different files, specify different blocksizes and record lengths for different files on the tape, and combine multiple tape files into a single output file. The capability of writing an EBCDIC tape from an ASCII file is also included. ETAPE removes all trailing blanks from tape records after reading them. On output, records will be blank padded and blocked to create fixed length tape blocks. A switch can be set to turn off the EBCDIC translation and allow the translation (or writing) of ASCII tapes. ETAPE assumes that the user has already allocated a tape drive and mounted the tape, giving it the logical name "TAPE:". An example might be - ALLOC MSA0: TAPE: MOUNT/FOREIGN TAPE RUN SYS$SYSTEM:ETAPE The program prompts for input with the message "ETAPE>" and expects a 2 letter command (upper or lower case). Some commands expect a parameter to follow the command abbreviation. In this case, the parameter must be separated from the command by exactly one space. Some commands take numeric parameters and others take alphameric text. A description of the commands can be obtained by asking for help on any particular command. A brief listing of the commands is given below: BB nnn - backspace nnn blocks BF nnn - backspace nnn files BL nnn - set blocksize for subsequent operations FI filespec - send translated output to specified file HE CC - request help on a particular command LR nnn - set logical record length (for deblocking records) QU - dismount tape and exit RW - rewind tape (and continue operations) SB nnn - skip nnn blocks in a forward direction SF nnn - skip nnn files in a forward direction TB nnn - translate next nnn blocks TF nnn - translate next nnn files TM - write a tape mark at the current position of the tape UT - toggles translation mode (between EBCDIC and ASCII) WH - print detailed statistics WR filename - write the contents of filename to the tape After each command that results in some tape movement, the program will print a message like "nnn:mmmm ==> file (rrrr)" which means the tape is at file nnn, block mmmm, and output is currently going to "file" (TTY means to the terminal) and rrrr records have been written to that file so far. If the program is being run from a command file (e.g. in batch mode), then all commands will be echoed to SYS$OUTPUT. 2 BB Backspaces the tape the specified number of physical blocks (default=1). This command will not back up before the beginning of the current file (that is, it will not cross a tape mark). 2 BF Backspaces the tape the specified number of files. A file is counted for each tape mark sensed (or until beginning of tape is reached). The tape is then positioned just past the last tape mark sensed (unless at BOT). Therefore, the command "BF 1" (or just "BF") will position the tape at the beginning of the current file, not at the previous file. To go back to the beginning of the previous file, you have to give it the command "BF 2". 2 BL Sets the physical blocksize of records read on the tape to the size specified. The maximum blocksize is currently set at 32000 bytes (this can be changed by modifying and recompiling the program). If a block of less than the specified size is read, then a warning message is printed. If a block larger than the specified size is read, then the block is truncated and a warning message is printed. 2 FI Allows the user to send the output to another file rather than to the terminal. The filename may be up to 40 characters in length, and can be a logical name, which will be properly translated. If the command "FI" is given without a parameter, output reverts to the terminal. This command will close any output file that was opened by a previous FI command. Multiple tape files can be concatenated to the same output file. You should enter the LR and BL commands prior to issuing this command, as the RECL parameter of the file is taken from the current value of the blocksize. Also, the carriagecontrol characteristics of the file are 'LIST', unless the file is given the extension .LIS, in which case carriagecontrol='FORTRAN' is used. 2 HE Self-referential. 2 LR Use this command to set the logical record size of the blocks on the tape. LR must be less than or equal to BL, and if not specified, defaults to the previous value given by an LR command, or the value of the last BL command, if LR is greater then the current blocksize. When ETAPE reads a physical block on the tape, it will break the block into records equal in length to the value specified as the parameter of this command. It is not required that the blocksize be an even multiple of LR; if that is not the case, then the last record will be shorter than the others. 2 QU Rewinds the tape and exits the program. All open files are closed. 2 RW Rewinds the tape. All else remains unchanged. 2 SB Use this command to skip forward a specified number of blocks on the tape. This command will not skip past the end of a file, or past the end of the tape. Default is to skip 1 block. 2 SF Use this command to skip forward a specified number of files on the tape. The default is 1 file, which will position you at the beginning of the next file on the tape. Will not go past end of tape. A file on tape is delimited by tape marks (this program knows nothing about labels; labels are treated just as regular files on the tape). 2 TB Translated the next nnn blocks and displays them at the terminal, or writes them to a file, as the user has requested previously. This command stops when it encounters the end of a file (but the output file is not closed, so you can reposition the tape and send another file to the same output file). The form of the command "TB *" translates all remaining blocks in the file currently positioned at. 2 TF Translates the next nnn files, sending output to the terminal or to a file, as the user has previously specified. The form "TF *" translates all remaining files on the tape, concatenating them and merging them to the output file/device. Stops upon reaching the end of the tape. 2 TM Writes a tapemark on the tape at that point. Read access beyond the tapemark is then prohibited. Note that the WR command already writes its own tapemark at the end of every file written to the tape. 2 UT Causes translation to be toggled between ASCII and EBCDIC. Initially, the switch is set to do translation from EBCDIC. A UT command turns off the translation and a subsequent UT command will turn it back on. The WH command will tell you what mode you are in. 2 WH Prints detailed tape statistics (tape position, output file and # blocks written, blocksize and record length, etc). 2 WR Writes the contents of the filename given in the parameter, in whatever format (ASCII or EBCDIC) is currently in use. The current values of lrecl and blocksize are used to block the records for output. This will also write a tapemark after the end of file. Short records are padded with blanks, long records are truncated (with a warning message), and the last block written may be shorter than the other blocks (but will be an integral multiple of lrecl). 1 ESUBS This set of subroutines enables the user to do everything ETAPE can do via calls from a higher level language. All are to be called as integer*4 functions returning a status code. The calling program should declare a common block as follows: INTEGER*2 IOSB(4) COMMON /E_IOSB/ IOSB This block should be examined for additional information. See the VAX/VMS V3.0 System Services I/O User's Guide, Volume I, pp. 7-16, 7-17 for a description of this control block. The routines available are as follows: E_OPEN(channel.ww.r) - open the tape for processing E_SKIPF(channel.rw.r,nfile.rl.r) - skip forward nfile files E_SKIPB(channel.rw.r,nblock.rl.r) - skip forward nblock blocks E_RW(channel.rw.r) - rewind tape (don't dismount) E_CLOSE(channel.rw.r) - rewind and dismount tape E_READ(channel.rw.r,buffer.wt.ds,len.rl.r) - read a block Examine iosb(1) to determine if EOF or EOT found. E_WRITE(channel.rw.r,buffer.mt.ds,len.rw.r) - write a block E_TM(channel.rw.r) - write a tape mark A Program to read the first file of a standard labelled IBM EBCDIC tape follows, using these routines. program IBMTAPE character buffer*1600,records(20)*80 ! assume tape blocked 80/1600 equivalence (buffer,records) integer*2 channel,iosb(4) common /E_IOSB/ iosb ! control block will be set by routines. integer*4 status,E_OPEN,E_SKIPF,E_READ,E_CLOSE include '($ssdef)' c c Prior to running this program, the following VMS commands must be given: c ALLOC MSA0: TAPE (or whatever drive you are using) c MOUNT/FOREIGN TAPE c c First step is to assign a channel for tape I/O, using E_OPEN. c status = E_OPEN(channel) if(.not.status)then write(6,1)status,iosb(1) stop endif c c Next step is to skip over the label on the tape, using E_SKIPF. c status = E_SKIPF(channel,1) ! skip 1 file. if(.not.status)then write(6,2)status,iosb(1) stop endif c c Now a loop to read the data blocks until EOF detected. This is done by c looking at iosb(1) - if equal to SS$_ENDOFFILE, SS$_ENDOFTAPE or SS$_ENDOFVOLUME c then EOF is presumed. Also, look at iosb(2) to determine how many bytes were c actually read, as the last block may be shorter than the rest. c status = E_READ(channel,buffer,1600) ! The 1600 refers to block size. nblock = 0 do while(status.and.iosb(1).ne.SS$_ENDOFFILE.and.iosb(1).ne. + SS$_ENDOFTAPE.and.iosb(1).ne.SS$_ENDOFVOLUME) nblock = nblock + 1 write(6,3)nblock,iosb(2) c . c . (Perhaps some code in here to to something with the data. c . status = E_READ(channel,buffer,1600) enddo if(nblock.eq.0)write(6,4)status,iosb(1) stop c d1 format(' Couldn''t access tape:',2(z8,8x)) d2 format(' Error skipping first file:',2(z8,8x)) d3 format(' Block',i5,' contained',i5,' bytes') d4 format(' Couldn''t read any data:',2(z8,8x)) end