[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

Guide to OpenVMS File Applications


Previous Contents Index

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:

  • EDIT/ACL
  • SET FILE/ACL

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.


Previous Next Contents Index