HP 3000 Manuals

File Directory Structure [ Getting Started as an MPE/iX Programmer Programmer's Guide ] MPE/iX 5.0 Documentation

Getting Started as an MPE/iX Programmer Programmer's Guide

File Directory Structure

File directory structure is based on several file characteristics that
determine how the file is classified and how it is handled during file
manipulation operations. These characteristics are discussed in the
following subsections.

Domains

Files can be classified on the basis of domain. The domain of a file
determines if it is permanent, is temporary (lasts only for the duration
of the job or session), or exists only for one particular process.

The File System maintains separate directories to record the location of
PERMANENT and TEMP files. PERMANENT files are recorded in the System
File Directory; and TEMP files, in the Job Temporary File Directory. A
permanent or temporary file can be opened or closed with a file domain of
OLD (although you cannot create a file with an OLD domain by using the
MPE/iX command :BUILD).

This designation differs from PERMANENT only in the fact that first the
Job Temporary File Directory and then the System Permanent File Directory
are searched for the filename. OLD files are described in the "Closing a
File" subsection. There is no File System directory for files that exist
only to their creating process (NEW files).

The subsections below define domains and describe how to change, list,
and search for the domain of a file and how to open and close files with
various domains. Table 6-1 summarizes the features of NEW, TEMP, and
PERMANENT files.

Table 6-1. New, Temporary, and Permanent File Features

In some cases, the domain you specify for a file may be restricted by the
type of device on which the file resides. The domains permitted are
summarized in Table 6-2 .

Table 6-2. Valid File Domains

---------------------------------------------------------------------------------------------
| | |
| Device Type | Valid Domains (see note below table) |
| | |
---------------------------------------------------------------------------------------------
| | |
| | |
| Disc | NEW, TEMPORARY, PERMANENT, or OLD |
| | |
- -
| | |
| Magnetic tape device | NEW, PERMANENT, or OLD |
| | |
- -
| | |
| Terminal | NEW, PERMANENT, or OLD |
| | |
- -
| | |
| Line printer | NEW |
| | |
- -
| | |
| Plotter | NEW |
| | |
- - -
---------------------------------------------------------------------------------------------

NOTE When you specify a file domain using HPFOPEN, you should open only
disc files with the domain option set to NEW. Device files can be
opened with the domain option set to NEW (to maintain compatibility
with MPE V/E), but a warning is returned in the status parameter.

NEW Files.

When you create a file, you can indicate to the File System that it is a
NEW file; it did not previously exist. Space for this file has not yet
been allocated. As a NEW file, only the program that creates it knows
about it, and it exists only while the program is executing. When the
program concludes, the file vanishes, unless you take action to retain
it.

TEMP Files.

A TEMP file is one that already exists, but only the job or session that
created it knows about it. Some or all of the space for the file has
been allocated, and its physical characteristics have been defined. A
file in this domain is a job temporary file; it has been created for a
specific purpose by its job or session. It may not be needed after the
job or session ends. When the job or session concludes, the file
automatically disappears, unless you take action to change it to a
PERMANENT file. This is described in the "Changing Domains" subsection,
below.

PERMANENT Files.

A PERMANENT file exists as a permanent file in the File System. Its
existence is not limited to the duration of its creating job or session.
Any job or session can access the file when security restrictions allow.
Some or all of the space for the file has been allocated, and its
physical characteristics have been defined. When the job or session
concludes, the file remains.

Effect of File Domain on Operations.

You can select or change the domain disposition of a file when you close
the file using the FCLOSE intrinsic. This is called the closing
disposition of the file and follows these rules:

* Any file can be deleted when closed. This is the default for a
NEW file.

* A NEW file can be changed to a TEMP file when closed.

* A NEW or TEMP file can be changed to PERMANENT when closed.

* A PERMANENT file can be changed to a TEMP when closed by a PM
(privileged mode) user.

The File System action defaults to delete a NEW file, temporarily keep a
TEMP file, and save a PERMANENT file. The way in which subsystems use
files affects these defaults. You can specify a closing disposition with
a :FILE command that overrides how the program or subsystem closes the
file. Other commands such as :PURGE, :BUILD, and :SAVE provide various
mechanisms for changing file domain. For detailed information on these
commands, refer to the MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364).

The FCLOSE intrinsic is called for every file on which an HPFOPEN or
FOPEN has been performed. The File System ensures that an opened file is
automatically closed at program termination, without requiring an
explicit statement. However, a subsystem must explicitly call FCLOSE to
ensure that the action taken will be as specified in your program.

Determining file disposition at close time can have consequences on
running programs (especially in batch mode). For example, a program can
open a NEW file by default, write data to the file, and attempt to save
the file as OLD. A directory error (for example, a duplicate file name)
can be detected only at close time; and data is lost, unless you have
used one of the following methods to check for or avoid the situation:

* Create a NEW file by using BUILD before executing the program in
which the file is opened as an OLD file.

* Delete the previous copy of the file before the run.

* Rename the existing file by using FRENAME.

The File System closes files when it terminates a program, without
requiring the program to explicitly close them. This allows no recourse
for accidentally losing data. It is a recommended programming practice,
when the content of a file is important, to write the program to properly
handle closing disposition.

The CREATE domain of HPFOPEN creates a NEW file and makes it PERMANENT
when closed. It eliminates the need to HPFOPEN or FOPEN it as a NEW
file, HPFCLOSE or FCLOSE it as a PERMANENT file, and open it with HPFOPEN
or FOPEN again as an OLD file.

Changing Domains.

A file's domain can be changed. Any disc file can be made permanent or
can be deleted after it has served its purpose. You can use the
disposition parameter of the FCLOSE intrinsic to specify a different
domain for a file as it closes. You can use the :FILE command to change
the domain of a file; specifying the DEL, TEMP, or SAVE parameter
determines the disposition of a file when it is closed after its next
use. The DEL parameter deletes a file after its next use. The TEMP
parameter changes the domain of a NEW file to TEMP when it is closed.
The SAVE parameter changes the domain of a NEW or TEMP file to PERMANENT
when it is closed.

You can change the domain of a file from TEMP to PERMANENT without
opening and closing the file by using the :SAVE command. This command
prompts you for the lockword if the file has one.

For examples of changing domains, refer to Accessing Files Programmer's
Guide (32650-90017). For detailed information on the :FILE and :SAVE
commands, refer to the MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364).

File Specifications

File specifications allow you to identify a file. This is necessary in
order to:

* Locate it in the directory structure

* Refer to it from a command or program

* Determine how to handle it during file manipulations such as
opening and closing

* Transfer it during I/O

The File System uses several designations and classifications to
facilitate file identification. The use of file designators and classes
allows the File System to recognize a file so that commands and programs
can reference it. MPE/iX allows you to designate a name for a file in
several ways. Techniques for file identification are described in the
subsections below.

File Designators

A file designator is a name used by the File System to reference a file
with great flexibility. It allows you to equate a name other than the
file name used in the standard file reference format, described below.

The two types of MPE/iX file designators are:

* Formal file designator

* Actual file designator

A formal file designator is the name by which a program recognizes a
file. It is specified programmatically or in a file equation and is not
the file name found in the file list of a directory. It is the file name
coded into the program, along with the program's specifications for the
file. The :FILE command refers to a file by its formal file designator.
A formal file designator is frequently called a user file name.

An actual file designator is a file name provided by the user for the
File System to use in place of the formal file designator to accomplish a
task. In many cases, the formal file designator and the actual file
designator are the same. The actual file designator is the file name
given in the file list of a directory. It is described in the standard
file reference format:

filename[/lockword][.groupname][.accountname]

To read from an input file, a program requires that a name for the file
must be specified in the program. However, it is desirable to allow a
user at run time to provide a file of any name to be used for this
purpose. This is accomplished by using file designators to associate the
file name the user provides with the file name the program expects.
Programmers can use an arbitrary name as a formal file designator and
equate it to an appropriate actual file designator at run time, a
technique facilitating maximum file reference flexibility. When used in
this way, the formal file designator contains one to eight alphanumeric
characters, beginning with a letter.

NOTE HPFOPEN option (Item #38), the file privilege option, when used
to set a NEW file's privilege level to other than three
(least-privileged, of user level), disallows all subsequent access
to that file by the FOPEN intrinsic. (For compatibility reasons,
FOPEN can access only a file whose file privilege level is three.)

The formal file designator is the name passed to the HPFOPEN or FOPEN
intrinsic and used when HPFOPEN or FOPEN looks for a file equation for
that file. When users invoke a :FILE command, they can specify a file
name to equate to the formal file designator. This file name is the
actual file designator. At run time, the program will find the actual
file designator associated with the formal file designator and open the
user-specified file. Figure 6-4 shows an example of using file
designators. In this example, the file directory on disc shows an actual
file designator PAYROLL5 and the REPORT program contains a formal file
designator named PAYROLLX. At run time, a user can use the :FILE command
to create a file equation associating the name PAYROLLX with the name
PAYROLL5. When the user runs the REPORT program, it uses the content of
the PAYROLL5 file wherever it performs an operation on PAYROLLX.

Figure 6-4. Identifying a Disc File using File Designators

Backreferencing a File.

You can invoke a :FILE command that refers to a previously invoked :FILE
command using a technique called "backreferencing." Once you establish a
set of specifications in a :FILE command, you can apply them to other
file references in your job or session by using the formal file
designator, preceded by an asterisk (*). For example, if you have
defined a file named MYFILE in a :FILE command, you can later refer to
all the same specifications by stating *MYFILE. This is useful when you
want to be sure the file specifications for a file used by one program
match those already set up for a file in another program. It also saves
supplying the same parameters over again.

Whenever you reference a predefined file in a File System command, you
must enter the asterisk before the formal file designator if you want the
predefinition to apply.

Figure 6-5 shows an example of back referencing. In this example, a
:FILE command equates the formal file designator EMPLOYEE in the PERSONEL
program with the actual file designator MASTER. At run time, the program
opens a file named MASTER where it specifies EMPLOYEE. If you wanted to
run a different program, named FINANCE, with the file MASTER, back
referencing allows access to it without requiring that you repeat all the
parameters that were specified in the first :FILE command. The :FILE
command for the FINANCE program simply back references the actual file
designator given in the previous :FILE command by specifying the string
*EMPLOYEE. This allows access to the MASTER file with all the same
attributes specified in the first :FILE command.

Figure 6-5. Backreferencing a Previously Identified File

For detailed information, refer to Accessing Files Programmer's Guide
(32650-90017).

File Classes.

The File System recognizes two general classes of files:

* User-defined files, which users define, create, and make available
for their own purposes.

* System-defined files, which the File System defines and makes
available to all users. For example, they are used to indicate
standard input/output devices.

The file classes are distinguished by the file names and other
descriptors (such as group or account name) that refer to them. You can
use a file name and descriptors, in combination, as either:

* A formal file designator in a program or file equation

* An actual file designator that identifies the file to the File
System

User-defined Files

You can reference any user-defined file by writing its name and
descriptors in the standard file reference format, as follows:

filename[/lockword][.groupname][.accountname]

The maximum size of a file designator written in this format is 35
characters, including delimiters.

When you reference a file that belongs to your logon account and group,
you can use the simplest form of the standard file reference format; the
user or system file name. Specify both the actual and formal file
designators in the standard file reference format.

The file name is from 1 to 8 alphanumeric characters, beginning with a
letter (unless the file has a lockword, in which case you must specify
the lockword and a delimiter). In the following examples, both formal
and actual file designators appear in this format:

:FILE ALPHA=BETA
:FILE REPORT=OUTPUT
:FILE X=AL126797
:FILE PAYROLL=SELFL

A file name must be unique in its group. A reference to a file is always
qualified by adding to the file name the name of the group and account in
which the file resides. For example, if you create a file named FILX
under GROUPA and ACCOUNT1, the system will recognize your file as
FILX.GROUPA.ACCOUNT1. A file with the same file name created under a

GROUPB is recognized as FILX.GROUPB.ACCOUNT1. Thus, you need only to
ensure that a file name is unique in its group.

Groups serve as the basis for your local file references. When you log
on, if the default File System file security provisions are in effect,
you have unlimited access to all files assigned to your logon group and
your home group. You are permitted to read and execute programs residing
in the public group of your log on account. This group, always named
PUB, is automatically created under every account to serve as a common
file base for all users of the account. You can also read and execute
programs residing in the PUB group of the System Account. This special
account, always named SYS, is available to all users on every system.

You can refer to files that belong to different logon accounts and groups
by specifying qualifying information in the optional parameters of the
standard file reference format. For detailed information, refer to
Accessing Files Programmer's Guide (32650-90017).

If you do not supply explicit group and account name information in a
standard file reference format, MPE/iX supplies the defaults of the group
and account in which you are currently logged on.

When you create a disc file, you can assign to it a lockword. It must
later be supplied in the standard file reference format to access the
file in any way. The lockword is independent of, and serves in addition
to, the other File System security provisions governing the file.

You assign a lockword to a new file by specifying it in the filereference
parameter of the :BUILD command or in the formalreference parameter of
the HPFOPEN or FOPEN intrinsic used to create the file.

For detailed information on using lockwords and supplying lockwords in
jobs and sessions, refer to Accessing Files Programmer's Guide
(32650-90017).

System Files

System-defined files are:

$STDIN
$STDINX
$STDLIST
$NEWPASS
$OLDPASS
$NULL

$NEWPASS and $OLDPASS are disc files that provide temporary files for
passing information between job steps. $STDIN, $STDINX, and $STDLIST are
device files that provide default input and output files. The
system-defined file $NULL is in neither category because it is not
associated with a disc or device. Figure 6-6 shows system-defined
files in use.

Figure 6-6. System Files in Use

System-defined file designators indicate files that the File System
uniquely identifies as standard input/output devices for jobs and
sessions.

These designators are:

* $STDIN; the standard job or session input device from which your
job or session is initiated.

* $STDINX; the same as $STDIN, except handling of MPE/iX command
images is different.

* $STDLIST; standard job or session listing device.

* $NULL; name of a file that is always treated as an empty file.

These designators are useful in redirecting program input and output to
standard devices. For detailed information on system-defined files,
refer to Accessing Files Programmer's Guide (32650-90017).

You can use a formal file designator in a program to specify a
system-defined file. For example, a program can specify the
system-defined file name $STDLIST to make output appear on a terminal; or
it can assign output to $NULL to test a program to see if it compiles and
runs to completion, where the actual output is not needed. Figure 6-7
(*) shows examples of using a system defined file.

Figure 6-7. Using a System File

Input/Output Sets

All file designators can be classified as an input set, use for input
files of an output set, used for output files. For your convenience,
these sets are summarized in Table 6-3 and Table 6-4 . For
information on interactive and duplicative input files and output files,
refer to Accessing Files Programmer's Guide (32650-90017).

Table 6-3. Input Set

Table 6-4. Output Set

| | |
| filereference | File name (including any account and group names and lockword, |
| | if necessary). Unless you specify otherwise, it is a |
| | temporary file residing on disc that is destroyed on |
| | termination of the creating program. If closed as a |
| | job/session temporary file, it is purged at the end of the |
| | job/session. If closed as a permanent file, it is saved until |
| | you purge it. |
| | |
- - -
---------------------------------------------------------------------------------------------

Passed Files

Programmers, particularly those writing compilers or other subsystems,
sometimes create a temporary disc file that can be automatically passed
to succeeding MPE/iX commands within a job or session. This file is
always created under the special name $NEWPASS. When the program closes
the file, MPE/iX automatically changes its name to $OLDPASS and deletes
any other file named $OLDPASS from the job or session temporary file
domain. (Domains are described in a subsection below). After the file
is closed, your commands and programs reference the file as $OLDPASS.
Only one file named $NEWPASS and one file named $OLDPASS can exist in the
job or session domain at any one time. Figure 6-8 shows the
automatic passing of files between program runs. For an example of file
passing and detailed information, refer to Accessing Files Programmer's
Guide (32650-90017).

Figure 6-8. Passing Files between Program Runs

$NEWPASS and $OLDPASS are specialized disc files with many similarities
to other disc files, but with some differences. For example, the default
close disposition of $NEWPASS includes renaming it. For detailed
comparisons of $NEWPASS to new files and $OLDPASS to old files refer to
Accessing Files Programmer's Guide (32650-90017).

Searching File Directories

There are two directories with addresses of files: Job Temporary File
Directory for the addresses of TEMP files, and System File Directory for
the addresses of PERMANENT files.

There is no directory for NEW files. When a file is opened, the File
System may search both directories, depending on the file domain options
specified, starting with the Job Temporary File Directory, until it finds
the file address associated with the file.

Finding Files

You can use the the following commands to see file and file equation
lists:

* :LISTFILE command for PERMANENT files

* :LISTFTEMP command for TEMP files

* :LISTEQ command for current file equations

For a detailed description of the commands, refer to Getting System
Information Programmer's Guide (32650-90018).

Types of Operations Allowed on Files

The types of operations most frequently used on a file involve reading,
writing, saving, appending, information to the end of a file, updating a
file, and various combinations of operations. The type of operation
allowed is determined when a file is opened. You can override the
operations allowed by system defaults with specifications in your program
or the :FILE command. The type of operation is not a permanent
characteristic of a disc file, so it is not in the file label. Thus, no
overriding can take place at this level, although the physical
characteristics of a device file may dictate the types of operations
allowed. For example, a line printer is always a write-only file, and a
real operation cannot be specified for it.

Physical characteristics of a file cannot be changed after it has been
created. Thus it is logical for the file label to take precedence over
all commands. Other determinants are effective only when a new file is
being created.

NOTE :FILE commands, HPFOPEN calls, and FOPEN calls cannot alter
physical characteristics of an existing file.

Opening a File.

Before a process can read, write, or manipulate a file, it must initiate
access to the file by opening it with the HPFOPEN or FOPEN intrinsic
call. This call applies to all disc and device files. When HPFOPEN or
FOPEN is executed, it returns a file number used to identify the file in
subsequent intrinsic calls issued by the process.

If the file is successfully opened, the file number returned is a
positive integer. If the file cannot be opened, the file number returned
is zero (0).

If the process issues more than one HPFOPEN or FOPEN call for a file
before it is closed, it results in multiple, logically separate accesses
of that file. In this case, MPE/iX returns a unique file number for each
access and maintains a separate logical record pointer. (indicating the
next sequential record to be accessed) for each access where you did not
request or permit the multi-access option at HPFOPEN or FOPEN time.

When you open a file, HPFOPEN or FOPEN establishes a communication link
between the file and your program. The link is established by
determining the device on which the file resides, allocating it to your
process, verifying access right, and performing other required tasks.
These tasks include constructing control blocks required by MPE/iX for
access to this file. For detailed information on establishing the
communication link and determining the File System hierarchy, refer to
Accessing Files Programmer's Guide (32650-90017).

For an example of opening new and old disc files, refer to Accessing
Files Programmer's Guide (32650-90017).

When a process opens a disc file, the HPFOPEN or FOPEN call specifies
that the file is OLD (located in either the System Permanent File
Directory or the Job Temporary File Directory) or NEW. An OLD file is an
existing file, and a NEW file is a file to be created during the process.
When a process accesses a file residing on a non-sharable device, the
device's attributes may override the OLD or NEW specification.
Specifically, a device used only for input automatically imposes a
PERMANENT domain on a file. A device used only for output, such as a
line printer, automatically imposes a NEW domain on a file. Serial
input/output devices, such as terminals and magnetic tape units, follow
the domain option specification in the HPFOPEN or FOPEN call.

NOTE The HPFOPEN intrinsic assumes that all files on non-sharable
devices (device files) are PERMANENT files. To maintain
compatibility with MPE V/E, device files can be opened with the
domain option set to NEW, but a warning is returned in the status
parameter.

When a job attempts to open a PERMANENT file on a non-sharable device,
MPE/iX searches for the file in its internal tables. If it does not find
the file, it requests the operator to locate the file. When a job opens
a new file on a non-sharable device (other than magnetic tape), it uses
the first available device. When a job opens a new file on a magnetic
tape unit, the operator is usually required to make the tape available.
The specification of a device name or device class when HPFOPEN or FOPEN
is issued, implies a request for the initial allocation of an unopened
device.

For detailed information on, and examples of, opening a file on a
non-sharable device, refer to Accessing Files Programmer's Guide
(32650-90017).

Closing a File.

You terminate access to a file from a program with the FCLOSE intrinsic.
It applies to files on all devices (disc files and device files) and
deallocates the device on which the file resides. If your program has
several concurrent HPFOPEN or FOPEN calls issued to the same file, the
device is not deallocated until the last FCLOSE intrinsic is executed.

You can use the FCLOSE intrinsic to change the disposition of a disc or
magnetic tape file. For example, a file you open as a NEW file can be
closed and saved as an OLD file with permanent or temporary disposition.
A disc file you open as a TEMP file can be closed as TEMP or saved as a
PERMANENT file.

When a program opens a NEW disc file with an HPFOPEN or FOPEN call, the
File System does not search to determine if a file of the same name
exists. This occurs when you attempt to save a file with the FCLOSE
intrinsic.

When a program opens a disc file specified as a NEW file in the option of
an HPFOPEN or FOPEN call that determines the domain, and saves it with
the FCLOSE intrinsic, the MPE/iX File System conducts a search. If the
file is to be saved as a TEMP file, it searches the Job Temporary File
Directory. If the file is to be saved as a PERMANENT file, it searches
the System Permanent File Directory. If the File System finds a file of
the same name in a directory it searches, it returns an error code to
your program. Thus, you can open a NEW file with the same name as an
existing file, but an error occurs if an FCLOSE intrinsic attempts to
save it in the same domain with a file of the same name.

Similarly, when a program opens a disc file specified as a TEMP file in
the domain option of an HPFOPEN or FOPEN call and saves it with the
FCLOSE intrinsic, only the Job Temporary File Directory (not the System
File Directory) is searched. Thus it is possible to have three files
with the same name, a PERMANENT file, a NEW file, and a TEMP file. If a
file opened as TEMP is closed and saved as a PERMANENT file with the
FCLOSE intrinsic, MPE/iX searches the System Permanent File Directory.
If it finds a file of the same name, it returns an error code to the
program.

If a program opens a disc file specified as OLD in the domain option of
an HPFOPEN or FOPEN call and saves it with the FCLOSE intrinsic, the File
System searches the Job Temporary File Directory and the System Permanent
File Directory to determine if a file of the same name already exists.
If it finds a file of the same name in either directory, it returns an
error code to your program.

If your program does not issue an FCLOSE intrinsic call on files that
have been opened, MPE/iX closes all files automatically when the
program's process terminates. In this case, MPE/iX closes all opened
files with the same disposition they had before being opened. NEW files
are deleted, OLD files are saved and assigned to the domain in which they
previously belonged, either PERMANENT or TEMP. This can be altered with a
:FILE command.

For examples of closing a new file as either a TEMP or a PERMANENT file,
refer to Accessing Files Programmer's Guide (32650-90017). Figure 6-9
shows the directories searched for file names when a file is opened
and closed, depending on the file domain.

Figure 6-9. Directories Searched Based on File Domain

The operation of the FCLOSE intrinsic used with unlabeled magnetic tape
is dependent on conditions within the process using the device. It is
possible for a single process to HPFOPEN (or FOPEN) a magnetic tape
device using a device class and later HPFOPEN (or FOPEN) on the same
device again by using its device name/logical device number. You can do
this in a way that makes more than one tape file open concurrently.

When no concurrent tape files are open, a tape is closed with the
temporary no-rewind disposition, rewound, and unloaded. When file open
and file close calls are nested, tape files can be closed without
deallocating the physical device, as shown in Figure 6-10 .

Figure 6-10. Nested HPFOPEN/FOPEN and FCLOSE Pairs

Nesting of HPFOPEN or FOPEN and FCLOSE pairs keeps a tape that has been
FCLOSEd from rewinding. A tape closed with the TEMP, no-rewind
disposition is rewound and unloaded unless the process closing it has
another file currently open on the device.

For detailed information on file disposition, end-of-file marks, and use
of FCLOSE with magnetic tape, refer to Accessing Files Programmer's Guide
(32650-90017).

MPE/iX 5.0 Documentation