Caché I/O Device Guide
Magnetic Tape I/O
[Back] 
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter tells you how to program I/O for magnetic tape in Caché. It describes I/O commands and special variables as they relate to magnetic tape.

Choosing a Tape Handler
On UNIX® and Windows systems, use the Caché magnetic tape handler. On OpenVMS system, you can choose from two different handlers for magnetic tape devices:
You select the handler when you issue the OpenVMS MOUNT command.
Note:
When mounting a magnetic tape device on OpenVMS, use the FOREIGN switch: mount /foreign <device name>
To set up magnetic tape device numbers and select a tape handler, see Managing Magnetic Tape Devices.
Using the Caché Magnetic Tape Handler
This chapter describes I/O commands you use with the Caché magnetic tape handler.
With this tape handler, you refer to your magnetic tape device by device numbers 47 through 62 as configured in the Management Portal.
Note:
On OpenVMS, when you use these numbers, you can easily change the physical device they refer to by issuing one ASSIGN statement at the OpenVMS level, rather than changing each instance of the old reference in your application.
OPEN Command
Selects a device and specifies its parameters.
Syntax
OPEN devicenum:(codesparam:reclenparam:blkszparam):timeout:"mnespace"
where:
Argument Definition
devicenum The logical device number, from 47 to 62 (inclusive).
codesparam
Optional — 1st positional parameter: format codes. A string of one or more letter codes for magnetic tape format options. These letter codes are listed in the table Magnetic Tape Format Codes. The string of codes must be in quotation marks. Only certain combinations of codes are permitted.
This optional parameter has a default of “AUV” (ASCII characters, no labels, variable-length records in ANSI D format) on Windows systems. On UNIX® and OpenVMS systems, the default is “ALV” (ASCII characters, standard labels, variable-length records in ANSI D format).
reclenparam Optional — 2nd positional parameter: record length. If codesparam includes F (fixed-length records), reclenparam is the logical record length, from 1 to 510 bytes. If records are not fixed-length, specify 0 for reclenparam or omit it.
blkszparam Optional — 3rd positional parameter: Block size, in bytes. An even number from 16 bytes to 32KB, and a multiple of reclenparam. The default is 2048 bytes. The maximum value is highly platform, drive, and character-coding dependent. The recommended maximum is 32KB characters; larger block sizes up to 65,535 bytes are possible in some circumstances.
timeout Optional — The number of seconds Caché waits for an OPEN to finish; a positive integer. If the timeout is zero, OPEN returns control to the process immediately. A timed OPEN sets $TEST. If the OPEN succeeds within the timeout period, $TEST is set to True (1). If the OPEN times out, $TEST is set to False (0).
mnespace Optional — Name of the file that contains mnemonics and their meanings for use with the WRITE /mnemonic command. See the section Magnetic Tape Mnemonic Space for WRITE /mnemonic for more details.
Only the devicenum argument is required. You must specify a magnetic tape device by its device number. Caché reserves device numbers 47 through 62 (inclusive) for magnetic tape devices. These device numbers are defined in the Management Portal. Select [Home] > [Configuration] > [Device Settings] > [Devices] to edit device number assignments.
Arguments are separated by colons (:). If you omit an argument, you must specify the colon. You must not end either the command or its parameter list with a colon.
The optional parameter list is enclosed in parentheses, and can specify its parameters as either positional parameters (in the order shown), or as keyword parameters with the syntax /KEYWORD=value. Keyword parameters may be specified in any order; because Caché executes them in left-to-right order, interactions between parameters may dictate a preferred order in some cases. You can mix positional parameters and keyword parameters in the same parameter list. The enclosing parentheses are required if you specify more than one parameter.
For more information, see OPEN in the Caché ObjectScript Language Reference.
The three optional parameters (codesparam, reclenparam, and blkszparam) control data format. If you omit them, the following default parameters apply:
On Windows systems: indicating ASCII characters, no labels, variable-length records, and 2048-byte blocks:
("AUV":0:2048)
On UNIX® and OpenVMS: indicating ASCII characters, ANSI-standard labels, variable-length records, and 2048-byte blocks:
("ALV":0:2048)
These default OPEN parameter values are defined in the Management Portal. Select [Home] > [Configuration] > [Device Settings] > [Devices], and then click “Edit” for a specific device (magnetic tape devices are numbered 47 through 62). When you click on a listed device, it displays the Open Parameters default value.
Caché ignores the data format parameters specified with OPEN if the device has already been opened, either by running the %IS utility or by issuing another OPEN command. You therefore must issue a CLOSE command for the device before you can reopen it and assign new parameters.
Specify Tape Format Codes in codesparam
The following table describes the magnetic tape format codes you can specify in codesparam of the OPEN command.
Magnetic Tape Format Codes
Code Format Definition
A (default) ASCII Uses ASCII character set.
D DOS-11 Uses DOS-11 labeling, the ASCII character set, and stream data format.
E EBCDIC Translates ASCII to EBCDIC on output, and EBCDIC to ASCII on input.
F Fixed length Assumes fixed-length records for input. Caché uses stream data format for output; you are responsible for padding records to the correct length.
K\name\
Knum
I/O Translation Mode When you use the K protocol for a device, I/O translation will occur for that device if translation has been enabled system-wide. You identify the previously defined table on which the translation is based by specifying the table's name. The “+” and “-” options for turning protocols on and off are not available with the K protocol. (The older form, “Knum,” where num represents the number of the slot the table is loaded in, is being phased out but is still supported. The system manager can display slot numbers in the NLS utility in the selection window for each table type.)
L (default UNIX® OpenVMS) Standard labels Uses ANSI standard labels if you select the ASCII character set; uses IBM standard labels if you select the EBCDIC character set.
R Read mode Acts as a logical protection level during write operations. If you try to write to a tape that has Read mode specified or has a write-protect ring, an error occurs. Ignored for Read commands, except you must include this parameter if the tape has no write-protect ring. Write mode is the default. R is required for write-protected tapes on some UNIX® systems.
S Stream format On output, packs characters, including <RETURN> and, sequentially into the buffer. On input, treats <LINE FEED>,, and <FORM FEED> as string delimiters, and ignores <RETURN> and null characters. Jobbed processes that inherit TCP devices are automatically set to S format. You can reset the format with the USE command.
U (default Windows) Unlabeled Unlabeled. If you will be reading from an unlabeled tape, you must open it with U.
V Variable length If you select ASCII characters, uses ANSI D format; if you select EBCDIC, specifies EBCDIC V format. Each argument of a READ or WRITE corresponds to one logical record.
Y\name\
Ynum
$X/$Y Action Mode When you use the Y protocol for a device, the system uses the named $X/$Y Action Table. You identify the previously defined $X/$Y Action Table on which translation is based by specifying the table's name. You can get the name from the system manager. $X/$Y action is always enabled. If Y is not specified and a system default $X/$Y is not defined, a built in $X/$Y action table is used. The + and – options for turning protocols on and off are not available with the Y protocol. (The older form, Ynum where num represents the number of the slot the table is loaded in, is being phased out but is still supported. The system manager can display slot numbers in the %NLS utility in the selection window for each table type.)
The following table shows the magnetic tape density codes that you can specify in codesparam of the OPEN command.
Magnetic Tape Density Codes
Code Format Definition
1 800 BPI Selects 800 BPI (Bits per inch) recording density for drives that support multiple densities.
2 1600 BPI Selects 1600 BPI for drives that support multiple densities.
3 6250 BPI Selects 6250 BPI for drives that support multiple densities.
Allowed Combinations of Format Codes
The following table shows which combinations of codesparam format codes you can specify. If you include conflicting codes in the parameter string, the last code prevails.
Allowed Combinations of Format Codes
  A D E F L R S U V
A ASCII - Y N Y Y Y Y Y Y
D DOS Y - N N N Y Y N N
E EBCDIC N N - Y Y Y Y Y Y
F Fixed Length Y N Y - Y Y N Y N
L Labeled Y N Y Y - Y Y N Y
R Read Mode Y Y Y Y Y - Y Y Y
S Stream Format Y Y Y N Y Y - Y N
U Unlabeled Y N Y Y N Y Y - Y
V Variable Length Y N Y N Y Y N Y -
OPEN Keyword Parameters
The following table describes the keyword parameters for controlling magnetic tape devices via the OPEN command.
OPEN Command Keywords for Magnetic Tape Devices
Keyword Default Corresponding Positional Parameter Description
/ASCII
/ASC
Use ASCII codesparam =“A” Specifies that the ASCII character set be used.
/BLOCKSIZE=n
/BLO=n
No default blkszparam Specifies the size of a tape block.
/DENSITY=n
/DEN=n
No default
codesparam =“1”
codesparam =“2”
codesparam =“3”
Tape density. The value of n specifies the tape density in BPI. Recognized values are 0, 800, 1600, and 6250. A value of 0 selects the default density for the device. Other values of n are ignored.
/DOS No default codesparam =“D” Specifies DOS-11 labeling, stream format, and the ASCII character set.
/EBCDIC
/EBC
No default codesparam =“E” Specifies ASCII to EBCDIC translation on output and EBCDIC to ASCII translation on input.
/FIXED
/FIX
Not fixed codesparam =“F” Specifies fixed-length records for input. (The programmer is responsible for padding records to the correct length for output.)
/GZIP[=n] 1   Specifies GZIP-compatible stream data compression. /GZIP or /GZIP=n (for nonzero values of n) enables compression on WRITE and decompression on READ. /GZIP=0 disables compression and decompression. Before issuing /GZIP=0 to disable compression and decompression, check the $ZEOS special variable to make sure that a stream data read is not in progress. /GZIP compression has no effect on I/O translation, such as translation established using /IOTABLE. This is because compression is applied after all other translation (except encryption) and decompression is applied before all other translation (except encryption).
/IOTABLE[=name]
/IOT[=name]
If name is not specified, the default I/O translation table for the device is used. codesparam =“K\name\” Establishes an I/O translation table for the device.
/LABELED[=n]
/LAB[=n]
L format is the default on OpenVMS and UNIX® platforms; U format is the default on Windows platforms.
codesparam =“L”
codesparam =“U”
/LABELED and /LABELED=n for nonzero values of n corresponds to the L format code, which specifies standard labels (ANSI standard labels if the ASCII character set is used, or IBM standard labels if the EBCDIC character set is used). /LABELED=n for a zero value of n corresponds to the U format code, which specifies an unlabeled tape.
/PARAMS=str
/PAR=str
No default codesparam Corresponds to the codesparam format code string positional parameter. (This keyword provides a way to specify a format code string in a position- independent way.)
/READ No default codesparam =“R” Acts as logical Write protection for the tape. (If a WRITE operation is attempted, an error will occur.)
/RECORDSIZE=n
/REC=n
No default reclenparam Specifies the logical record length when fixed-length records are specified on input.
/STREAM
/STR
0 codesparam =“S” Specifies stream record format.
/TRANSLATE[=n]
/TRA[=n]
1 codesparam =“K” /TRANSLATE or /TRANSLATE= n for nonzero values of n enable I/O translation for the device. /TRANSLATE= n for a zero value of n disables I/O translation for the device.
/VARIABLE
/VAR
No default codesparam =“V” Specifies variable length record format (ANSI D format if the ASCII character set is used, or EBCDIC V format if the EBCDIC character set is used). (This is the default.)
/XYTABLE[=name]
/XYT[=name]
If name is not specified, the default $X/$Y action table for the device is used. codesparam =“Y\name\ ” Establishes a $X/$Y action table for the device.
Examples
The following command opens logical device 47 with the default parameters.
   OPEN 47
The following command opens logical device 48 with ANSI standard D format, which consists of labeled files with variable-length ASCII records.
   OPEN 48:"AVL"
The following command opens logical device 47 with EBCDIC unlabeled fixed-block records, 80 bytes long, in 8000byte blocks.
   OPEN 47:("EUF":80:8000)
Check Parameters if an OPEN Command Fails
If an OPEN command fails, use these hints to resolve the problem:
Because OPEN commands do sometimes fail, you should always specify a timeout, so that a failed OPEN does not cause your process to hang.
USE Command
Sets a previously opened magnetic tape drive as the current device.
Syntax
USE devicenum
For more information, see USE in the Caché ObjectScript Language Reference.
Example
The following command makes device 47 your current device.
   USE 47
READ Command
Reads from the current device, according to the command format you specify. After the READ, the variable holds the contents of the record at the current position on the tape.
You control the tape head location with WRITE * control code options, as explained in the next section.
Syntax
READ variable
READ *variable
READ variable#length
For more information, see READ in the Caché ObjectScript Language Reference.
Tape Without Write-Protect Ring
To read a tape without a write-protect ring, you must OPEN the tape with the “R” parameter.
Note:
On some UNIX® systems, R is required for write-protected tapes.
WRITE Command
Writes data to the current location on the current magnetic tape device.
Syntax
WRITE *-n
WRITE /mnemonic
For more information, see WRITE in the Caché ObjectScript Language Reference.
Magnetic Tape WRITE Options
Argument Definition
*-n Specifies a control code; see WRITE *-n Controls Magnetic Tape Functions for details.
/mnemonic Causes Caché to interpret mnemonic as defined in the active mnemonic space. If there is no active mnemonic space, an error results.
You can specify an active mnemonic space in two ways:
See the section Controlling Devices with Mnemonic Spaces for more information on mnemonic spaces.
WRITE *-n Controls Magnetic Tape Functions
You can change the location of the tape head and write special marks and labels by using the WRITE * command followed by a negative integer control code. For example:
   WRITE *-5
The following table describes the control codes:
WRITE *-n Control Codes
Code Function Effect
-1 Backspace Backspaces tape one block. (Not supported for cartridge tape.)
-2 Forward Space Advances tape one block (skipping labels) so that WRITE *-2 at the beginning of the tape (BOT) skips volume and header labels as well as the first data block. If you use the U format code in your OPEN but the tape really is labeled, WRITE *-2 at the beginning of the tape (BOT) skips the volume label. (Not supported for cartridge tape.)
-3 Write Tape Mark Writes a tape mark. If the buffer contains unwritten data, that data is written out first.
-4 Write Block Writes out the current buffer. If the format specifies labels and the tape is at BOT, header labels of the appropriate format are written before the data block.
-5 Rewind Rewinds the tape. Any unwritten data (in addition to trailer labels and tape marks required by the format) is written before rewinding occurs.
-6 Read Block Reads the next block. If the tape is at BOT, skips header labels before reading.
-7 Read Label Reads the next block whether or not it is a label. (Not supported for cartridge tape.)
-8 Write Header Label If the format specifies labels, writes header labels. If the tape is at BOT, writes a volume label before the header labels. Note that on UNIX® systems this is not supported for cartridge tape.
-9 Write EOF Label Writes any unwritten data. If the format specifies labels, writes the appropriate trailer label. Writes two tape marks and backspaces over the second. (Not supported for cartridge tape.)
-13 Rewind and Unload OpenVMS only — performs all the functions of WRITE *-5, then unloads the tape. This control lets you create an output set that spans more than one tape volume.
The following example opens tape device #47 and sets it as the current device. Then it rewinds the tape.
   OPEN 47
   USE 47
   WRITE *-5
Note:
You can use the mnemonic parameter to accomplish many of the functions you carry out with WRITE *-n.
CLOSE Command
Closes the magnetic tape device, making it available to other users. It does not rewind the tape.
Syntax
CLOSE devicenum
For more information, see CLOSE in the Caché ObjectScript Language Reference.
How Caché Closes and Rewinds Tapes
Caché performs these steps when it is writing a tape and the program issues:
  1. If data in the magnetic tape buffer has not yet been written to tape, Caché writes the buffer to tape. In the EBCDIC formats, a short block is written, if necessary, in accordance with the IBM tape standard.
    Note:
    OpenVMS: You cannot write a block smaller than 14 bytes to tape.
  2. If the tape is an ANSI- or EBCDIC-labeled tape and the last operation to the tape was a write, Caché writes the appropriate EOF label.
  3. Caché writes two tape marks, then backspaces over the second tape mark, leaving the write head positioned between the tape marks.
  4. Caché executes the CLOSE or rewind command.
Reading and Writing OpenVMS Labeled Tapes
Tapes you use with Caché may have an OpenVMS label. Caché allows you to bypass these labels automatically, or to write a label where there is none, as long as you do not specify the U (unlabeled) format in your OPEN command.
The effect of READ and WRITE commands depends on whether the tape has been labeled at the OpenVMS level, and what the first command is after the OPEN. The following table describes the results.
Results of the Caché OPEN Command with OpenVMS Labels
First Command After OPEN OpenVMS Labeled Unlabeled
READ Skips label and reads first block of data. <MAGTAPE> error
WRITE If you include D or L in OPEN codesparam, then the Caché label overwrites the OpenVMS label. If you include D or L in OPEN codesparam, the Caché label is written first, and then the data.
When a WRITE command writes or rewrites a label, Caché does the following:
Thus, to write data to a labeled tape in normal usage, simply issue OPEN and USE commands. Write the data, then issue a WRITE *-5 to rewind the tape and close it.
Reading and Writing ANSI and EBCDIC Labeled Tapes
Caché allows you to read and write ANSI-standard and EBCDIC labels at the beginning and end of tape files.
Note:
On Windows and UNIX®, you can write ANSI-standard and EBCDIC labels on 9-track tape only. You cannot label cartridge, 8mm, or 4mm tapes.
To write a single file to a labeled tape during normal usage, simply open and use the tape. Issue a WRITE *-5 to rewind the tape, write the data, and close it.
With ANSI-standard or EBCDIC labels, Caché writes the following:
  1. A volume label at the beginning of the tape.
  2. A header label that consists of the two blocks, HDR1 and HDR2.
  3. A tape mark.
  4. The data blocks.
  5. A trailer label that consists of the two blocks, EOF1 and EOF2. (The trailer label and EOF blocks are written as part of the CLOSE.
  6. Two tape marks. These labels are automatically rewritten by Caché.
    Thus, a tape with a single file would look like:
VOL1, HDR1, HDR2, TM, Data, TM, EOF1, EOF2, TM, TM
Labels have the formats shown below. The format for UNIX® and Windows ANSI-Standard and EBCDIC labels is:
Volume label (Vol 1)                        |

    |VOL1CACHE1                            D%B|
    0   10   20      30
    |444400100120                          1|
    40  50   60      70

Header one (HDR1)
   |HDR1CACHE.SCR CACHE10001fseq0001020    1|
   0   10   20       30
   |0 00000 00000 00000 Open |
   40  50   60       70 

Header two (HDR2) 
   |HDR2fblk         M                      |
   0   10   20       30
   | 00 
   40  50   60       70

Trailer one (EOF1) 
   |EOF1CACHE.SRC CACHE100001fseq00010      |
   0   10   20        30

   |0 00000 00000 blkcnt Open                |
   40  50   60        70 

Trailer two (EOF2) 

   |EOF2fblk.rec      M                     |
   0   10   30        30 
   | 00                                     |
   40  50   60        70
The format for OpenVMS ANSI-Standard and EBCDIC labels:
Block number 1: Volume label (Vol1)

    VOL1CACHE1      000000
        D%B4444001001      000020                    1................ 000040 
------------------------------------------------------------------------- 
Block number 2: Header one (HDR1) 

    HDR1CACHE.SRC   CACHE1fseq0 000000 
001000100 00000 00000 000000MUMP 000020
    S                                                ................ 000040 
------------------------------------------------------------------------- 
Block number 3: Header two (HDR2)

    HDR2blk.rec        000000
          M                                     00       000020 
                                                     ................ 000040
         *** End of file *** 
------------------------------------------------------------------------- 
Block number end-1: Trailer one (EOF1) 

    EOF1CACHE.SRC CACHE10001fseq0 000000 
    001000100 00000 00000 blkcntMUMP 000020 
S                          ................ 000040 
------------------------------------------------------------------------- 
Block number end: Trailer two (EOF2) 

    EOF2blk.rec        000000 
          M                                   00         000020
                                                     ................ 000040 
--------------------------------------------------------------------------  
    *** End of file ***

        *** End of file ***
For the OpenVMS listing, in HDR1 and EOF1, fseq is the file sequence number. In HDR2 and EOF2, f is the data format, blk is the block size, and rec is the record length. In EOF1, blkcnt is the block count for the file.
DOS Labels
If you write a tape with DOS labels, a single header label appears before each file, and each file ends with a tape mark. The header label consists of the file name “CACHE 001” in radix 50 notation, followed by three bytes with values 1, 1, 23. The rest of the 80-byte label is padded with ASCII nulls.
Record Structure
In ASCII variable-length data format, each record is preceded by a four- character number whose value is the record length plus four. The last record in the block is followed by the caret character (^). Each argument of a WRITE or READ corresponds to one record.
In EBCDIC variable-length data, the format is the same as ASCII variable-length except that each block begins with a four-character number indicating the block length.
File Structure
To write multiple files on a tape, you direct the placement of labels for the second and subsequent files. The volume label appears only at the beginning of the tape. The two header label blocks and a tape mark precede each file, and the two trailer label blocks and a single tape mark follow all but the last file. Use a double tape mark at the end of the last file.
You can use the magnetic tape control codes WRITE *-8 (write header label), and WRITE *-9 (Write EOF label) to control the placement of additional labels.
Creating Files on a Labeled Tape
The following table shows the steps you follow in creating three files on a labeled tape using the Caché tape handler.
Creating a Three-File Labeled Tape
Step Control Code Definition
1 OPEN 47:"ALV" USE 47 WRITE *-5 Opens and rewinds the tape.
2 USE 47 WRITE ... Writes the first file. Caché automatically precedes the first file with the volume label and header label.
3 USE 47 WRITE *-9 Writes the final data block, a tape mark, an EOF label, and two tape marks. Backspaces over the second tape mark.
4 USE 47 WRITE *-8 WRITE ... Writes a header label for the second file and writes the second data file.
5 USE 47 WRITE *-9 Writes its final data block, its EOF label, and backspaces over the second tape mark.
6 USE 47 WRITE *-8 WRITE ... Writes the third file's header label and data.
7 USE 47 WRITE *-5 CLOSE 47 Writes the last data block and a trailer label with two tape marks, rewinds the tape, and closes the magnetic tape.
Special Variables Show I/O Conditions
The special variables $ZA and $ZB contain information about magnetic tape operations. If your program requires the values of $ZA and $ZB, it should examine them after each magnetic tape operation, recognizing that an error trap will occur after some operations.
$ZA Holds Magnetic Tape Status
Magnetic tape errors and special conditions appear in the special variable $ZA. Caché updates $ZA after each Caché ObjectScript command that refers to the magnetic tape device.
The following table shows the meanings of the bits in $ZA. The letter Y in the Trap column means that this condition causes a <MAGTAPE> error. If you have set $ZTRAP, this condition invokes the error code that you referred to with $ZTRAP. See the $ZA and $ZTRAP special variables in the Caché ObjectScript Language Reference.
$ZA Bits
Bit Value Trap Meaning
0 1 Y Logical Error - mixed Reads and Writes—To switch between reading and writing, either close and then open the device, or issue a Forward Space, Backspace, or Rewind command.
2 4 N Write Protected—Attempting to open a write-protected 9-track tape without the read-only parameter sets bit 2 and opens the tape as read only. No error occurs.
3 8 Y Error Summary—The error summary is the logical OR of all conditions that cause an error (all conditions marked “Y” in the table).
5 32 N Beginning of Tape [BOT]
6 64 N On Line
7 128 Y Controller or drive error
8 256 Y (OpenVMS) Bad Tape Error
9 512 Y (OpenVMS) Record Length Error—Record Length Error is set on reading a tape mark or a block whose size differs from the block-size argument of the OPEN command. However, this sets the Error Summary bit and traps to $ZTRAP only if the block is too long.
10 1024 Y End of Tape [EOT]
12 4096 Y Parity or CRC Error
14 16384 Y Tape Mark—Caché sets the Tape Mark bit when it encounters a tape mark on Read, Read Block, Forward Space or Backspace. This sets the Error Summary bit and traps to $ZTRAP only on Read, Read Label, and Read Block.
15 32768 Y Tape Not Ready
Some bits indicate error conditions, while other bits indicate conditions that do not necessarily produce an error. If your program must be aware of these non-error conditions, it must test the appropriate bit of $ZA after every magnetic tape operation. For example, a program that might write off the end of the tape must check bit 10, End of Tape.
To test a bit, divide $ZA by the value for that bit listed in the above table and perform a modulo 2 operation. For example, to check if bit 14, Tape Mark, is set, enter:
   USE 47 
   IF $ZA\16384#2 {
      DO Endfile }
   ELSE { QUIT }
where 16384 is 2 to the 14th power and #2 is the modulo 2 operation. Since any number to the 0 power equals 1, you do not need a divisor to check bit 0, Logical Error. Simply enter:
   USE 47 
   GOTO LogErr:$ZA#2
$ZB Holds Information about Driver Buffer
$ZB contains the number of bytes of data remaining in the magnetic tape driver's internal buffer. Immediately after you read a block, this number is the block size. As READ commands transfer logical records from the buffer to Caché ObjectScript variables, the number in $ZB decreases until the next block enters the buffer.
When you write to tape, $ZB shows the number of unused bytes remaining in the driver's internal buffer. Immediately after you write a block, this number is the buffer size that the OPEN command specified. As WRITE commands transfer logical records from ObjectScript variables into the buffer, the number in $ZB decreases until Caché writes the buffer's contents in the next block.
Most magnetic tape programs need not be concerned with $ZB; $ZB is useful for programs that must deal with unusual formats and variable-length blocks. See $ZB in the Caché ObjectScript Language Reference.
Example
This example checks $ZA and $ZB after each magnetic tape read, and sets MTERR when either of these variables indicates an error. It also sets $ZTRAP when a magnetic tape error occurs.
  ; $$MTIN(MTDEV) = the next logical record read from
  ; magtape device MTDEV.
  ; Also returns ZA=$ZA and ZB=$ZB 
  ; On a magtape error, MTERR=1 and $$MTIN(MTDEV)="" 
  ; Expects the caller to have set $ZTRAP to trap other
  ; errors. 
  ;
MTIN(IO) 
     NEW REC,CURDEV 
     SET MTERR=0,CURDEV=$IO,$ZTRAP="MTIERR" 
     USE IO
     READ REC
MTIEXIT
     SET ZA=$ZA,ZB=$ZB
     USE CURDEV 
     QUIT REC 
  ;
MTIERR 
      IF $ZE'["<MAGTAPE>" { 
          USE CURDEV 
          ZQUIT 1 
          GOTO @$ZT }
  ; Use caller's error trap. 
     SET $ZT="",MTERR=1,REC="" 
     GOTO MTIEXIT
Magnetic Tape Mnemonic Space for WRITE /mnemonic
Caché provides a routine named ^%XMAG which contains the default mnemonic space for magnetic tape devices. Using this default allows you to use the mnemonics defined in the following table to issue commands to your tape drive using the form:
   WRITE /mnemonic
^%XMAG Magnetic Tape Mnemonic Space
Mnemonic Description
INIT(%volume,%density, %format) Write ANSI-standard tape header label with specified density (if software-settable) and format. The volume parameter is not used. Permissible density values are: 800, 1600 (default) and 6250. See Magnetic Tape Format Codes for format values. “ SA” (stream, ANSI) is the default.
MOUNT(%device,%volume) Not implemented.
DISMOUNT(%unload) Not implemented.
SEEKFILE(filename) Not implemented.
REWIND Rewind tape volume to beginning.
ENDFILE Write end-of-file mark.
NEWFILE Create new file by writing header label. If tape at BOT, writes a volume label before the header label.
TAPEMARK Write tapemark. If the buffer contains unwritten data, that data is written out first.
SKIPBLOC(%1) Advance the tape %1 block(s). %1 must be a positive integer.
SKIPMARK(%1) Advance or back up tape %1 tapemark(s). If %1 is greater than zero, go forward; if %1 is less than zero, go backward.
SKIPFILE Not implemented.
BLOCKSIZ(%bsize) Close magnetic tape device and open it with block size set to bsize.
FIXED(%rsize) Close magnetic tape device and open it with the “F” parameter and record length set to rsize.
Using the OpenVMS Magnetic Tape Handler
You can also use the OpenVMS magnetic tape handler. This magnetic tape handler lets you use a magnetic tape device as if it were a slow disk. You can create, read, and write in RMS file format. To use the OpenVMS tape handler, use the I/O commands as described in the chapter Sequential File I/O.