| Previous | Contents | Index |
The SCALARVARYING option specifies that character strings with the VARYING attribute be read and written in strict accordance with the PL/I ANSI standard. Its format is as follows:
SCALARVARYING [ (boolean-expression) ] |
The SCALARVARYING option has the following effect on I/O operations involving VARYING character-string variables:
Thus, records to be read into or from variables with the VARYING attribute should be images of a varying character string-including the 2-byte count field at the beginning of the string.
When SCALARVARYING is not specified, character-string variables with the VARYING attribute are handled so as to facilitate reading and writing files with variable-length records. The rules are as follows:
For strings with the VARYING attribute that are embedded in arrays or structures, the entire storage is always read or written.
When a file is to be read with SCALARVARYING in effect, the target variable must be declared CHARACTER VARYING, and the length of the target variable must match the record length of each record in the file, minus two bytes. If the length does not match, the ERROR condition is signaled.
The following example illustrates reading a file with the SCALARVARYING option (presumably the file was created with the SCALARVARYING option in effect):
DECLARE EOF BIT(1) ALIGNED INITIAL('0'B);
DECLARE STRING CHARACTER(80) VARYING,
INFILE FILE RECORD INPUT;
OPEN FILE(INFILE) ENVIRONMENT(SCALARVARYING);
ON ENDFILE(INFILE) EOF = '1'B;
READ FILE(INFILE) INTO(STRING);
DO WHILE (^EOF);
PUT SKIP LIST(LENGTH(STRING),STRING);
READ FILE(INFILE) INTO(STRING);
END;
|
The file defined as INFILE must have 82-byte records: the first two
bytes of each record must contain the length of the data within the
record. This READ statement reads 82 bytes, and uses the first two as
the length and contents of each string.
7.2.47 SHARED_READ Option
The SHARED_READ option specifies that other users who have concurrent access to the file can read records in it. The format of this option is as follows:
SHARED_READ [ (boolean-expression) ] |
By default, the SHARED_READ option is disabled when a file is opened
for output or update; that is, sharing is not allowed by default if
anyone is writing to the file. SHARED_READ is enabled when a file is
opened for input, that is, sharing is allowed if no one is writing to
the file.
7.2.48 SHARED_WRITE Option
The SHARED_WRITE option specifies that other users who have concurrent access to the file can write, update, and delete records in the file. The format of this option is as follows:
SHARED_WRITE [ (boolean-expression) ] |
By default, the SHARED_WRITE option is disabled.
7.2.49 SPOOL Option
The SPOOL option requests that the file be submitted to the system printer job queue when it is closed. The format of this option is as follows:
SPOOL [ (boolean-expression) ] |
If you specify the DELETE option in conjunction with the SPOOL option, the file is submitted to the queue SYS$PRINT when it is closed and marked to be deleted after printing.
You can control the queue to which the file is submitted by using the DEFINE command to equate the logical name SYS$PRINT with the name of a specific queue before running the program. For example:
$ DEFINE SYS$PRINT LPC0: $ RUN PRINTER |
If the PL/I program PRINTER closes a file with the SPOOL option, the
file is queued to LPC0: (the printer device).
7.2.50 SUPERSEDE Option
The SUPERSEDE option specifies that if a file already exists with the same name, type, and version number as the file specified, the existing file should be replaced. The format of this option is as follows:
SUPERSEDE [ (boolean-expression) ] |
By default, the file system creates a new file and assigns it a new version number whenever a file is opened for output. Consequently, if a file specification does not include a version number, many versions of a file may be created. If the file's TITLE option or DEFAULT_FILE_NAME option specifies an explicit version number, the ERROR condition is signaled if a file with that version number already exists.
In some cases, you may want to specify an explicit version number to
ensure that a single version of a specific file be maintained. In these
cases, specify the SUPERSEDE option in conjunction with a TITLE value
or DEFAULT_FILE_NAME value to ensure that multiple versions of the file
are not created.
7.2.51 SYSTEM_PROTECTION Option
The SYSTEM_PROTECTION option defines the type of access to be permitted to the file by users with system user identification codes (UICs). The format of this option is as follows:
SYSTEM_PROTECTION(character-expression) |
character-expression
Is a 1- to 4-character string expression indicating the access privileges to be granted to users with system UICs or with the SYSPRV user privilege. 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 TEMPORARY option creates a temporary file with no directory entry. The format of this option is as follows:
TEMPORARY [ (boolean-expression) ] |
When you create a file with the TEMPORARY option, the file system does not create a directory entry for the file. A file thus created can be used during the execution of the program and deleted on completion, without the overhead required to create and remove the directory entry.
The file can be deleted when it is closed or, if needed later, can be deleted after it has been reused. You specify deletion by using the DELETE option when you open, reopen, or close the file.
However, because no directory entry is created for a temporary file, the file can be reaccessed only by its internal file identification. You can obtain this identification by specifying the FILE_ID_TO option when the file is created. For example:
DECLARE WORKFILE FILE OUTPUT SEQUENTIAL,
WORKFILE_ID (6) FIXED BINARY;
OPEN FILE(WORKFILE) ENVIRONMENT (TEMPORARY,
FILE_ID_TO(WORKFILE_ID));
.
.
.
CLOSE FILE(WORKFILE);
.
.
.
OPEN FILE (WORKFILE) ENVIRONMENT (
FILE_ID(WORKFILE_ID),
DELETE);
|
These statements declare the file WORKFILE, open it with the FILE_ID_TO option, close it, and later reopen it, using the FILE_ID option and specifying the file identification obtained when the file was first opened. The second OPEN statement also specifies the DELETE option of ENVIRONMENT, so that the file is deleted when it is subsequently closed.
Note that the FILE_ID and the FILE_ID_TO options, which are necessary for reaccessing a temporary file, cannot be used across the DECnet.
The TEMPORARY option is also useful in conjunction with the BATCH or SPOOL options. For example, if you create a file that is to be printed but that can be deleted after printing, you can specify it as follows:
DECLARE PRINTFILE FILE PRINT ENVIRONMENT (
SPOOL, TEMPORARY, DELETE);
|
When this file is closed, it is automatically queued for printing. Once
it is printed, it is deleted.
7.2.53 TRUNCATE Option
The TRUNCATE option specifies that any unused space allocated for a file be deallocated when the file is closed. The file is truncated to its logical end-of-file. The format of this option is as follows:
TRUNCATE [ (boolean-expression) ] |
You can specify this option to conserve disk space. If a file's
allocation is greater than its contents require, and if the file is not
expected to increase in size, you may want to use this option to
reclaim the allocated, but unused, space.
7.2.54 USER_OPEN Option
The USER_OPEN option allows you to access RMS facilities not explicitly available in PL/I by writing a function that controls the opening of the file. Specifying the USER_OPEN option causes the run-time library to call your function to open the file instead of calling RMS to open it according to its normal defaults. The format of this option is as follows:
USER_OPEN (entry-name) |
entry-name
An entry variable or entry constant.
When the OPEN statement is executed, the run-time library sets up the RMS file access block (FAB) and the record access block (RAB), as well as its own internal data structures. These blocks transmit requests for file and record operations to RMS; they also return the data contents of files, information about file characteristics, and status codes. For more information on the RAB and the FAB, see the OpenVMS Record Management Services Reference Manual.
In order, the three parameters passed to the user-open function by the run-time library are as follows:
Your user-open function may have to be changed when new run-time libraries are released. |
The following example shows a PL/I program that creates a file 1000 blocks long.
/*
* This program allocates 1000 blocks to the file new.tmp.
*/
OPEN_TEST: PROC OPTIONS(MAIN);
DCL F FILE OUTPUT;
OPEN FILE(F) ENVIRONMENT(USER_OPEN(MY_OPEN)) TITLE('NEW.TMP');
RETURN;
/*
* This function sets the appropriate bit in the FAB to allocate
* 1000 blocks for the file.
*/
MY_OPEN:PROC(FAB,RAB,OPEN_FLAG) RETURNS(FIXED BIN);
%INCLUDE $FABDEF;
%INCLUDE $RABDEF;
DCL 1 FAB LIKE FABDEF;
DCL 1 RAB LIKE RABDEF;
DCL OPEN_FLAG FIXED BIN;
DCL STATUS FIXED BIN;
%INCLUDE SYS$OPEN;
%INCLUDE SYS$CREATE;
/*
* Store the allocation quantity.
*/
FAB.FAB$L_ALQ = 1000;
/*
* Call sys$open or sys$create and return its status to the Run-Time
* Library.
*/
IF OPEN_FLAG = 1 THEN
STATUS = SYS$OPEN(FAB,,);
ELSE
STATUS = SYS$CREATE(FAB,,,);
RETURN(STATUS);
END MY_OPEN;
END OPEN_TEST;
|
The WORLD_PROTECTION option defines the type of access to be permitted to the file by users who are not in the owner's group and who do not have system user identification codes. The format of this option is as follows:
WORLD_PROTECTION(character-expression) |
character-expression
Is a 1- to 4-character string expression indicating the access privileges to be granted to users in the world category. 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 four characters. All other characters are invalid. If any other character is present in the string, the UNDEFINEDFILE condition is signaled.
The WRITE_BEHIND option requests the file system to overlap the writing of buffers with computing operations. The format of this option is as follows:
WRITE_BEHIND [ (boolean-expression) ] |
When you use the WRITE_BEHIND option, you can specify the number of buffers to be used in the MULTIBUFFER_COUNT option. If you specify WRITE_BEHIND and do not specify a multibuffer count, RMS uses two buffers by default.
When the WRITE_BEHIND option is in effect, there is no way for the
program to determine when a buffer has been written to disk. To ensure
the integrity of a file that is being processed with the WRITE_BEHIND
option, you can use the FLUSH built-in subroutine to periodically write
all buffers back to disk. The FLUSH built-in subroutine is described in
Chapter 9.
7.2.57 WRITE_CHECK Option
The WRITE_CHECK option specifies that all write transfers of data between a program and a disk device be followed by a compare operation to ensure that the data was transferred intact. The format of this option is as follows:
WRITE_CHECK [ (boolean-expression) ] |
The WRITE_CHECK option is meaningful when a file is created or opened. An existing file can be opened either for update or for output with the APPEND option.
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 WRITE_CHECK is specified when a file is created, WRITE_CHECK is the
default for all subsequent openings of the file, unless explicitly
disabled.
7.3 ENVIRONMENT Options for File Protection and File Sharing
This section discusses the ENVIRONMENT options that take advantage of
special RMS processing options for file protection and file sharing.
7.3.1 File Protection
Each user who is authorized to use the system is assigned a user identification code (UIC) by the system manager. When a PL/I program creates a file, the current UIC associated with the process executing the program defines the file's ownership.
Based on this UIC, called the owner UIC, the file system defines the protection of the file in terms of which other users on the system can access the file and what operations they can perform on the file. The other users in the system are defined as follows:
The types of access privileges defined for a file are as follows:
You can explicitly control the protection applied to a file in two ways:
In a PL/I program, you can specify a file's ownership and protection
when you create the file.
7.3.1.1 Defining a File's Ownership
When you specify the ENVIRONMENT attribute for a file you are creating in a PL/I program, you can specify the following options to define the owner of the file, overriding the default:
These options specify the member number and group number of the owner of the file. Specify values for these options using fixed binary expressions. For example:
ENVIRONMENT (OWNER_GROUP (240),
OWNER_MEMBER (5))
|
This example defines the owner of the file as any process that has the UIC [360,5]. Note that although the value can be specified to PL/I in decimal radix, the OpenVMS system always displays and interprets UICs in octal radix.
To specify an owner UIC for a file that is different from the UIC under which the current program is executing, the process must have the SYSPRV user privilege or a system UIC.
| Previous | Next | Contents | Index |