MTS_$INTRO Domain/OS MTS_$INTRO
NAME
intro - using magtape descriptor files
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/mts.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/mts.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/mts.ins.ftn'
DESCRIPTION
A magtape descriptor file is the file system interface to a magnetic tape
device. The magtape descriptor file for a device contains a list of
attributes that define and control the state of the device. The mts_$
calls allow user programs to manage magtape descriptor files and their
attributes, and thereby control tape I/O.
The following is a list of the mts_$ calls.
mts_$close_desc close a magtape descriptor file
mts_$copy_desc copy a magtape descriptor file
mts_$create_default_desc create a default magtape descriptor file
mts_$get_attr get a magtape descriptor attribute
mts_$label label a magtape
mts_$open_desc open a magtape descriptor file
mts_$open_desc_uid open a magtape descriptor file
mts_$set_attr set a magtape descriptor attribute
Constants
mts_$current_file_seq
A value of the mts_$file_sequence_a attribute that specifies the
file at the current position on a tape with an ANSI volume label.
mts_$end_file_seq
A value of the mts_$file_sequence_a attribute that specifies a new
file at the end of the current file set on an ANSI labeled volume.
mts_$first_a
Designates the first enumerated value of type mts_$attr_t: the
first tape descriptor attribute. Use it with mts_$last_a to access
all tape descriptor attributes.
mts_$last_a
Designates the last enumerated value of type mts_$attr_t: the last
tape descriptor attribute. Use it with mts_$first_a to access all
magtape device attributes.
Data Types
mts_$attr_t
An enumerated type for specifying a tape file attribute. It takes
one of the following values:
mts_$ascii_nl_a
This attribute is a Boolean value that specifies how ASCII new-
lines are handled during tape I/O. If true, newlines are
stripped on writes and added on reads. If false, newlines are
left alone. The default is true.
mts_$block_length_a
This attribute is the file block length in bytes. The default
value is 2048.
mts_$buffer_offset_a
This attribute is the buffer offset in bytes for files on
ANSI-labeled volumes. The default value is 0.
mts_$close_vol_a
This attribute is a Boolean value that specifies whether the
tape volume should be closed when an open stream to the
descriptor file is closed. If true, the tape volume is closed
when the stream is closed. If false, the tape volume is not
closed when the stream is closed. The default is true.
mts_$create_date_a
This attribute is a string that specifies a file creation date
on an ANSI-labeled volume. The value associated with
mts_$create_date_a is a new creation date string for the
volume. A valid date string is an array of 19 ASCII characters
with the format "YEAR/MONTH/DAY HOUR:MINUTE:SECOND", where YEAR
is a 4-digit decimal integer, and MONTH, DAY, HOUR, MINUTE, and
SECOND are all 2-digit decimal integers with the appropriate
ranges. The default file creation date is "-auto" padded out
with spaces to 19 characters, which uses the system date for
the ANSI file creation date field.
mts_$exp_date_a
This attribute is a string that specifies a file expiration
date on a labeled volume. A valid date string is an array of
19 characters with the format
"YEAR/MONTH/DAY HOUR:MINUTE:SECOND", where YEAR is a 4-digit
decimal integer, and MONTH, DAY, HOUR, MINUTE, and SECOND are
all 2-digit decimal integers with the appropriate ranges. The
default file creation date is "-auto" padded out with spaces to
19 characters, which writes spaces into the ANSI file expira-
tion date field.
mts_$file_id_a
This attribute is a file identifier string on an ANSI-labeled
volume. The value associated with mts_$file_id_a is an array
of 17 characters associated with a file on the tape. The
default file identifier is blank.
mts_$file_section_a
This attribute is the file section number on an ANSI-labeled
volume. The default file section number is 1.
mts_$file_sequence_a
This attribute is the file sequence number. The default value
is 1. If the volume is labeled, then the value
mts_$current_file_seq specifies the current file, and the value
mts_$end_file_seq specifies a new file at the end of the
volume.
mts_$file_set_id_a
This attribute is a file set identifier string on an ANSI-
labeled volume. A file set identifier is an array of six char-
acters, associated with all files in a file set. The default
file set identifier is blank.
mts_$generation_a
This attribute is a file generation number on an ANSI-labeled
volume. The default is 0.
mts_$generation_version_a
This attribute is the file generation version number on an
ANSI-labeled volume. The default is 0.
mts_$file_access_a
This attribute is a file accessibility value on an ANSI-labeled
volume. The file accessibility is a single-character value.
The default is a blank.
mts_$labeled_a
This attribute is a Boolean value that specifies whether a
volume is labeled in accordance with ANSI X3.27. If true, the
volume is labeled. If false, the volume is not labeled. The
default is true.
mts_$owner_id_a
This attribute is the volume owner identification string on
ANSI-labeled volumes. The volume owner identification is an
array of 14 characters. The default is "-auto" padded out with
spaces to 14 characters, which uses the log-in name of the cal-
ling process' owner for the ANSI volume owner ID field.
mts_$record_format_a
This attribute specifies a record format for a volume. It can
take one of the following single-character values:
`D' The volume contains variable-length records.
`F' The volume contains fixed-length records.
`S' The volume contains spanned records.
`U' The volumes record format is undefined.
The default is `D' for variable length records.
mts_$record_length_a
This attribute is the maximum record length in bytes. The
default is 2048.
mts_$reopen_vol_a
This attribute is a Boolean value that specifies whether the
volume should be opened at the current tape position. If true,
the volume is reopened at the current tape position. If false,
the tape is rewound to the beginning of the volume when opened.
The default is false.
mts_$save_vol_pos_a
This attribute is a Boolean value that specifies whether the
tape should be rewound when the volume is closed. If true, the
tape is not moved when the volume is closed. If false, the
tape is rewound to the beginning of the volume when the volume
is closed. The default is false.
mts_$system_code_a
This attribute is the system code string for an ANSI-labeled
volume. The system code is an array of 13 characters. The
default is blank.
mts_$system_use_a
This attribute is the system use string for an ANSI-labeled
volume. The system use is an array of 35 characters. The
default is blank.
mts_$unit_a
This attribute is the unit number on a tape drive. It is used
to select one drive from a multiple-drive device. The default
is 0.
mts_$vol_access_a
This attribute specifies volume accessibility on an ANSI-
labeled volume. The volume accessibility is a single-character
value. The default is a blank.
mts_$vol_device_a
This attribute specifies a device type. The device type is one
of the following values of the enumerated type mts_$device_t:
mts_$ct
The device is a cartridge tape drive.
mts_$mt
The device is a free tape device.
mts_$vol_id_a
This attribute is the volume identification string on an ANSI-
labeled volume. The volume identification is an array of six
characters. The default is "-auto" padded out with spaces to
six characters, which currently just writes spaces in the ANSI
volume ID field.
mts_$attr_value_t
A variant record type for passing the value of a tape file attri-
bute. The following diagram illustrates the mts_$attr_value_t data
type:
15 0
______________________________________________________________
| i |
|_____________________________________________________________|
| i |
______________________________________________________________
15 0
OR
15 8 7 0
______________________________________________________________
| Not Used | b |
______________________________________________________________
15 8 7 0
OR
15 8 7 0
______________________________________________________________
| s | ... |
______________________________________________________________
15 8 7 0
i An integer value. The maximum integer value for an attribute
is 16K.
b A Boolean value.
s A string.
mts_$device_t
An enumerated type for specifying a device type. It takes one of
the following predefined values:
mts_$ct
A cartridge tape device.
mts_$mt
A free tape device.
mts_$handle_t
A pointer type used to pass a tape descriptor file handle.
mts_$rw_t
An enumerated type for specifying how a tape descriptor file should
be opened. It takes one of the following predefined values:
mts_$read
Open the tape descriptor file for attribute inquiries only.
mts_$write Open the tape descriptor file to set attributes and edit
labels.
Errors
mts_$bad_block_length
Bad block length.
mts_$bad_buffer_offset
Bad buffer offset.
mts_$bad_data
Descriptor contains bad data.
mts_$bad_file_section
Bad file section number.
mts_$bad_file_sequence
Bad file sequence number.
mts_$bad_generation
Bad generation number.
mts_$bad_generation_version
Bad generation version number.
mts_$bad_record_format
Bad record format attribute.
mts_$bad_record_length
Bad record length.
mts_$bad_unit
A bad unit number was specified.
mts_$invalid_attr
An invalid attribute was specified.
mts_$invalid_date
A date string is invalid.
mts_$not_labeled
Requested operation not allowed for unlabeled volume.
mts_$read_only
The descriptor file is not opened for writing.
mts_$vol_in_use
The volume is in use.
mts_$wrong_type
The object is not a tape descriptor file.