{
{   The purpose of this request is to return tape label attributes for a
{ magnetic tape file.  The attribute values are returned in a format that
{ allows them to be input to the FILE_ATTACHMENT parameter of a subsequent
{ FSP$OPEN_FILE request.
{
{   If the file is not currently attached to the requesting job or is not a
{ magnetic tape file, abnormal status is returned.
{
{   It is possible that not all attributes are defined for a particular SOURCE.
{ Refer to the discussion of the RETURNED_ATTRIBUTES for more information.
{
{       FSP$GET_TAPE_LABEL_ATTRIBUTES (FILE_REFERENCE, SOURCE, ATTRIBUTES,
{         RETURNED_ATTRIBUTES, STATUS)
{
{ FILE: (input)  This parameter specifies the name of the magnetic tape file
{       whose label attributes are to be returned.
{
{ SOURCE: (input)  This parameter specifies the source of the attribute values
{       that are to be returned.  Three options are supported:
{       FSC$TLA_LAST_ANSI_FILE_ACCESSED, FSC$TLA_EXPLICIT_SPECIFICATION, and
{       FSC$TLA_NEXT_POSITION.
{
{       Abnormal status is returned if the FILE_LABEL_TYPE is <> amc$labeled
{       and either FSC$TLA_LAST_ANSI_FILE_ACCESSED or FSC$TLA_NEXT_POSITION is
{       selected.
{
{       1.  The option FSC$TLA_LAST_ANSI_FILE_ACCESSED returns values defined
{           in the last ANSI file read from or written to the tape file.  If no
{           ANSI file has been previously accessed for the current attachment
{           of the file to the requesting job, the ATTRIBUTES parameter is not
{           modified and no attributes are included in the RETURNED_ATTRIBUTES
{           set.  If this request is issued while a labeled tape file is open,
{           the information contained in the header labels of the currently
{           opened ANSI file is returned.
{
{           You may obtain the most recently accessed (read or written) ANSI
{           header or trailer label group by requesting the HEADER_LABELS or
{           TRAILER_LABELS fields, respectively.
{
{       1.a A header label group always includes a file header label group and
{           may include a volume header label group.  A header label group is
{           read or written by NOS/VE whenever an ANSI file is opened or when
{           the current ANSI file is positioned to the beginning of each
{           volume.
{
{           A volume header label group is returned only if the volume is
{           positioned beyond loadpoint and before the second ANSI file on a
{           volume.  This is true for each volume in the volume set.  However,
{           the content of the volume header label group changes as each new
{           volume of a multi-volume file is accessed.  For example, the
{           VOLUME_IDENTIFIER field of the VOL1 label changes to reflect the
{           identity of the last volume mounted and the FILE_SECTION_NUMBER
{           increments by one for each volume the file spans.
{
{           The OWNER_IDENTIFICATION and VOLUME_ACCESSIBILITY fields of the
{           VOL1 label and the FILE_ACCESSIBILITY field of the HDR1 label are
{           secure fields.  Unless the program is executing with
{           REMOVABLE_MEDIA_ADMINISTRATION privilege these fields are set to
{           blanks (' ').
{
{           HEADER_LABELS returns all available header labels, including
{           system-defined labels (VOL1, HDR1, and HDR2), site-defined labels
{           (VOL2..VOL9 and HDR3..HDR9), and user-defined labels (UVL1..UVL9
{           and UHLx, where x is an ANSI a-character).
{
{       1.b A trailer label group includes either an end of file label group or
{           an end of volume label group.  An end of volume label group is
{           included if an ANSI file is currently open, it spans multiple
{           volumes, and the FILE_SECTION_NUMBER is > 1; otherwise, an end of
{           file label group is included.  A trailer label group is read by
{           NOS/VE when the logical position is at end of information or end of
{           volume.  A file trailer label group is written whenever a volume
{           has been previously written upon and the physical volume position
{           is reversed (by a rewind, backward skip, etc.) or the file is
{           closed.  A volume trailer label group is written whenever the
{           current volume cannot hold all of the data to be written.
{
{           TRAILER_LABELS returns all available ANSI trailer labels, including
{           system-defined labels (EOV1, EOV2, EOF1 and EOF2), site-defined
{           labels (EOV3..EOV9 and EOF3..EOF9), and user-defined labels
{           (UTL1..UTLx, where x is an ANSI a-character).
{
{           The FILE_ACCESSIBILITY field of the EOF1 or EOV1 label is a secure
{           field.  Unless the program is executing with
{           REMOVABLE_MEDIA_ADMINISTRATION privilege the value ' ' is returned
{           for FILE_ACCESSIBILITY within either of these labels.
{
{       1.c One can monitor the switching of volumes on an ANSI file by
{           sampling the VOLUME_NUMBER provided by AMP$FETCH_ACCESS_INFORMATION
{           after accessing a record or performing a positioning operation.
{
{       1.d The FILE_SET_POSITION and REWRITE_LABEL attributes are undefined
{           for this option and no value is returned.
{
{       2.  The option FSC$TLA_EXPLICIT_SPECIFICATION returns values defined by
{           the CHANGE_TAPE_LABEL_ATTRIBUTES (CHATLA) command for the current
{           attachment of the file.  If the file is currently open, the values
{           returned are the result of the merging of attributes specified on
{           FSP$OPEN_FILE with those specified by the CHATLA command, with the
{           the FSP$OPEN_FILE specifications taking precedence.  If an
{           attribute has not been specified by a CHATLA command or
{           FSP$OPEN_FILE, no value is returned by the ATTRIBUTES parameter
{           and the attribute is not included in the RETURNED_ATTRIBUTES set.
{
{           The following attributes are not supported by this option and no
{           value is returned:  BUFFER_OFFSET, FILE_SECTION_NUMBER,
{           IMPLEMENTATION_IDENTIFIER, LABEL_STANDARD_VERSION, HEADER_LABELS,
{           and TRAILER_LABELS.
{
{           Because tape attachment options specified in the FILE_ATTACHMENT
{           parameter of FSP$OPEN_FILE supercede any specification by the
{           CHANGE_TAPE_LABEL_ATTRIBUTES (CHATLA) command, a program that
{           specifies a tape label attribute via FSP$OPEN_FILE prevents a user
{           from influencing the value of the attribute.  While this capability
{           is necessary, the result may be too inflexible in some situations.
{           Prior to opening the file, you may use the
{           FSC$TLA_EXPLICIT_SPECIFICATION option of this request to obtain any
{           attribute values provided by a CHATLA command.  You may then choose
{           to accept values provided by a CHATLA command and pass them along
{           to FSP$OPEN_FILE or provide your own specification.
{
{       3.  The option FSC$TLA_NEXT_POSITION returns values that are to be
{           applied to the next ANSI file to be accessed in the magnetic tape
{           file.  If no ANSI file has been previously accessed and no CHATLA
{           command has been previously executed for the file within the
{           requesting job, system default values are returned.
{
{       3a.  With the exception of BLOCK_TYPE, CHARACTER_CONVERSION,
{            CHARACTER_SET, CREATION_DATE, EXPIRATION_DATE, FILE_SET_POSITION,
{            MAXIMUM_BLOCK_LENGTH, MAXIMUM_RECORD_LENGTH, PADDING_CHARACTER,
{            RECORD_TYPE, and REWRITE_LABELS, the values of the attributes
{            returned are a result of merging the attributes of the last ANSI
{            file accessed with any CHATLA specification for the current
{            attachment; the latter specification takes precedence.  If there
{            is no CHATLA specification for BLOCK_TYPE, CHARACTER_CONVERSION,
{            CHARACTER_SET, CREATION_DATE, EXPIRATION_DATE, FILE_SET_POSITION,
{            MAXIMUM_BLOCK_LENGTH, MAXIMUM_RECORD_LENGTH, PADDING_CHARACTER,
{            RECORD_TYPE, or REWRITE_LABELS, system default values are returned.
{
{            The values of the following attributes are controlled by the
{            system; values returned are those that would be written if the
{            next position requires labels to be written to the volume:
{            BUFFER_OFFSET, FILE_SECTION_NUMBER, IMPLEMENTATION_IDENTIFIER,
{            LABEL_STANDARD_VERSION.
{
{       3b.  With the exception of the REWRITE_LABELS and FILE_SET_POSITION
{            attributes, the values returned are those that would be recorded
{            in the label of the next ANSI file written, if one is written.
{
{       3c.  The value returned for the FILE_SET_POSITION attribute defines the
{            manner in which the volume set is to be positioned prior to
{            accessing the next ANSI file.
{
{       3d.  If the FILE_SET_POSITION value is FSC$TAPE_FILE_IDENTIFIER_POS,
{            the FILE_IDENTIFIER and GENERATION_NUMBER returned in the
{            TAPE_FILE_SET_POSITION field identify the ANSI file to which the
{            tape file will be positioned as a result of the next call to
{            FSP$OPEN_FILE (in the absence of a positioning specification by
{            the program).
{
{       3e.  If the FILE_SET_POSITION attribute is requested and the file set
{            position value is FSC$TAPE_FILE_SEQUENCE_POS, the
{            FILE_SEQUENCE_NUMBER field returned in the TAPE_FILE_SET_POSITION
{            record identifies the ordinal file position that will be attained
{            at the the next call to FSP$OPEN_FILE (in the absence of a
{            positioning specification by the program).
{
{       3f.  If the FILE_SEQUENCE_NUMBER attribute is requested, the value
{            returned (if one is returned) is derived from the
{            FILE_SET_POSITION attribute.
{
{            If the FILE_SET_POSITION is FSC$TAPE_FILE_SEQUENCE_POS, the value
{            specified by the FILE_SEQUENCE_NUMBER field of FILE_SET_POSITION
{            is returned.
{
{            If the FILE_SET_POSITION is not FSC$TAPE_FILE_SEQUENCE_POS, the
{            value of the FILE_SEQUENCE_NUMBER attribute can be predicted when
{            the FILE_SET_POSITION is FSC$BEGINNING_OF_SET, FSC$CURRENT_FILE,
{            or FSC$TAPE_NEXT_FILE.  The value 1 is returned for
{            FSC$BEGINNING_OF_SET.  The ordinal value of the last ANSI file
{            (the current value) is returned for FSC$CURRENT_FILE.  The current
{            value + 1 is returned for FSC$TAPE_NEXT_FILE.
{
{            If the FILE_SET_POSITION is FSC$TAPE_END_OF_SET and the volume is
{            already positioned at end of set, the ordinal value of the next
{            file to be written is returned.
{
{            If the FILE_SET_POSITION is FSC$TAPE_FILE_IDENTIFIER_POS, a value
{            is returned only when the file_identifier and generation_number of
{            the last_accessed file match the next_position values of
{            file_identifier and generation_number.
{
{ ATTRIBUTES: (input, output)  On input, this parameter specifies the identity
{       of the attributes whose values are requested and the order in which the
{       attributes are returned.  On output, this parameter specifies the value
{       of each of the attributes that were requested, if a value is returned.
{
{       If no value is returned for an attribute, the corresponding input
{       record is not modified by this request.  This allows you to use this
{       request to merge tape label attributes in a convenient way.  For
{       example, if you wanted to copy one labeled file to another and use the
{       attributes of the input file as the default attributes of the output
{       file, you would make two requests and use the same ATTRIBUTES array for
{       both requests.  The first request is for the input file; specify
{       FSC$TLA_LAST_ANSI_FILE_ACCESSED.  The second request is for the output
{       file; specify FSC$TLA_EXPLICIT_SPECIFICATION.  This allows the command
{       user to specify alternative attributes for the output file via the
{       CHANGE_TAPE_LABEL_ATTRIBUTES command.  Any value specified by a CHATLA
{       command for the output file replaces the value obtained from the input
{       file; ATTRIBUTES not specified by a CHATLA are retained.  Refer to the
{       RETURNED_ATTRIBUTES parameter for further discussion.
{
{       The FST$ATTACHMENT_OPTION type is used by this parameter to make it
{       easier to use this request prior to calling FSP$OPEN_FILE.  For this
{       reason, this request ignores records in the input array that are not of
{       type FSC$TAPE_ATTACHMENT.
{
{       The secure attributes FILE_ACCESSIBILITY, OWNER_IDENTIFIER,
{       REMOVABLE_MEDIA_GROUP, and VOLUME_ACCESSIBILITY may only be requested
{       by a program executing under the SYSTEM_OPERATOR_UTILITY with the
{       REMOVABLE_MEDIA_ADMINISTRATION capability active; otherwise, abnormal
{       status is returned.
{
{       The HEADER_LABELS and TRAILER_LABELS are returned in a sequence.  The
{       caller allocates the sequence and this request initializes the sequence
{       with the label group.  The size of a label group may vary according to
{       vendor.  The ANSI X3.27 1987 File Structure and Labeling of Magnetic
{       Tapes for Information Interchange standard defines the possibility of
{       84 labels in a label group, each 80 characters in length.  However,
{       some vendors may write labels longer than 80 characters.  NOS/VE
{       accepts individual labels of up to 4128 bytes in length.
{
{       The label group sequence begins with a record of type
{       FST$TAPE_LABEL_SEQUENCE_HEADER.  The caller's sequence must be at least
{       the size of this record or abnormal status is returned.  If the caller's
{       sequence is smaller than the size of the label group, but >=
{       #SIZE(FST$TAPE_LABEL_SEQUENCE_HEADER), abnormal status is returned and
{       only the header record is stored in the sequence.  The field
{       SEQUENCE_SIZE in the header returns the size of the label group
{       in bytes.  This allows the caller to reallocate a sequence of the
{       necessary size and successfully reissue the request.
{
{       Processing of label records in the sequence may occur according to the
{       following algorithm.  The result of the algorithm is to obtain pointers
{       to the VOL1 and HDR1 labels:
{
{       NEXT sequence_header IN label_group;
{       IF fsc$ansi_vol1_label_kind IN sequence_header^.label_kinds THEN
{         label_identifier.location_method := fsc$tape_label_locate_by_kind;
{         label_identifier.label_kind := fsc$ansi_vol1_label_kind;
{         fsp$locate_tape_label (label_group, label_identifier, label_locator);
{         IF label_locator.label_found THEN
{           RESET label_locator.label_block;
{           NEXT vol1_label IN label_locator.label_block;
{         ELSE
{           vol1_label := NIL;
{         IFEND;
{       IFEND;
{       IF fsc$ansi_hdr1_label_kind IN sequence_header^.label_kinds THEN
{         label_identifier.location_method := fsc$tape_label_locate_by_kind;
{         label_identifier.label_kind := fsc$ansi_hdr1_label_kind;
{         fsp$locate_tape_label (label_group, label_identifier, label_locator);
{         IF label_locator.label_found THEN
{           RESET label_locator.label_block;
{           NEXT hdr1_label IN label_locator.label_block;
{         ELSE
{           hdr1_label := NIL;
{         IFEND;
{       IFEND;
{
{       For each label returned, the "TRANSFER_LENGTH" field of the
{       FST$TAPE_LABEL_BLOCK_DESCRIPTOR record indicates the length of the ANSI
{       label directly following the header in the sequence.  If the label was
{       greater than 4128 bytes in length the label is truncated and only the
{       first 4128 bytes of the label are returned.  If the label block could
{       not be read without error, the LABEL_BLOCK_TYPE field of the
{       FST$TAPE_LABEL_BLOCK_DESCRIPTOR record is set to
{       FSC$ERRONEOUS_TAPE_LABEL_BLOCK, and the ERRONEOUS_LABEL_FAILURE_MODES
{       field identifies the fault symptom.
{
{       The caller's sequence pointer is not updated by this request;
{       therefore, the pointer points to a record of type
{       FST$TAPE_LABEL_SEQUENCE_HEADER at the completion of a normal request.
{
{ RETURNED_ATTRIBUTES: (output)  This parameter specifies the identity of each
{       of the attributes for which a value was returned in the ATTRIBUTES
{       parameter.
{
{       If an attribute has no value or it is not defined for the SOURCE
{       specified, the corresponding record in the ATTRIBUTES parameter is not
{       modified and the attribute is not included in the RETURNED_ATTRIBUTES
{       set.
{
{ STATUS: (output)  This parameter specifies the request status.
{
