|
|
|
Getting Started as an MPE/iX Programmer Programmer's Guide: HP 3000 Computer MPE/iX Computer Systems > Chapter 6 File System
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. 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 “New, Temporary, and Permanent File Features” 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 “Valid File Domains”. Table 6-2 Valid File Domains
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. 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. 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. 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:
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:
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. 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 allow you to identify a file. This is necessary in order to:
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. 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:
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.
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 “Identifying a Disc File using File Designators” 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. 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 “Backreferencing a Previously Identified File” 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. For detailed information, refer to Accessing Files Programmer's Guide (32650-90017). The File System recognizes two general classes of files:
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: 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:
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-defined files are:
$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 “System Files in Use” shows system-defined 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:
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 “Using a System File” shows examples of using a system defined file. 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 “Input Set” and Table 6-4 “Output Set”. 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
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 “Passing Files between Program Runs” 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). $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). 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. You can use the the following commands to see file and file equation lists:
For a detailed description of the commands, refer to Getting System Information Programmer's Guide (32650-90018). 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.
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.
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). 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 “Directories Searched Based on File Domain” shows the directories searched for file names when a file is opened and closed, depending on the 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 “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). |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
![[Identifying a Disc File using File Designators]](img/f0604.gif)
![[Backreferencing a Previously Identified File]](img/f0605.gif)
![[System Files in Use]](img/f0606.gif)
![[Using a System File]](img/f0607.gif)
![[Passing Files between Program Runs]](img/f0608.gif)
![[Directories Searched Based on File Domain]](img/f0609.gif)
![[Nested HPFOPEN/FOPEN and FCLOSE Pairs]](img/f0610.gif)