HP 3000 Manuals

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

File Structure 

When you create a file, the File System imposes a structure and access
method on the content of the file.  Access to records in a file are
dictated by the file type specified at file creation.  Important factors
in creating a file are discussed below.

File Types 

Depending on your intended use of the file, you can specify the following
file types:

   *   Standard file, which is the most common type of file.  It is
       structured as a group of records, beginning with record 0 and
       ending with record n-1, where n is the maximum specified in the
       filesize option.  The Standard file type is the default created
       when you first open a file.  Examples of Standard files are Editor
       files and program files.

   *   KSAM file.  Keyed Sequential Access Method (KSAM) is a method of
       organizing records based on the content of key fields within the
       records.  Each record in a KSAM file contains a primary key field;
       the contents of the primary key field determine the primary
       logical sequence of records in the file.  Other key fields can be
       defined so that you can sequence the file in other orders.  The
       order in which records are physically written to the file is the
       chronological order.  The chronological order may be the same as
       the primary key sequence or unrelated.  For detailed information
       on the creation and use of KSAM files, refer to Chapter 7, "Data
       Management" and KSAM/3000 Reference Manual (30000-90079).

   *   RIO file.  Relative I/O (RIO) is a random access method that
       permits individual file records to be deactivated.  These inactive
       records retain their relative position in the file.  RIO files are
       intended for use primarily by COBOL programs; however, you can
       access these files by programs written in any language.

You can access RIO files in two ways:  RIO access and non-RIO access.
RIO access ignores the inactive records when the file is read
sequentially using the FREAD intrinsic.  These records are transparent;
however, they can be read by random access using FREADDIR. They can be
overwritten serially and randomly using FWRITE, FWRITEDIR, or FUPDATE.
With RIO access, the internal structure of RIO blocks is transparent.

   *   Circular file, which is a wrap-around structure that behaves like
       a standard sequential file until it is full.  As records are
       written to a circular file, they are appended to the tail of the
       file; when the file is filled, the next record added causes the
       block at the head of the file to be deleted and all other blocks
       to be logically shifted toward the head of the file.  Circular
       files are particularly useful as history files and debugging
       files.  For detailed information on circular files, refer to
       Accessing Files Programmer's Guide (32650-90017).

   *   Message file, which is used by Interprocess communication (IPC), a
       facility of the File System that permits multiple user processes
       to communicate with one another easily and efficiently.  Message
       files act as first-in-first-out queues of records, with an entry
       made by FWRITE and a deletion made by FREAD. One process can
       submit records to the file with the FWRITE intrinsic while another
       process takes records from the file using the FREAD intrinsic.

For detailed information on the creation and use of Message files, refer
to Interprocess Communication Programmer's Guide (32650-90019).

File Codes 

MPE/iX subsystems often create special-purpose files whose functions are
identified by four-digit integers called file codes, written in the
system file labels.  HPFOPEN, FOPEN, :BUILD, and :FILE have parameters
for specifying a file code for a file when you create it.

File codes are useful when you want to run a program that produces an
output file several times and need to be able to uniquely identify the
output files from separate runs (or sets of runs).  You can use a :FILE
command to supply a unique file code for each run (or set of runs).

For user files, you can use any number from 0 through 1023 for a file
code.  If you do not specify a file code when you create a file, MPE/iX
automatically applies the default file code 0.  Numbers above 1023 are
predefined by Hewlett-Packard for special system files.  You should not
redefine them.  For detailed information, refer to Accessing Files 
Programmer's Guide (32650-90017).

For detailed information on creating and using a file code and on
reserved file codes, refer to Accessing Files Programmer's Guide 
(32650-90017).  For information on determining an existing file code,
refer to Getting System Information Programmer's Guide (32650-90018).

Creating a File 

When creating a file, you choose physical characteristics for it based on
how the file will be used.  These physical characteristics are determined
by parameters you choose when you:

   *   Create the file with the HPFOPEN intrinsic, FOPEN intrinsic, or
       the :BUILD command.

   *   Specify the file with the :FILE command.

Once a file has been created, you cannot change its physical
characteristics.  You can change other characteristics by redefining them
each time you open the file.  The :FILE command, HPFOPEN intrinsic, and
FOPEN intrinsic can alter the way a file is to be used.

The physical characteristics include record format, record size, volume
class, and many other attributes.  The intrinsics and commands for
specifying the physical characteristics of a file are described below.
(For detailed information on creating a file, refer to Accessing Files 
Programmer's Guide (32650-90017).

HPFOPEN and FOPEN Intrinsics.   

The HPFOPEN intrinsic is a programmatic tool that establishes access to a
disc or device file and enables you to create a file on a sharable
device.  Its optional parameters are a superset of the options in the
FOPEN intrinsic and provide more efficient file access.  You can use
HPFOPEN parameters to specify record format, record size, volume class,
and many other physical characteristics.  HPFOPEN and FOPEN allow file
names to include command interpreter (CI) variables and expressions.

When a previously non-existent file is created at run-time, the File
System must set up the physical characteristics of a NEW file.  You can
use a :FILE command to specify the physical characteristics of a NEW
file.  These override any system defaults and any specifications given in
the program or subsystem when it opens the file because no file label has
been defined for this NEW file.  If you want to keep the NEW file
permanently, you should close it as a TEMP or PERMANENT file.  Otherwise,
it is deleted when the program or subsystem terminates.  Figure 6-14  
shows an example of creating a file.


          Figure 6-14.  Creating a File 

The FOPEN intrinsic is another programmatic tool for supplying the File
System with information about a file.  You can use optional parameters at
file creation to specify record structure, file identification, file
domain, and file usage characteristics.

For detailed information on the HPFOPEN and FOPEN intrinsics, refer to
MPE/iX Intrinsics Reference Manual (32650-90028) and Accessing Files 
Programmer's Guide (32650-90017).

The :BUILD Command.   

The :BUILD command creates a file in much the same way as the HPFOPEN and
FOPEN intrinsics, except that they are used within a program and :BUILD
is entered as an MPE/iX command.  The :BUILD parameters have meanings and
applications that are similar to the corresponding parameters for HPFOPEN
and FOPEN. For detailed information on how to use the :BUILD command,
refer to the MPE/iX Commands Reference Manual Volumes 1 and 2 
(32650-90003 and 32650-90364).

You can use the MPE/iX command :BUILD to create a file and specify the
physical characteristics of the file to the File System.  When you invoke
:BUILD, the File System sets up the physical characteristics in the file
label and allocates space for a permanent file on disc.  For detailed
information, refer to the MPE/iX Commands Reference Manual Volumes 1 and 
2 (32650-90003 and 32650-90364) and Accessing Files Programmer's Guide 
(32650-90017).

Deleting Files 

You can use the :PURGE command to delete files from disc.  This command
deletes the specified file by removing the directory entry pointing to
the file.  It can be used to delete PERMANENT or TEMP files.  The :PURGE
command does not accept wildcard characters.

Renaming Files 

You can use the :RENAME command on a TEMP or PERMANENT file if you are
the creator of the file.  :RENAME can be used to change the file name and
add or change a lockword.  You can use :RENAME to move a file to a
different group in which you have SAVE access.  Renaming the file does
not change the file domain, and you cannot rename a file while it is in
use.

Saving Temporary Files 

You can use the :SAVE command on a temporary file to make it permanent.
This operation requires you to provide the file's lockword (if it has
one).  For example, you could save $OLDPASS to a new name using the
following syntax, where newfilereference is the name to which you want to
save $OLDPASS:

        :SAVE $OLDPASS, newfilereference 

Listing File Characteristics 

You can use the :LISTFILE command to see what the characteristics of a
file are.  :LISTFILE provides the following information: 

   *   File names and structure of permanent disc files

   *   Various levels of detail about each file, depending on the user's
       capability on the system

   *   Number of records in the file

   *   Number of extents

   *   Maximum number of extents

   *   Records per block

The :FILE Command 

The :FILE command determines how a file will be accessed.  You can use
:FILE to describe any of the characteristics available with HPFOPEN,
FOPEN, or :BUILD, but you cannot actually create a file with the :FILE
command.  While HPFOPEN, FOPEN, and :BUILD physically allocate space for
a file and define its characteristics, the :FILE command can define only
how a file will be accessed at run time.

FILE sets up an environment for the file at run time and specifies the
file's attributes when it is opened.  When you invoke a :FILE command,
the Command Interpreter checks it for syntactic correctness and saves a
file equation in a job or session table for use when the referenced file
is opened.  Another process, such as an HPFOPEN or FOPEN, performed on
the referenced file activates the information specified in the :FILE
command.  To be effective, the :FILE command must be invoked before the
file is accessed because the parameters specified for :FILE take effect
when the file is accessed.  They remain in effect until one of the
following conditions occurs:

   *   The job or session ends.

   *   A :RESET command is invoked.

   *   The parameters are overridden by another :FILE command invoked for
       the same formal file designator.

File equations are kept track of by a table created for the job or
session.  You can use the MPE/iX commands :LISTEQ to see a list of the
current file equations and and :LISTFTEMP to see a list of the current
temporary file names.

For an example of using the :FILE command and a comparison of the
parameters for HPFOPEN, FOPEN, and :FILE, refer to the MPE/iX Commands 
Reference Manual Volumes 1 and 2 (32650-90003 and 32650-90364) and
Accessing Files Programmer's Guide (32650-90017).

MPE/iX 5.0 Documentation