Updated: 11 December 1998 |
OpenVMS Record Management Services Reference
Manual
Previous | Contents | Index |
The ACL length (ACLLEN) field receives the length (in bytes) of the access control list for the file during an Open or a Display operation. If the file has no ACL, the XAB$W_ACLLEN field has a value of 0.
If the file has an ACL that fits in the user's buffer, the value of the XAB$W_ACLLEN field is equal to the number of bytes in the ACL. Even if the file's ACL does not fit into the user's buffer, the value of the XAB$W_ACLLEN field is still equal to the number of bytes in the ACL (not just the length of that portion that fits into the buffer).
To determine the number of ACL entries that are in the user's buffer, you must process binary ACEs until you find an ACE with a value of 0 or until you come to the end of the buffer.
The use of this field for DECnet for OpenVMS remote file access is not
supported.
15.5 XAB$W_ACLSIZ Field
The ACL buffer size (ACLSIZ) field specifies the length of the user buffer pointed to by the XAB$L_ACLBUF field.
RMS passes all information, including the ACL buffer, to and from the file system using buffered I/O operations. RMS limits buffered I/O transfers to 512 bytes, excluding the ACL buffer. Therefore, the size of the ACL buffer plus 512 bytes cannot exceed either the BYTLM quota for the process or the MAXBUF value for the system.
The use of this field for DECnet for OpenVMS remote file access is not
supported.
15.6 XAB$L_ACLSTS Field
The ACL error status (ACLSTS) field contains a system error status relating to the processing of ACLs. A value is returned to this field upon a successful return from a Create, Open, or Display service.
Whenever you use the XAB$L_ACLBUF, XAB$L_ACLCTX, XAB$W_ACLLEN, or XAB$W_ACLSIZ fields, be sure to use the following error-handling guidelines:
This extra level of error checking is necessary because the success or failure of reading and writing ACLs is independent of the success or failure of the whole operation. Thus, in the absence of this additional error checking, it is possible to create a file successfully even though an ACL error occurred.
This field is relevant only when an ACL is used with a Create service
or when an ACL is returned from an Open or Display service. The use of
this field for DECnet for OpenVMS remote file access is not supported.
15.7 XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length
of the XABPRO, in bytes. Once set, this field must not be altered
unless the control block is no longer needed. This field must be
initialized to the symbolic value XAB$C_PROLEN (this is done by the
$XABPRO macro).
15.8 XAB$B_COD Field
The type code (COD) field is a static field that identifies this
control block as a XABPRO. Once set, this field must not be altered
unless the control block is no longer needed. This field must be
initialized to the symbolic value XAB$C_PRO (this is done by the
$XABPRO macro).
15.9 XAB$W_GRP Field
The file owner group number (GRP) field contains the half of the XAB$L_UIC field that defines the group number. Refer to the XAB$L_UIC field description for additional information. The contents of the XAB$L_UIC field, rather than the $XABPRO macro, establish the initial value of the XAB$W_GRP field.
This field corresponds to the FDL attribute FILE OWNER.
15.10 XAB$W_MBM Field
The file owner member number (MBM) field contains the half of the XAB$L_UIC field that defines the member number. Refer to the XAB$L_UIC field description for additional information. The contents of the XAB$L_UIC field, rather than the $XABPRO macro, establish the initial value of the XAB$W_MBM field.
This field corresponds to the FDL attribute FILE OWNER.
15.11 XAB$B_MTACC Field
The magnetic tape accessibility (MTACC) field enables you to access HDR1 labels for ANSI-labeled magnetic tapes, in compliance with ANSI standards. The value specified in the XAB$B_MTACC field is input to the Create service and output from the Open and Display services for magnetic tape only.
The character to be inserted in the accessibility field of the HDR1 label must be one of the following:
This field corresponds to the FDL attribute FILE MT_PROTECTION, and it
is not supported for DECnet for OpenVMS operations.
15.12 XAB$L_NXT Field
The next XAB address (NXT) field specifies the symbolic address of the
next XAB in the XAB chain. A value of 0 (the default) indicates that
the current XAB is the last (or only) XAB in the chain.
15.13 XAB$W_PRO Field
The file protection (PRO) field specifies the file access privileges that RMS grants to the four classes of users: System, Owner, Group, and World.
This field consists of four 4-bit subfields, each of which specifies file access privileges for one of the four user classes.
You can specify the user class using the $XABPRO macro or through the use of symbolic offsets, if you do not have access to the VAX macro libraries. This is the syntax for representing the four user classes as arguments to a $XABPRO macro:
<SYSTEM,OWNER,GROUP,WORLD> |
Alternatively, you can specify the user class using the appropriate symbolic offset from the following list:
PRO = <RW,RW,RW,RW> |
A logical 0 enables access; a logical 1 denies access. |
Users are granted the maximum number of types of access rights for each of the classes to which they belong.
Figure 15-1 illustrates the organization of the subfields in the XAB$W_PRO field.
Figure 15-1 File Protection Field
If you do not explicitly specify file protection when you invoke the Create service, RMS attempts to determine file protection by default in the following order:
The following table provides detailed descriptions of the four user classes.
User Class | Description |
---|---|
System | Specifies access rights for users executing under a system UIC, that is, users whose group number is less than the value for a system UIC, which is defined by the system manager (usually 10 or less). |
Owner | Specifies access rights for the owner of the file. A user is considered the owner of the file only if both the group and member number fields of the accessing process match the group and member number fields of the file owner's UIC stored with the file. |
Group | Specifies the access rights for users whose group number matches the group number field of the file owner. |
World | Specifies access rights for all users. World access is used for granting access to users who are not in the system, owner, or group classifications. |
This field corresponds to the FDL attribute FILE PROTECTION.
15.14 XAB$B_PROT_OPT Field
The ACL file protection (PROT_OPT) field provides a single option, the XAB$V_PROPAGATE option, which is used as input during an Enter or a Rename operation. (During a Rename operation, the protection XAB is assumed to be attached to FAB2.)
The XAB$B_PROT_OPT field is a binary options field where each file protection option has a corresponding bit assignment. Options are identified using mnemonics, and each option has its own symbolic offset and mask value. For example, the PROPAGATE option has a symbolic offset of XAB$V_PROPAGATE and a mask value of XAB$M_PROPAGATE.
If the XAB$V_PROPAGATE bit is set in this field during either an Enter or Rename operation, the file receives new security attributes when the new directory entry is made. These security attributes follow the same rules as apply during a Create operation. For example, if a lower version of a new file exists, the new file inherits the security attributes of the next lower version of the file. If the XAB$V_PROPAGATE bit is not set, the security attributes of the new file do not change.
This field is not supported for DECnet for OpenVMS operations.
15.15 XAB$L_UIC Field
The user identification code (UIC) field combines the two XABPRO fields that define the UIC of the owner of a file: the XAB$W_GRP (group number) and XAB$W_MBM (member number) fields. Both numbers are octal numbers. The valid range for a group number is 0 to 37777; the valid range for a member number is 0 to 177777. Note that the maximum value in each case (37777 and 177777) is reserved for Compqy use only. This field corresponds to the FDL attribute FILE OWNER.
The symbolic offsets for the group number field and the member number field respectively are XAB$W_GRP and XAB$W_MBM.
The total user identification field, including both the group and member number fields, has a symbolic offset of XAB$L_UIC.
Note that if no file protection XAB is provided or if the user identification field is null for a Create service, RMS determines the owner's UIC using the following logical order:
If you wish to create an output file with a UIC different from your own, you must have system privilege (SYSPRV).
The revision date and time XAB (XABRDT) complements the date and time XAB (XABDAT) by providing revision time and date input to the Close service when RMS closes a file that has been modified. Like the XABDAT, the XABRDT can be used as input to the Create Service or can be used to store revision data returned by the Open service or the Display service. The distinction is that XABDAT cannot be used to modify the revision data. Only the XABRDT can be used to update revision data when a file is closed after being modified. Typically, a process would use the two data structures when it wants to sense and set revision data within a single file operation.
To change the revision data, the process must have Control access to the file and must have opened the file for modification using the Put, Update, Truncate, or Delete service. Normally when RMS closes a file and these conditions prevail, it uses the current date and time as the revision date and time and increments the revision number. Thus, the previous revision values for the file are superseded. (See the Security Guide for more information about CONTROL access.)
Using the XABRDT as an input to a Close service, you can specify a set
of revision values other than the current time and date and the next
revision number.
16.1 Summary of Fields
The two XABRDT fields that specify revision values are the XABQ_RDT (revision date and time) field and the XAB$W_RVN (revision number) field.
The following table indicates how RMS uses the XABRDT fields for various file-processing services.
Service | Input/Output |
---|---|
Close | Input |
Create | Input |
Display | Output |
Erase | Not used |
Extend | Not used |
Open | Output |
The Open service overwrites the XAB$Q_RDT and XAB$W_RVN fields with the file's existing revision values. If you do not change these values, the existing values are subsequently input to the Close service and the file's revision data is not updated.
To change the revision data, you must set the fields between the time you open the file and the time you close the file. If you specify a revision date and time of 0 or if you do not include a XABRDT as input to the Close service, RMS uses the current date and time for the revision date and time and increments the revision number.
To sense the contents of the XAB$Q_RDT and XAB$W_RVN fields before you specify new values with the XABRDT, examine the XAB$Q_RDT field and the XAB$W_RVN field in the XABDAT block.
The symbolic offset, size, FDL equivalent, and a brief description of each XABRDT field are presented in Table 16-1.
Field Offset | Size (Bytes) |
FDL Equivalent | Description |
---|---|---|---|
XAB$B_BLN 1 | 1 | None | Block length |
XAB$B_COD 1 | 1 | None | Type code |
XAB$L_NXT | 4 | None | Next XAB address |
XAB$Q_RDT 2 | 8 | DATE REVISION | Revision date and time |
XAB$W_RVN 2 | 2 | FILE REVISION | Revision number |
Unless otherwise indicated, each field is supported for DECnet for
OpenVMS operations on files at remote OpenVMS systems. For information
about the support of RMS options for remote file access to other
systems, see the DECnet for OpenVMS Networking Manual.
16.2 XAB$B_BLN Field
The block length (BLN) field is a static field that defines the length
of the XABRDT, in bytes. Once set, this field must not be altered
unless the control block is no longer needed. This field is initialized
to the symbolic value XAB$C_RDTLEN by the $XABRDT macro.
16.3 XAB$B_COD Field
The type code (COD) field is a static field that identifies this
control block as a XABRDT. Once set, this field must not be altered
unless the control block is no longer needed. This field is initialized
to the symbolic value XAB$C_RDT by the $XABRDT macro.
16.4 XAB$L_NXT Field
The next XAB address (NXT) field contains the symbolic address of the
next XAB to be used. A value of 0 (the default) indicates that the
current XAB is the last (or only) XAB in the chain.
16.5 XAB$Q_RDT Field
The revision date and time (RDT) field contains a 64-bit binary value expressing the date and time when the file was last opened for modifications. Note that this field is limited to a granularity of 1 second for remote files.
This field corresponds to the FDL attribute DATE REVISION.
16.6 XAB$W_RVN Field
The revision number (RVN) field contains a numeric value that indicates the number of times this file was opened for modifications.
This field corresponds to the FDL attribute FILE REVISION.
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4523PRO_018.HTML
|