The GUARDFILE utility creates a file of FILEKIND GUARDFILE by translating a source file. For purposes of this discussion, a “source file” is one that contains the untranslated access rules. When you use the GUARDFILE utility, you must supply a source file containing correctly defined access rules.

To create a guard file:

Making a Source File for the GUARDFILE Utility

If you have an existing source file and you want to use it, you can edit it as your new source file. Otherwise, you need to make a source file.

You can prepare the source file with CANDE or some other text editor. The source file must have one of the following FILEKIND values (CANDE types) -- abbreviations appear in parentheses:

The input is scanned from the normal text field of the records (columns 1 through 72 of type SEQ or TEXT, columns 1 through 80 of type JOB or DATA). Source input can also be supplied directly through a REMOTE file (using CANDE) or a READER file (using WFL), in which case 80 columns of input are scanned for each input record. You can also use MARC to supply source input to the GUARDFILE utility.

Defining Access Rights for the Source File

The access right definitions in the source file must be in a format acceptable to the GUARDFILE utility. Some rules to keep in mind when specifying these access rights are

First-Match Rule

The search in the guard file is governed by a first-match rule. When the guard file is examined to determine access to a file it is protecting, the search stops at the first match between the process and the attempted access, and the defined access right listed in the guard file for that process.

Due to the first-match rule, combinations (access rules defined with the USING clause) must be listed first and must be explicitly stated. Consider the following example:

PROGRAM OBJECT/READ/A/FILE = NONE
 USING USERCODE SMITH = READONLY;
USERCODE SMITH = NONE; 

The result of these access rules is to grant program OBJECT/READ/A/FILE read-only access to a file when usercode SMITH runs this program. In addition, any other attempt by usercode SMITH to gain access to the file is denied.

However, if the source records are listed in the reverse order, as in the next example, usercode SMITH is denied access even if the user ran OBJECT/READ/A/FILE.

USERCODE SMITH = NONE;
PROGRAM OBJECT/READ/A/FILE = NONE
 USING USERCODE SMITH = READONLY; 

As another example, consider the following:

PROGRAM OBJECT/READ/OR/WRITE = READONLY
 USING USERCODE SMITH = READWRITE;
USERCODE JONES = NONE
 USING PROGRAM OBJECT/READ/OR/WRITE = WRITEONLY; 

If usercode JONES runs OBJECT/READ/OR/WRITE, the user has read-only access, because application of the first-match rule found the following and stopped:

PROGRAM OBJECT/READ/OR/WRITE = READONLY 

Using MARC to Run the GUARDFILE Utility

Running the GUARDFILE utility in MARC involves completing fields on the MARC Create a Guard File screen. You must have a valid source file before you can use the screen.

To access the screen, transmit GO GUARDFILE from the action line of any MARC screen.

To create your guard file

Using CANDE to Run the GUARDFILE Utility

If the source file for the GUARDFILE utility already exists, you can use it in the CANDE RUN command. If the source file does not exist, you can create one interactively in CANDE.

Creating a Guard File Using an Existing Source File

To create a guard file using an existing source file, initiate the GUARDFILE utility in CANDE with the following form of the RUN command, where <source file title> is the title of your source file and <guard file title> is the desired title of the guard file.

RUN $SYSTEM/GUARDFILE;FILE SOURCE = <source file title>,
GUARD=<guard file title> 

For example, consider the following command:

RUN $SYSTEM/GUARDFILE; FILE SOURCE = SENTRY/PLANNED,
 GUARD = SENTRY 

In response to this command, the utility reads the disk file SENTRY/PLANNED and produces the disk file SENTRY. (SENTRY/PLANNED contains only one access rule, PROGRAM MYUTILITY = RW;.) The default family name DISK is used for both files, subject to substitution by the FAMILY specifications in effect. Assuming that usercode SMITH is being used, the following textual output is sent to the terminal through a remote file:

Guardfile Utility (59.180.0001) at BLUE, 03/13/2017, 08:33:17 
 
Guardfile (SMITH)SENTRY ON USER
          created on 03/13/2017 at 08:33:17
Guardfile version 2.1   Default access = NONE
                            
USING PROGRAM    (SMITH)MYUTILITY  = READWRITEEXECUTE
 

As another example, consider the following command:

RUN $SYSTEM/GUARDFILE; STATION=0; FILE SOURCE=BODYGUARD ON ADMIN 

This example is similar to the previous one, except the specification of STATION=0 notifies the utility not to use the terminal, so the textual output is sent to a line printer file. The printer file includes a transcription of the source file.

If printer and terminal output are required, then the following command is applicable:

RUN $SYSTEM/GUARDFILE; FILE SOURCE=G/IN, GUARD=G/OUT,
 LINE (PRINTER)

The translated source file (the guard file) is shown on both files in the same format (with width appropriate for the terminal).

Creating a Guard File Without an Existing Source File

To create a guard file in CANDE without an existing source file, initiate the GUARDFILE utility in CANDE with

RUN $SYSTEM/GUARDFILE; FILE GUARD = <guard file title>

For example, if your desired guard file title is VIA/MYUTILITY ON ADMIN, use the following command:

RUN $SYSTEM/GUARDFILE; FILE GUARD=VIA/MYUTILITY ON ADMIN 

CANDE responds with “#RUNNING” and “#?” to indicate that a remote file is open for input. You can now define access rights according to the guidelines outlined in “Defining Access Rights for the Source File” earlier in this section . When you finish defining access rights, transmit ?END; the response from CANDE is similar to when a source file was provided.

The following shows a complete series of actions up to the point of transmitting ?END.

RUN $SYSTEM/GUARDFILE;FILE GUARD=VIA/MYUTILITY ON ADMIN
#RUNNING 9320
#?
PROGRAM MYUTILITY = RW;
?END

The translated source file is written to VIA/MYUTILITY on the family ADMIN. Textual output is sent to the terminal.

Using WFL to Run the GUARDFILE Utility

When you run the GUARDFILE utility using WFL, if the source file exists, you can fileequate it in your WFL job. If the source file does not exist, you can define access rights in your WFL job.

Creating a Guard File Using an Existing Source File

Use an existing source file to create a guard file in a WFL job. Initiate the GUARDFILE utility with a job format similar to the following:

100 BEGIN JOB <job name>;
200 RUN SYSTEM/GUARDFILE;
300 FILE SOURCE=<source file title>;
400 FILE GUARD=<guard file title>;
500 END JOB 

The job name is the name of the WFL job; it is optional. The source file title is the title of the source file. The guard file title is the desired title of the guard file. The textual output for this example includes a listing of the source file, which is sent to a printer file.

Creating a Guard File Without an Existing Source File

To create a guard file in a WFL job without using an existing source file, initiate the GUARDFILE utility with a job format similar to the following:

100 BEGIN JOB;
200 RUN SYSTEM/GUARDFILE;
300 FILE GUARD=<guard file title>;
400 DATA
500 PROGRAM <program name> = RW;
600 ?END JOB

The title of the program for which access is defined is <program name>. The guard source is read from card images in the job file, and the textual output (including source listing) goes to the printer.