 |
Guide to OpenVMS File Applications
4.4.2 ACL-Based Protection
You can also protect disk files with access control lists (ACLs). (ACLs
cannot be used with magnetic tape files.)
An ACL is a list of people or groups who are allowed to access a
particular file. ACLs offer more scope than UICs in determining what
action you want taken when someone tries to access your file. You can
provide an ACL on any file to permit as much or as little access as you
want.
You can specify the ACL for a file when you create it if you use RMS
directly. You cannot specify an ACL in an FDL specification, and ACLs
are not supported over DECnet.
After a file is created, you can define the access control list for it
with the ACL Editor. You can invoke this editor with either of the
following DCL commands:
For more information about how to invoke, modify, and display ACLs, see
the OpenVMS System Management Utilities Reference Manual. For additional information about operating system
security features, see your system or security manager, or consult the
documentation related to OpenVMS security.
4.5 Populating a File
The next two sections explain how to use the Convert utility to
populate a file.
4.5.1 Using the Convert Utility
The Convert utility allows you to create and populate a file.
To create a file, you need an input data file and an FDL file that
describes the output file you want to create. You issue a DCL command
in the following form:
CONVERT/CREATE/FDL=fdl-file input-file output-file
|
As with the CREATE/FDL command, the CONVERT/CREATE/FDL command creates
a file named by the output-file parameter and having
characteristics specified in your FDL file. Unlike the CREATE/FDL
command, CONVERT populates the output file with the records from the
input file. For example, to create the file CUST.IDX from the
specifications in the FDL file STDINDEX.FDL and copy the records from
the input file CUST.SEQ into CUST.IDX, you enter the following command:
$ CONVERT/CREATE/FDL=STDINDEX.FDL CUST.SEQ CUST.IDX
|
RMS assigns the characteristics specified in the file STDINDEX.FDL to
the records in CUST.IDX. Note that the Convert utility processes
relative files by sequentially reading records from the input file,
then writing them to the output file. As a result, the relative record
numbers (RRN) change when the input file contains deleted or unused
records.
4.5.2 Using the Convert Routines
You can invoke the functions of the Convert utility from your
application program by calling the following series of convert routines:
|
CONV$PASS_FILES
|
Names the files to be converted. You can also specify an FDL file.
|
|
CONV$PASS_OPTIONS
|
Indicates the CONVERT qualifiers that you want to use. You may specify
any legal CONVERT option, or you may accept the defaults.
|
|
CONV$CONVERT
|
Copies records from one or more source data files to an output data
file. The output file is not required to have the same file
organization and format as the source files.
|
The routines must be called in this order.
Example 4-8 shows how to call the CONVERT routines from a Fortran
program.
| Example 4-8 Using the CONVERT Routines in a
Fortran Program |
* This program calls the routines that perform the
* functions of the Convert utility. It creates an
* indexed output file named CUSTDATA.DAT from the
* specifications in an FDL file named INDEXED.FDL.
* The program then loads CUSTDATA.DAT with records
* from the sequential file SEQ.DAT. No exception
* file is created. This program also returns the
* "BRIEF" CONVERT statistics.
* Program declarations
IMPLICIT INTEGER*4 (A - Z)
* Set up parameter list: number of options, CREATE,
* NOSHARE, FAST_LOAD, MERGE, APPEND, SORT, WORK_FILES,
* KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE,
* NOEXIT, NOFIXED_CONTROL, FILL_BUCKETS, NOREAD_CHECK,
* NOWRITE_CHECK, FDL, and NOEXCEPTION.
*
INTEGER*4 OPTIONS(19),
1 /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/
* Set up statistics list as an array with the
* number of statistics that requested. There are
* four: number of files, number of records, exception
* records, and good records, in that order.
INTEGER*4 STATSBLK(5) /4,0,0,0,0/
* Declare the file names
CHARACTER IN_FILE*7 /'SEQ.DAT'/,
1 OUT_FILE*12 /'CUSTDATA.DAT'/,
1 FDL_FILE*11 /'INDEXED.FDL'/
* Call the routines in their required order.
STATUS = CONV$PASS_FILES (IN_FILE, OUT_FILE, FDL_FILE)
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
STATUS = CONV$PASS_OPTIONS (OPTIONS)
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
STATUS = CONV$CONVERT (STATSBLK)
IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))
* Display the statistics information.
WRITE (6,1000) (STATSBLK(I),I=2,5)
1000 FORMAT (1X,'Number of files processed: ',I5/,
1 1X,'Number of records: ',I5/,
1 1X,'Number of exception records: ',I5/,
1 1X,'Number of valid records: ',I5)
END
|
Example 4-9 shows how to call the CONVERT routines from a COBOL
program.
| Example 4-9 Using the CONVERT Routines in a
COBOL Program |
* CONV.COB
*
* This program calls the routines that perform the
* functions of the Convert utility. It creates an
* indexed output file named CUSTDATA.DAT from the
* specifications in an FDL file named INDEXED.FDL.
* The program then loads CUSTDATA.DAT with records
* from the sequential file SEQ.DAT. No exception
* file is created. This program also returns the
* "BRIEF" CONVERT statistics.
*
* DATA NAMES:
*
* IN-REC defines the input record
* OUT-REC defines the output record
* STATVALUE receives the status value from the
* routine call
* NORMAL receives the value from SS$_NORMAL
* OPTIONS defines the CONVERT parameter list
* STATSBLK receives the CONVERT statistics. The
* first data field (NUM-STATS) contains
* the total number of statistics requested.
* There are four:
* (1) number of files processed (NUM-STATS)
* (2) number of records processed (NUM-FILES)
* (3) number of exception records (NUM-RECS)
* (4) number of valid records (NUM-VALRECS)
*
IDENTIFICATION DIVISION.
PROGRAM-ID. PARTS.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. VAX
OBJECT-COMPUTER. VAX
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT IN-FILE ASSIGN TO SEQ.
SELECT OUT-FILE ASSIGN TO CUSTDATA.
DATA DIVISION.
FILE SECTION.
FD IN-FILE
DATA RECORD IS IN-REC.
01 IN-REC.
02 IN-NUM PIC X(4).
02 IN-NAME PIC X(20).
02 IN-COLOR PIC X(4).
02 IN-WEIGHT PIC X(4).
02 SUPL-NAME PIC X(20).
02 FILLER PIC X(28).
FD OUT-FILE
DATA RECORD IS OUT-REC.
01 OUT-REC.
02 OUT-NUM PIC X(4).
02 OUT-NAME PIC X(20).
02 OUT-COLR PIC X(4).
02 OUT-WGHT PIC X(4).
02 SUPL-NAME PIC X(20).
WORKING-STORAGE SECTION.
01 MORE-DATA-FLAGS PIC X(3) VALUE 'YES'.
88 THERE-IS-DATA VALUE 'YES'.
88 THERE-IS-NO-DATA VALUE 'NO '.
01 STATVALUE PIC S9(9) COMP.
01 OPTIONS USAGE IS COMP.
02 NUM-OPTS PIC S9(9) VALUE 18.
02 CREATE PIC S9(9) VALUE 1.
02 NOSHARE PIC S9(9) VALUE 0.
02 FASTLOAD PIC S9(9) VALUE 1.
02 NOMERGE PIC S9(9) VALUE 0.
02 NOPPEND PIC S9(9) VALUE 0.
02 XSORT PIC S9(9) VALUE 1.
02 XWORKFILES PIC S9(9) VALUE 2.
02 KEYS PIC S9(9) VALUE 0.
02 NOPAD PIC S9(9) VALUE 0.
02 PADCHAR PIC S9(9) VALUE 0.
02 NOTRUNCATE PIC S9(9) VALUE 0.
02 NOEXIT PIC S9(9) VALUE 0.
02 NOFIXEDCTRL PIC S9(9) VALUE 0.
02 NOFILLBUCKETS PIC S9(9) VALUE 0.
02 NOREADCHECK PIC S9(9) VALUE 0.
02 NOWRITECHECK PIC S9(9) VALUE 0.
02 FDL PIC S9(9) VALUE 1.
02 NOEXCEPTION PIC S9(9) VALUE 0.
01 STATSBLK USAGE IS COMP.
02 NUM-STATS PIC S9(9) VALUE 4.
02 NUM-FILES PIC S9(9) VALUE 0.
02 NUM-RECS PIC S9(9) VALUE 0.
02 NUM-EXCS PIC S9(9) VALUE 0.
02 NUM-VALRECS PIC S9(9) VALUE 0.
PROCEDURE DIVISION.
MAIN.
PERFORM CONVERT-FILE THRU DISPLAY-STATS.
OPEN INPUT IN-FILE.
READ IN-FILE
AT END MOVE 'NO ' TO MORE-DATA-FLAGS.
CLOSE IN-FILE.
STOP RUN.
CONVERT-FILE.
CALL 'CONV$PASS_FILES' USING BY DESCRIPTOR 'SEQ.DAT'
BY DESCRIPTOR 'CUSTDATA.DAT'
BY DESCRIPTOR 'INDEXED.FDL'
GIVING STATVALUE.
IF STATVALUE IS FAILURE
CALL 'LIB$STOP' USING BY VALUE STATVALUE.
CALL 'CONV$PASS_OPTIONS' USING BY CONTENT OPTIONS
GIVING STATVALUE.
IF STATVALUE IS FAILURE
CALL 'LIB$STOP' USING BY VALUE STATVALUE.
CALL 'CONV$CONVERT' USING BY REFERENCE STATSBLK
GIVING STATVALUE.
IF STATVALUE IS FAILURE
CALL 'LIB$STOP' USING BY VALUE STATVALUE.
DISPLAY-STATS.
DISPLAY 'Number of files processed: ',NUM-FILES CONVERSION.
DISPLAY 'Number of records: ',NUM-RECS CONVERSION.
DISPLAY 'Number of exception records: ',NUM-EXCS CONVERSION.
DISPLAY 'Number of valid records: ',NUM-VALRECS CONVERSION.
|
For more information about calling the Convert routines, see the
OpenVMS Utility Routines Manual.
4.6 Summary of File-Creation Options
This section summarizes the file-creation options that are available
using RMS. File-creation options may be available as qualifiers or
keywords to the OPEN statement and include various aspects of file
creation, including file disposition, file characteristics, file
allocation, and file positioning.
Note that the run-time options for opening files in conjunction with
creating files are not included here, but they are described in
Chapter 9.
4.6.1 File-Creation Options
The following table lists the creation-time options that apply to
specifying how an application uses a file:
| Name of Option |
Function |
|
Create-if
|
Creates the file only if the directory does not contain a file with the
same name. If a file with the same name exists in the directory, RMS
opens the existing file instead of creating a new file.
- FDL: FILE CREATE_IF
- RMS: FAB$L_FOP FAB$V_CIF
|
|
Maximize version
|
Creates the file with the specified version number or a version number
one greater than a file of the same name in that directory.
- FDL: FILE MAXIMIZE_VERSION
- RMS: FAB$L_FOP FAB$V_MXV
|
|
Supersede version
|
Supersedes the file with the same name, type, and version number in the
current directory.
- FDL: FILE SUPERSEDE
- RMS: FAB$L_FOP FAB$V_SUP
|
|
Temporary
|
Creates a temporary file (which has no directory entry) that is
retained when the file is closed. The file can be accessed only if its
internal file identifier is known (requires the use of a name block).
Name blocks provide additional fields for extended file specifications.
- FDL: FILE DIRECTORY_ENTRY
- RMS: FAB$L_FOP FAB$V_TMP
|
|
Temporary, delete
|
Creates a temporary file (which has no directory entry) marked for
deletion. The file is deleted automatically when the file is closed.
- FDL: FILE TEMPORARY
- RMS: FAB$L_FOP FAB$V_TMD
|
4.6.2 File Characteristics
The creation-time options that define file characteristics are
described in the following chart:
| Name of Option |
Function |
|
Block size
|
Defines the number of bytes to be used in each block (unit of I/O)
throughout the life of this file. This file characteristic applies only
to magnetic tape files.
- FDL: FILE MT_BLOCK_SIZE
- RMS: FAB$W_BLS
|
|
Bucket size
|
Defines the number of blocks to be used in each bucket (unit of I/O)
throughout the life of this file. This file characteristic applies only
to relative and indexed files.
- FDL: FILE BUCKET_SIZE
- RMS: FAB$B_BKS or XAB$B_BKZ
|
|
Date information
|
Specifies the date and time values for file backup, file creation, file
expiration, and file revision. Can also set the number of file
revisions.
- FDL: DATE attributes and
FILE REVISION
- RMS: Date and Time XAB fields
|
|
File organization
|
Defines the file organization: sequential, relative, or indexed.
- FDL: FILE ORGANIZATION
- RMS: FAB$B_ORG
|
|
File protection
|
Defines the file protection for the file being created.
- FDL: FILE OWNER,
FILE PROTECTION,
FILE MT_PROTECTION
- RMS: Protection XAB fields
|
|
Fixed-length control field size
|
Defines the number of bytes in the fixed-length control field of a VFC
record.
- FDL: FILE CONTROL_FIELD_SIZE
- RMS: FAB$B_FSZ
|
|
Key characteristics
|
Defines the characteristics of a key in an indexed file, including key
size, starting position, key type, bucket fill size, and key options.
- FDL: KEY attributes
- RMS: Key Definition XAB fields
|
|
Maximum record number
|
Defines the maximum number of records for the file. Applies only to
relative files.
- FDL: FILE MAX_RECORD_NUMBER
- RMS: FAB$L_MRN
|
|
Maximum record size
|
Defines the maximum record size for all records in the file. Maximum
record size refers to the size of all records in a file with
fixed-length records, the size of the largest record with
variable-length records, or the size of the variable-length portion of
VFC records. A value of 0 with variable-length records means that there
is no limit on the record size, except for magnetic tape files, for
which a value of 0 sets an effective maximum record size equal to the
block size minus 4. Variable-length records and VFC records must
conform to certain physical limitations (see the OpenVMS Record Management Services Reference Manual).
- FDL: RECORD SIZE
- RMS: FAB$L_MRS
|
|
Record attributes
|
Defines the following control information for each record:
- Records can use one of the following carriage control conventions:
- Each record is preceded by a line feed and terminated by a carriage
return (FDL attribute RECORD CARRIAGE_RETURN). This is the default.
- Each record contains a Fortran carriage return (FDL attribute
RECORD FORTRAN).
- Each record is in print format where the two-byte fixed-length
control field (VFC record format) of each record contains the carriage
return information (FDL attribute RECORD PRINT).
- No carriage control provided (FDL attribute RECORD NONE).
- Records can be prevented from crossing block boundaries (FDL
attribute RECORD BLOCK_SPAN).
- For variable-length records, the byte count field may be formatted
in LSB (least-significant-byte) format (default) or in MSB
(most-significant-byte) format (FDL attribute RECORD MSB_RECORD_LENGTH).
- FDL: RECORD BLOCK_SPAN, RECORD MSB_RECORD_LENGTH
- RMS: FAB$B_RAT
|
|
Record format
|
Defines the record format:
- Fixed-length record format
- Variable-length record format
- VFC record format
- Stream record format
- Undefined record format (sequential files only)
- FDL: RECORD FORMAT
- RMS: FAB$B_RFM
|
4.6.3 File Allocation and Positioning
You can specify file-allocation and positioning options with either the
FAB control block or an allocation XAB (XABALL) control block. Note
that any value specified in the XABALL control block overrides the
corresponding value in the FAB. The creation-time options described in
the following table apply to file allocation and positioning:
| Name of Option |
Function |
|
Allocation quantity
|
Allocates the file or area using the number of blocks specified by this
value, rounded up to the nearest even multiple of the volume's cluster
size.
- FDL: FILE ALLOCATION or
AREA ALLOCATION
- RMS: FAB$L_ALQ or
XAB$L_ALQ
|
|
Areas
|
Allocates the file using single or multiple areas. Applies only to
indexed files; sequential and relative files are always contained in a
single area. Indexed files can be placed in specific areas, for
example, to separate the data area from the index area.
- FDL: AREA number
- RMS: XAB$B_AID
|
|
Contiguous
|
Allocates the file or area using a single extent. If the disk's
unallocated space does not permit the file to be allocated
contiguously, an error is returned.
- FDL: FILE CONTIGUOUS or
AREA CONTIGUOUS
- RMS: FAB$L_FOP FAB$V_CTG or
XAB$L_AOP XAB$V_CTG
|
|
Contiguous best try
|
Attempts to allocate the file or area using a minimum number of
extents. If the file cannot be allocated contiguously, an error is not
returned.
- FDL: FILE BEST_TRY_CONTIGUOUS or
AREA BEST_TRY_CONTIGUOUS
- RMS: FAB$L_FOP FAB$V_CBT or
XAB$L_AOP XAB$V_CBT
|
|
Cylinder boundary
|
Allocates the file or area at the beginning of a cylinder boundary.
- FDL: AREA POSITION
ANY_CYLINDER
- RMS: XAB$B_AOP XAB$V_ONC
|
|
Cylinder position
|
Positions the file or area at the beginning of the specified cylinder
number.
- FDL: AREA POSITION CYLINDER
- RMS: XAB$B_ALN XAB$V_CYL and
XAB$L_LOC
|
|
Default extension
|
Defines the minimum number of blocks for a file extension (extent) when
additional disk space is needed. For the Edit/FDL utility file
extension sizes, see Appendix A.
- FDL: FILE EXTENSION
- RMS: FAB$W_DEQ or
XAB$W_DEQ
|
|
Hard positioning
|
Directs OpenVMS RMS to return an error if the requested file or area
positioning or alignment cannot be performed.
- FDL: AREA EXACT_POSITIONING
- RMS: XAB$B_AOP XAB$V_HRD
|
Logical block
position
|
Positions the file or area at the beginning of the specified logical
block.
- FDL: AREA POSITION LOGICAL
- RMS: XAB$B_ALN XAB$V_LBN and
XAB$L_LOC
|
Related file
position
|
Positions the file or area as close as possible to a related file, at
the specified virtual block.
- FDL: AREA POSITION FILE_ID or
AREA POSITON FILE_NAME
- RMS: XAB$B_ALN XAB$V_RFI and
XAB$L_LOC
|
Virtual block
position
|
Positions the file or area at the beginning of the specified virtual
block.
- FDL: AREA POSITION VIRTUAL
- RMS: XAB$B_ALN XAB$V_VBN and
XAB$L_LOC
|
|
Truncate end of file
|
Truncates a nonshared sequential file at its logical end to release the
space between the logical end of the file (end of file data) and the
physical end of the file (allocated file space) for other use.
- FDL: FILE_TRUNCATE_ON_CLOSE
- RMS: FAB$V_TEF
|
|
Volume number
|
Indicates the volume set where the file or area is placed when it is
created.
- FDL: AREA VOLUME
- RMS: XAB$W_VOL
|
For the list of the run-time options that are common to creating and
opening a file, see Chapter 9.
For more information about the options listed above, see Chapter 2.
For more detailed information about the programming aspects of these
options, refer to the OpenVMS Record Management Services Reference Manual.
|
