The input to the GUARDFILE utility describes in detail the rights of any user or program. A percent sign (%) stops the scanning of the source line; the program ignores (treats as commentary) all remaining information on the input record to the right of the percent sign.

Syntax

<guard file input>

  ┌◄────────── , ─────────────┐  ┌◄────────── , ────────────┐
──┴─┬───────────────────────┬─┴──┴────<input request> ; ────┴──────────┤
    ├─<default statement>───┤
    └─<newaccess statement>─┘

<newaccess statement>

───────── SET ────────────── NEWACCESS ────────────────────────────────┤

Explanation

<default statement>

The default statement specifies default values for file access rights and family names, and assigns identifiers to represent “dmverb” definitions. A dmverb is used to specify the data management operations a user or program can exercise for a database. Dmverbs are addressed later in this section.

For more information on the default statement, refer to “Default and Define Specifications” later in this section.

<newaccess statement>

The newaccess statement specifies that the NEWACCESS option is set.

For more information on the newaccess statement, refer to “NEWACCESS Option” later in this section.

<input request>

See “Input Request,” later in this section.

Each input request describes the access rights for one or more usercodes, access codes, or programs. If two input requests can be applied to the same usercode, access code, or program, the first request is used.

Default and Define Specifications

The default statements, if present, must precede any program or usercode input specifications. Dmverb definitions affect only the guarding of databases.

If you do not present an applicable default statement to the GUARDFILE program, the program uses the following default values:

Syntax

<default statement>

  ┌◄─────────────────────────────────────────────────────────────────┐ 
──┴─┬─/1\ ─── DEFAULT ───<file access>────────────────────┬──── ; ───┴───┤
    ├─/1\ ─── PACKNAME ─── = ─<family name>───────────────┤
    └─ DEFINE ───<identifier>─── = ─<dmverb definition>───┘

Explanation

DEFAULT <file access>

The default file access defines access rights for any program or usercode not named in the guard file, as well as for individual entries that are not followed by an explicit access specification for the program name, usercode, or access code list in which they occur. If the operating system examines the guard file and does not find an entry corresponding to the program or usercode attempting to access the guarded file, the file access specified in the default statement is used. The <file access> construct is defined under “File Access” later in this section.

PACKNAME = <family name>

This construct specifies the family name to include in <program name> whenever PROGRAM <program name> appears in the input without an ON <family name> clause.

DEFINE <identifier> = <dmverb definition>

This construct equates an identifier to a dmverb definition. You can use this specification in conjunction with the program or usercode entries that follow it. After a dmverb definition is given once in a default statement, you can use <identifier> to represent those verbs in subsequent dmverb access statements.

<identifier>

The identifier has no intrinsic meaning, but has meaning only by association. An identifier can be any alphanumeric character string beginning with a letter that is not a reserved word in the GUARDFILE program. (Refer to “Reserved Words” later in this section for a list of reserved words used by the GUARDFILE program.)

Input Request

The input request specifies the access rights of users and programs to a file. It can also specify the access rights to the Enterprise Database Server verbs allowed for use on a database for usercodes, programs, access codes, or a combination of these.

Syntax

<input request>

                    ┌◄───────────── , ──────────────┐ 
───<matching rule>──┴─── USING ───<matching rule>───┴──────────────┤

<matching rule>

                   ┌◄───────────── , ──────────────────┐ 
───┬─ CODEFILE ─┬──┴─<program name>─┬────────────────┬─┴─┬─────────┤
   ├─ PROGRAM ──┘                   └─<access spec>──┘   │
   │            ┌◄─────────────── , ─────────────────┐   │
   ├─ USERCODE ─┴─┬─<usercode>──┬─┬────────────────┬─┴───┤
   │              └─ * ─────────┘ └─<access spec>──┘     │
   │              ┌◄─────────────── , ───────────────┐   │
   ├─ ACCESSCODE ─┴─<accesscode>──┬────────────────┬─┴───┤
   │                              └─<access spec>──┘     │
   │             ┌◄─────────────── , ──────────────┐     │
   └─ GROUPCODE ─┴─<groupcode>──┬────────────────┬─┴─────┘
                                └─<access spec>──┘       

<program name>

───<file name>──┬──────────────────────┬───────────────────────────┤
                └─ ON ──<family name>──┘    

<file name>

                            ┌◄── /11\ / ──┐ 
───┬──────────────────────┬─┴───<name>────┴────────────────────────┤
   ├─ ( ──<usercode>── )──┤
   └─ * ──────────────────┘

<access spec>

───┬─<file access>─┬────────────────────────┬──────────────────────┤
   │               └─ , ──<dmverb access>───┤
   └─<dmverb access> ───────────────────────┘

Explanation

<program name>

The program name specifies a program.

The GUARDFILE program prefixes the usercode under which it is executed to any program names that are specified in the input request. You can, however, specify in the input request that another usercode or no usercode is prefixed.

<matching rule>

At run time, the operating system ensures that the name of the program attempting access matches the program name in the guard file before granting access. If the guard file entry specifies CODEFILE matching, the title of the code file associated with the program attempting access must match the title specified in the guard file. If the guard file entry specifies PROGRAM matching, the process name (for example, the NAME task attribute) of the program attempting access must match the program name specified in the guard file. The usercode prefix (or *) of the program or code file attempting access must also match the usercode prefix (or *) of the program in the guard file entry.

For example, suppose the guard file contains the following entry:

PROGRAM *A/B = READONLY; 

When program *A/B is executed under a usercode or under no usercode, it is granted READONLY access to the guarded file. When program (USR)A/B is executed, no access is permitted.

<access spec>

This construct indicates the access allowed for all preceding items in the list, whether bracketed or not, that have no <access spec> of their own.

If you do not supply any <access spec> for names in the list, the DEFAULT values of access rights and dmverbs are used.

If you state an <access spec> for some of the names in the list, the <access spec> stated for the current name being processed applies to all previous names in the list for which no <access spec> is stated. If you state either the <file access> right or the <dmverb access> specification for an item in the name list, that <access spec> is treated as complete for the insertion into previous elements in the name list, and subsequent <access spec>s are not applied to that item.

<usercode>

The usercode can be 1 to 17 characters long, or the asterisk (*) can be used to specify access rights for processes running without usercodes.

<file name>

The file name specifies the name of the file containing the program.

When <usercode> is used with <file name>, it specifies the usercode under which the file resides. An asterisk (*) explicitly indicates an unowned file. If you do not specify an asterisk or usercode, the GUARDFILE utility prefixes the usercode of the user running the utility to <file name>.

When the On <family name> construct is used with <file name>, it specifies the family on which the program or code file resides. The following rules govern family names for both CODEFILE and PROGRAM matching:

<name>

This name can be 1 to 17 alphanumeric characters long.

<file access> <dmverb access>

The <file access> and <dmverb access> access constructs are defined under “File Access” and “Dmverb Access” later in this section. Default dmverb access rights are associated with various file access rights. If you do not specify dmverb access, the default dmverbs associated with the specified file access are applied. Refer to Dmverbs and Their Default Value Lists for the dmverbs associated with various file access rights.

<accesscodes>

The access code can be 1 to 17 alphanumeric characters long.

<group code>

The group code specifies the name of the group of users who all have access to the file.

USING Clause

You can use the USING clause to create combinations of requirements. For example, you can define access in such a way as to require a program to run under a specific usercode before access is granted; assume usercode SMITH and program SCANNER, use the USING clause as follows:

USERCODE SMITH USING PROGRAM SCANNER = EXECUTEONLY; 

The USING clause applies only to the immediately preceding name or bracketed list of names. You might want to group programs and usercodes in file security specifications for a number of reasons. For example:

You can also group programs into classes by function. For example, a group of programs whose sole function is to search a file and provide reports based on current information might be considered “inquiry” programs. Other such program groups might periodically update low-security items within the file, and still others might manipulate restricted information.

File Access

The <file access> construct specifies what actions can be performed on a file. The possible actions are read, write, write-extend, and execute. In the following railroad diagram, the bold characters of the extended form are used to make the abbreviated form (for example, the abbreviated form of EXECUTEONLY is XO):

── = ─┬─ NONE ──────────────┬─────────────────────────────────────┤ 
      ├─ READ ──────────────┤
      ├─ WRITE ─────────────┤
      ├─ EXECUTE ───────────┤
      ├─ READEXECUTE ───────┤
      ├─ WRITEEXECUTE ──────┤
      ├─ READWRITEEXECUTE ──┤
      ├─ EXTEND ────────────┤
      ├─ EXECUTEONLY ───────┤
      ├─ READWRITE ─────────┤
      ├─ READONLY ──────────┤
      ├─ WRITEONLY ─────────┤
      ├─ EXTENDONLY ────────┤
      └─ READEXTEND ────────┘     

Allowed Actions for Specified File Access Rights shows which actions are allowed by each file access right. Abbreviations appear in parentheses.

The possible actions described in Allowed Actions for Specified File Access Rights are defined as follows:

NEWACCESS Option

The NEWACCESS option can be set as part of the initial input to the GUARDFILE utility using the following format:

SET NEWACCESS 

When this option is set

Restrictions for Guarding a Code File

The write and write-extend actions on a code file are allowed only if you are executing a compiler; otherwise, the write and write-extend actions are denied.

Examples of Guarding a File

The following examples illustrate various ways of guarding files to accommodate required functional needs.

Example 1

User A wants user B to help produce the file X. User A owns file X, but wants user B to also have read/write access to the file. User A does not want anyone else to have access to file X, so a guard file named SHARE/WITH/B is created by user A with the following input:

DEFAULT = NONE;          % No access allowed by default.
USERCODE B = READWRITE;  % Full access allowed to user B.

User A then attaches this guard file to the shared file by using the following WFL statement or CANDE SECURITY command:

SECURITY X GUARDED SHARE/WITH/B ON APACK

Example 2

User A owns and maintains an information file for the group of users B, C, and D. Only user A is allowed to change the information in the file, but all users in the group are allowed to read the file. Users C and D are also allowed to execute the file. No one outside the group is allowed access to the file. User A protects this file by creating a guard file with the following input:

DEFAULT = NONE;               % No access allowed by default.
USERCODE B = READ;            % Read access allowed to user B.
USERCODE C, D = READEXECUTE;  % Read and execute access allowed

Example 3

When user E joins the group mentioned in Example 2, user A starts to add user E to the user list in the guard file, but then user A realizes that the guard file would have to change each time the membership of the group changes. To avoid having to change the guard file whenever the group changes, user A persuades the security administrator to add the phrase ACCESSCODE = AGROUP to each group member's usercode entry in the USER DATA FILE.

User A can now make a one-time change to the guard file to allow any user with the ACCESSCODE of AGROUP to read the file. (Note that the membership of the group cannot be changed without the cooperation of the security administrator.) User A recreates the guard file using the following input:

DEFAULT = NONE;                  % No access allowed by default.
ACCESSCODE AGROUP = READ;        % Read access allowed to group.

Example 4

A personnel department might manage employee information by using a master file that is guarded so that access is allowed only through certain programs and only when those programs are run under particular usercodes.

A guard file is created with the following input:

DEFAULT = NONE;          % No access allowed by default.

PROGRAM PERSONNEL/UPDATE % Program for changing personnel data.
        = NONE           % No automatic access via update program.
     USING USERCODE MANAGER, CLERK1, CLERK2
        = READWRITE;     % Full access to manager and clerks.

PROGRAM PERSONNEL/VIEWV  % Program for on-line viewing of data.
        = NONE           % No automatic access via view program.
    USING USERCODE MANAGER, ASSISTANT1, ASSISTANT2
        = READ;          % Read access to manager and assistants.

PROGRAM PERSONNEL/REPORT % Program for hardcopy data reports.
        = NONE           % No automatic access via report program.
    USING USERCODE MANAGER
        = READ;          % Read access to manager only.

Dmverb Access

The <dmverb> construct applies only to Enterprise Database Server databases. It indicates what database operations you can use when accessing an Enterprise Database Server database.

Syntax

<dmverb access>

───── DMVERBS ─── = ────<dmverbs definition>───────────────────────┤

<dmverb definition>

───┬─<define identifer>─┬─┬─────────────────────────────┬──────────────────────┤
   ├─ ALL ──────────────┘ └─ EXCEPT ──<dmverb access>───┤
   └─<dmverb list> ─────────────────────────────────────┘

<dmverb list>

       ┌◄──── , ───────┐ 
─── ( ─┴───<dmverb>────┴─ ) ────────────────────────────────────────────────┤

<dmverb>

──────┬─ ASSIGN ────────────┬─────────────────────────────────────┤ 
      ├─ CLOSELOCK ─────────┤
      ├─ CREATESTORE ───────┤
      ├─ DELETE ────────────┤
      ├─ FIND ──────────────┤
      ├─ GENERATE ──────────┤
      ├─ INSERT ────────────┤
      ├─ LOCK ──────────────┤
      ├─ LOCKSTORE ─────────┤
      ├─ OPENINITIALIZE ────┤
      ├─ OPENINQUIRY ───────┤
      ├─ OPENTEMPORARY ─────┤
      ├─ OPENUPDATE ────────┤
      ├─ REMOVE ────────────┤
      └─ SECURE ────────────┘     

Explanation

<define identifier>

This construct is an identifier that has appeared in a DEFINE statement and represents a dmverb list. Only the dmverbs in that list are permitted. You must declare the <define identifier> in the default statements. (Refer to “Default and Define Specifications” presented earlier in this section for a definition of <identifier>.)

ALL

The ALL attribute specifies all dmverbs.

<dmverb list>

This is the list of permitted dmverbs.

EXCEPT <dmverb list>

The <dmverb list> construct following the word EXCEPT indicates the dmverbs to be removed from the list of dmverbs permitted by <define identifier> or by ALL. You can only apply this clause to a <define identifier> or to the ALL clause.

For a database, you can specify the data management operations allowed for any user or program. Dmverbs and Their Default Value Lists contains the dmverbs that you can specify, along with certain default values associated with dmverb access specifications and the file access rights.

Certain combinations of file access rights and dmverb access specifications are not permitted. For instance, a file access right of READONLY implies that the database can be opened for inquiry only (no modification of the database is permitted); consequently, some verbs (such as STORE and REMOVE) are not permitted. Therefore, if a file access right of READONLY is assigned to an entry, and a dmverb specification that includes verbs not in the standard READONLY verb list (see Dmverbs and Their Default Value Lists) is requested, an error is given. If the file access NONE is specified implicitly or by default, no DMVERB is acceptable. For data management usage, the file access rights EXECUTEONLY, WRITEONLY, EXTENDONLY, and READEXTEND have no meaning and are interpreted as a specification of NONE.

Dmverbs and Their Default Value Lists shows the dmverbs and their respective default value lists.

Examples of Using Dmverbs

User A can use all data management operations:

USERCODE A = READWRITE, DMVERBS = ALL;

User A can open the database only for inquiry. After it is opened, user A can only execute a FIND (no other dmverbs are allowed):

USERCODE A = READONLY, DMVERBS = (OPENINQUIRY, FIND);

A syntax error is given because the file access right NONE does not apply to data management:

USERCODE A = NONE, DMVERBS = (FIND);

A syntax error is given because the DELETE operation is not allowed with the file access right READONLY:

USERCODE A = READONLY, DMVERBS = (DELETE);	

Reserved Words

You cannot use a reserved word as a <define identifier>. The following reserved words are used in the GUARDFILE program: