| Previous | Contents | Index |
The NO_SHARE option prohibits sharing of the data in a file. The format of the NO_SHARE option is as follows:
NO_SHARE [ (boolean-expression) ] |
By default, the NO_SHARE option is enabled when a file is opened for
output or update. This option is disabled when a file is opened for
input.
7.2.34 OWNER_GROUP Option
The OWNER_GROUP option overrides the default group number in the user identification code (UIC) associated with the file's owner. The group number, together with the member number, defines the ownership of the file and provides the values against which protection is applied. Its format is as follows:
OWNER_GROUP(integer-expression) |
integer-expression
Is an integer value in the range 0 through 16383 (decimal).
Note that although the value can be specified to PL/I in decimal, the OpenVMS system always displays UICs in octal format.
Following is an example of a program using the OWNER_GROUP and the OWNER_MEMBER options to define the ownership of a file. Note the use of the DECODE built-in function to obtain octal numbers for the UIC.
OWNER: PROCEDURE OPTIONS(MAIN);
DCL TEST_FILE STREAM OUTPUT FILE;
OPEN FILE(TEST_FILE)
ENVIRONMENT(OWNER_GROUP(DECODE('214',8)),
OWNER_MEMBER(DECODE('10223',8)));
PUT FILE(TEST_FILE) LIST('This file is owned by UIC [214,10223].');
CLOSE FILE(TEST_FILE);
END OWNER;
|
The OWNER_ID option overrides the default owner of a file. This option combines the capabilities of the OWNER_GROUP and OWNER_MEMBER options. In addition, this option allows the specification of identifiers that are not true UICs, which is not possible with the other two options. Its format is as follows:
OWNER_ID(integer-expression) |
integer-expression
Is any FIXED BINARY value.
Following is an example of a program using the OWNER_ID option:
/*
* This program example creates a file owned by the identifier TEST. (Note
* that the process running this program must hold the identifier with the
* RESOURCE attribute or the file creation will fail.)
*/
%REPLACE IDENTIFIER BY 'TEST';
OWNER_ID: PROCEDURE OPTIONS(MAIN);
%INCLUDE $KGBDEF;
%INCLUDE $STSDEF;
%INCLUDE SYS$ASCTOID;
DCL TEST_FILE STREAM OUTPUT FILE;
DCL IDENTIFIER_VALUE FIXED BINARY;
DCL KGB_BITS BIT(32) ALIGNED;
/*
* Get the value of the identifier. (Note: The fact that the value
* translates successfully does not mean that the current process
* holds the identifier.
*/
STS$VALUE = SYS$ASCTOID( IDENTIFIER, IDENTIFIER_VALUE, KGB_BITS );
IF ~STS$SUCCESS THEN SIGNAL VAXCONDITION(STS$VALUE);
/*
* Does the identifier have the resource attribute? (Note: If you
* want to determine whether this process holds the identifier with the
* resource attribute, you must use the SYS$FIND_HOLDER or SYS$CHKPRO
* system services.)
*/
IF (KGB_BITS & KGB$M_RESOURCE) = '0'b
THEN
PUT LIST('The identifier ' ||
IDENTIFIER || ' does not have the RESOURCE attribute.');
OPEN FILE(TEST_FILE) ENVIRONMENT(OWNER_ID(IDENTIFIER_VALUE));
PUT FILE(TEST_FILE)
LIST('This file is owned by the identifier ' || IDENTIFIER || '.');
CLOSE FILE(TEST_FILE);
END OWNER_ID;
|
The OWNER_MEMBER option overrides the default member number in the user identification code (UIC) associated with the file's owner. The member number of a file's owner, together with the group number, provides protection for the file. Its format is as follows:
OWNER_MEMBER(integer-expression) |
integer-expression
Is a numeric value in the range 0 through 65535 (decimal).
Note that although the value can be specified to PL/I in decimal, the OpenVMS system always displays UICs in octal format.
See the section on the OWNER_GROUP option for an example of a program
using the OWNER_MEMBER option.
7.2.37 OWNER_PROTECTION Option
The OWNER_PROTECTION option defines the type of access to be permitted to the file by the file's owner and by other users with the same user identification code (UIC). The format of this option is as follows:
OWNER_PROTECTION(character-expression) |
character-expression
Is a 1- to 4-character string expression indicating the access privileges to be granted to the file's owner (and any other users who have the same UIC). The character-string expression can contain any of the following letters to indicate the access allowed:
Letter Meaning R Read access is allowed. W Write access is allowed. E Execute access is allowed. D Delete access is allowed. The lowercase forms of these letters are also permitted. Letters can be repeated, but the maximum length of the string is 4 characters. All other characters are invalid. If any other character is present in the string, the UNDEFINEDFILE condition is signaled.
The PRINTER_FORMAT option specifies that the records in the file contain printing and carriage-control information in the fixed control area. The format of this option is as follows:
PRINTER_FORMAT [ (boolean-expression) ] |
This option indicates that a file is in printer format, that is, the fixed control area of each record contains carriage-control information. Printer file format provides more explicit carriage control than the default type of carriage control, called carriage return format. Printer format is particularly useful in formatting a printed listing.
Note that format items are implemented in the following way:
Table 7-2 summarizes coding specifications for the fixed-length control area for files with printer format. The first byte in the fixed control area is called the prefix byte: it determines the carriage control to be performed before writing the record. The second byte is the postfix byte: it determines the carriage control to be performed after writing the record. The values shown in Table 7-2 have the same meanings in either byte; the bytes are interpreted separately.
| Bit 7 | Bits 0-6 | Meaning | ||
|---|---|---|---|---|
| 0 | 0 | No carriage control is specified, that is, NULL. | ||
| 0 | 1-7F | Bits 0 through 6 are a count of new lines (line feeds followed by carriage return). | ||
| Bit 7 | Bit 6 | Bit 5 | Bits 0-4 | Meaning |
| 1 | 0 | 0 | 0-1F | Output the ASCII control character specified by the configuration of bits 0 through 4 (7-bit character set). |
| 1 | 1 | 0 | 0-1F | Output the ASCII control character specified by the configuration of bits 0 through 4, which are translated as ASCII characters 128 through 159 (8-bit character set). |
| 1 | 1 | 1 | 0-1F | Reserved. |
Example 7-1 illustrates a procedure that uses explicit carriage control. The following notes are keyed to this program:
| Example 7-1 Explicit Carriage Control |
|---|
PRINTER_FORMAT_EXAMPLE: PROCEDURE OPTIONS(MAIN);
/*
* Declare structure definitions for carriage-control bit fields
* and a FIXED BIN(15) variable for the fixed control area
*/ /* (1) */
DECLARE
1 LINE_FEEDS STATIC,
2 COUNT BIT (7), /* Contains count of line feeds */
2 INDICATOR BIT(1) INIT('0'B), /* Must be zero */
1 CARRIAGE_CONTROL STATIC,
2 CODE BIT(5), /* Bits 0-4 ASCII code for action */
2 FILLER BIT(2) INIT('00'b), /* Bits 5 and 6 */
2 EXPLICIT BIT(1) INIT('1'B), /* Bit 7 must be set */
CONTROL_FIELD BIT(16) ALIGNED;
/*
* Set up variables for form feeds and carriage returns
*/
DECLARE
(NEW_LINE,NEW_PAGE) BIT(8); /* (2) */
/*
* Declare PRINTFILE with character-string variable for I/O
*/
DECLARE
PRINTFILE RECORD OUTPUT FILE ENV(
FIXED_CONTROL_SIZE(2), /* (3) */
PRINTER_FORMAT),
PRINTREC CHARACTER(80) VARYING;
/*
* Set up the NEW_PAGE and NEW_LINE variables using the
* CARRIAGE_CONTROL structure as a template.
*/
POSINT(CODE) = 12; /* Assign ASCII code for form feed */
NEW_PAGE = STRING(CARRIAGE_CONTROL);
POSINT(CODE) = 13; /* Assign ASCII code for CR */
NEW_LINE = STRING(CARRIAGE_CONTROL);
OPEN FILE(PRINTFILE);
/*
* Output first line with no carriage control
*/
PRINTREC = 'Output first line with no carriage control'; /* (4) */
WRITE FILE(PRINTFILE) FROM(PRINTREC);
/*
* Prepare to output five line feeds followed by a new line
*/
POSINT(LINE_FEEDS.COUNT) = 5; /* assign 5 to LINE_FEEDS.COUNT */ /* (5) */
CONTROL_FIELD = STRING(LINE_FEEDS) || NEW_LINE;
PRINTREC = 'Record preceded by 5 line feeds ';
WRITE FILE(PRINTFILE) FROM (PRINTREC) OPTIONS(
FIXED_CONTROL_FROM(CONTROL_FIELD));
/*
* Prepare to output a page eject followed by a new line
*/
CONTROL_FIELD = NEW_PAGE || NEW_LINE; /* (6) */
PRINTREC = 'New page';
WRITE FILE(PRINTFILE) FROM(PRINTREC) OPTIONS( /* (7) */
FIXED_CONTROL_FROM(CONTROL_FIELD));
CLOSE FILE(PRINTFILE) ENV(SPOOL); /* (8) */
END PRINTER_FORMAT_EXAMPLE;
|
The READ_AHEAD option requests the overlapping of reading records into buffers with computing operations. This option, used in conjunction with the MULTIBUFFER_COUNT option, can increase the efficiency of I/O operations to disk files. PL/I enables this option by default. The format of this option is as follows:
READ_AHEAD [ (boolean-expression) ] |
When you use the READ_AHEAD option, you can specify the number of buffers to be used in the MULTIBUFFER_COUNT option. When READ_AHEAD is in effect and no multibuffer count is specified, RMS uses two buffers by default.
When READ_AHEAD is enabled, the data transfer and the reading ahead are
transparent to the PL/I program.
7.2.40 READ_CHECK Option
The READ_CHECK option specifies that all input transfers of data between a program and a disk device be followed by a comparison operation to ensure that the data was transferred intact. The format of this option is as follows:
READ_CHECK [ (boolean-expression) ] |
The READ_CHECK option is meaningful when a file is created or opened. An existing file can be opened for input or for update.
This option is useful for applications that must verify all I/O operations to ensure that data was successfully transferred. However, use of this option decreases the speed and efficiency of I/O operations.
If READ_CHECK is specified when a file is created, READ_CHECK is the
default for all subsequent openings of the file, unless explicitly
disabled.
7.2.41 RECORD_ID_ACCESS Option
The RECORD_ID_ACCESS option indicates that the records in a file will be accessed randomly, using the internal identification of the records. The format of this option is as follows:
RECORD_ID_ACCESS [ (boolean-expression) ] |
You must open a file with this option to use the RECORD_ID_TO and RECORD_ID options of the record I/O statements. These options are described in Chapter 8.
When a file is opened with the RECORD_ID_ACCESS option, access by
record identification can be mixed with sequential access or access by
key during this opening. However, a statement cannot specify a record
both by key and by record identification.
7.2.42 RETRIEVAL_POINTERS Option
The RETRIEVAL_POINTERS option specifies the number of extent pointers to be maintained in main memory for file access. Each pointer provides access to a separate extent in the file; increasing the number of pointers for a noncontiguous file can increase the speed with which records are accessed during I/O operations. Its format is as follows:
RETRIEVAL_POINTERS(integer-expression) |
integer-expression
Is a fixed binary expression in the range -1 through 127. A value in the range of 1 through 127 indicates the number of pointers. If you specify -1, the file system maps as much of the file as possible. If the option is not specified, or if the expression has a value of 0, the file system uses the default number established when the volume was initialized or mounted.
The RETRIEVAL_POINTERS option is meaningful when a file is created or opened.
When a disk is initialized, the default window size is set by the /WINDOW qualifier of the DCL command INITIALIZE. You can override this value for the opening of a specific file by specifying the RETRIEVAL_POINTERS option to increase the speed with which records can be accessed.
However, you should avoid specifying a value that is too large. Space
for the pointers is allocated from system space, and a large number of
pointers could have an adverse effect on system performance.
7.2.43 REVISION_DATE Option
The REVISION_DATE option lets you specify a date and time field for the file's revision, allowing you to override the default revision date and time. The format of this option is as follows:
REVISION_DATE (variable-reference) |
variable-reference
Specifies the name of a BIT(64) ALIGNED variable containing an absolute time value in system format. The value specifies the date and time to be used as the file's revision date and time.
The REVISION_DATE option is meaningful only when the file is closed.
You can obtain the time value required by using the Convert ASCII
String to Binary Time system service (SYS$BINTIM).
7.2.44 REWIND_ON_CLOSE Option
The REWIND_ON_CLOSE option specifies, for a file on a magnetic tape volume, that the volume is to be rewound when the file is closed. The format of this option is as follows:
REWIND_ON_CLOSE [ (boolean-expression) ] |
The REWIND_ON_OPEN option specifies, for a file on a magnetic tape volume, that the volume is to be rewound when the file is created or opened. The format of this option is as follows:
REWIND_ON_OPEN [ (boolean-expression) ] |
Magnetic tape file positioning is described in Chapter 6.
| Previous | Next | Contents | Index |