Document revision date: 15 July 2002

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:

• If the FAB$L_STS field (R0) contains an error status, handle the error in the usual manner.
• If the FAB$L_STS field (R0) contains a success status, then you must check the value in XAB$L_ACLSTS. If XAB$L_ACLSTS contains a success status, then the entire operation completed successfully and no further action is required; if XAB$L_ACLSTS contains an error status, handle the error appropriately. Note that a value is placed in the XAB$L_ACLSTS field only when a success status is returned in FAB$L_STS (R0).

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:

• An uppercase letter from A through Z
• A digit from 0 through 9
• One of the following special characters: (!), (%), (&), ('), ((), ()), (*), (+), (,), (-), (.), (/), (:), (;), (<), (=), (>), (?)

Note that if this field is not specified or if the specification is invalid, a space character is inserted into the HDR1 accessibility field.

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:

• System---XAB$V_SYS
• Owner---XAB$V_OWN
• Group---XAB$V_GRP
• World---XAB$V_WLD

You can also specify access privileges for each user class using the $XABPRO macro or through the use of symbolic mask values. Using a $XABPRO macro, you insert the appropriate initial letters for each user class in the macro argument:

• R---read access
• W---write (modify) access
• E---execute access
• D---delete access

For example, to grant each user class read and write privileges, you would use this line of code:

PRO = <RW,RW,RW,RW>

Alternatively, you can specify user class privileges using the appropriate symbolic mask value from the following list:

• No read access---XAB$M_NOREAD
• No write access---XAB$M_NOWRITE

• No execute access---XAB$M_NOEXE
• No delete access---XAB$M_NODEL

If you do not specify access privileges for a file, by default RMS grants all access privileges (read, write, execute, delete) to all user classes by zeroing all bits in the XAB$W_PRO field.

You cannot deny all access to all user classes through the RMS interface. If you set all bits in the XAB$W_PRO field to logical 1, RMS assigns the file process default protection.

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:

1. Using the protection assigned to an existing file of the same name
2. Using the default file protection of the directory
3. Using the process-default protection

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:

1. The owner UIC of an existing version of the file if the creating process has ownership rights to the previous version
2. The owner UIC of the parent directory, if the creating process has ownership privileges to the parent directory
3. The UIC of the creating process

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 64-bit XAB$Q_RDT binary field indicates the date and time when the file was last opened for modifications.
• The XAB$W_RVN field indicates how many times the file is opened for modifications.

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.

Table 16-1 XABRDT Fields

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.

	privacy and legal statement
4523PRO_020.HTML