Devicefiles Before an asynchronous device can be used by your
program, you must obtain access to the device and define the characteristics
you want to be associated with the device for your application.
You do this by using the FOPEN or HPFOPEN intrinsic to open a file
on the device, passing the file specifications required by your
program in the parameters of the call. See Chapter 8 “Intrinsics Reference” for a description of the syntax of the
FOPEN and HPFOPEN intrinsics.
When the FOPEN or HPFOPEN call is executed, MPE/iX will open
the file as specified by the parameters of the call, establish communications
between your program and the file, allocate needed resources (including
the device on which the file is to reside), and return a file number
to your program. If the file is not opened successfully, a 0 is
returned as the file number. See Chapter 2 “Controlling Asynchronous Devices
Programmatically” for more information on condition codes.
The file number assigned by the open call is unique. Because
every file has its own number, even if multiple files are opened
on the same device, it is possible to use the file number to access
a specific file in subsequent intrinsic calls. The file number remains
associated with the file as long as it is opened; that is, until
your program either issues an FCLOSE against that file or terminates.
The parameter values used for the FOPEN or HPFOPEN call determine
what features will be associated with the file. System default values
are assumed for any optional parameters not specifically designated.
Default values will also be assumed if you attempt to specify
a value that does not make sense for the device on which the file
is being opened. For example, the userlabel
parameter of the FOPEN intrinsic has no meaning for files opened
on terminals and, if specified, any value will be ignored and the
default of 0 assumed.
The fact that parameters are ignored if not meaningful for
a specific device provides an extra degree of flexibility when coding
a program. If you foresee an instance when you might want to temporarily
redirect a file normally resident on one type of device to another
type of device, you can code the specifications that will allow
you to do so. For example, you can specify the tape label option
(foption bit (6:1) of the FOPEN intrinsic)
for a file your program normally opens on a terminal even though
this option has no meaning for files on asynchronous devices.
If you later run the same program, but issue a :FILE
command to redirect that file to tape, there is no need to specify
the tape label option.
File Open Intrinsics |
 |
The way in which file characteristics are specified differs
depending on whether you are calling FOPEN or HPFOPEN. The parameters
of the FOPEN intrinsic are positional. The file system expects to
see them in a certain order and will not accept any specifications
that fail to conform. An FOPEN call to open $STDIN
for reading might be coded as:
fileid_in:=FOPEN(,octal(`444'),0,-80);
HPFOPEN provides a superset of the features provided by FOPEN
and uses combinations of itemnum/item
pairs to specify file characteristics. An HPFOPEN call performing
the same function as the FOPEN call above (and returning any error
information in a variable called "status") might
be coded as:
HPFOPEN(fileid_in,status, 53,1, |
HPFOPEN can be used in native mode only. None of the extended
features provided by this intrinsic apply specifically to asynchronous
devicefiles. For consistency, the examples that follow will show
the use of FOPEN exclusively. Be aware, however, that, in native
mode, HPFOPEN calls can be used instead.
Your program may open multiple files on the same device, each
with its own set of characteristics, logically separate access,
and unique file number. Such files opened on a device are often
referred to as ports.
The code fragments shown in Figure 3-1 “Opening a Read Port and a Write Port” open a read port and a write port on a
terminal device. The parameters specify 80 byte ASCII records and
carriage control. Condition codes are checked in the example through
the Pascal/iX ccode function, which
will return a value of CCE if no errors occur during the opens,
or of CCG or CCL if errors do occur.
Figure 3-1 Opening a Read Port and a Write Port
|
| |
|
 | NOTE: The ccode function
used in the examples is a Pascal/iX intrinsic function that returns
the condition code bits from the status register. If you are using
a language other than Pascal/iX, you should see the reference manual
for that language for information on how to access the condition
code bits. |
|
| |
|
After the FOPEN calls are successfully executed, the variable
fileid_in will contain the file number
of a file that can be read from, and the variable fileid_out will
contain the file number of a file that can be written to.
It is possible to issue a single FOPEN call that will allow
you to read and write from a single file. However, to do so you
must include some additional parameters in the FOPEN call. You must
specify a formal file designator in the formaldesignator
parameter of the FOPEN call (HPFOPEN item number 2) instead of using
one of the system defined files ($STDIN,
$STDINX or $STDLIST).
You must also specify the logical device number of the terminal
device in the device parameter (HPFOPEN item
number 20). You can use the WHO intrinsic to determine the logical
device numbers of the devices being used as the input and output
devices for the current job or session.
