Guardian Programmer's Guide

Using the File System
Guardian Programmer’s Guide — 421922-014
2 - 16
Opening Files
Examples of opening disk files, device files, and process files follow.
Opening Disk Files
To open a disk file, use a call like the following:
FILE^NAME ':=' "$OURVOL.MYSUBVOL.DATAFILE" -> @S^PTR;
LENGTH := @S^PTR '-' @FILE^NAME;
ERROR := FILE_OPEN_(FILE^NAME:LENGTH,
FILENUM);
The first parameter (FILE^NAME:LENGTH) is the file name created by the
FILE_CREATE[LIST]_ procedure (or the TACL CREATE command or the FUP
CREATE command). LENGTH is an integer variable that specifies the length in bytes
of the file name. If the file was created using the FILE_CREATE_ procedure, you can
use the length value returned by that procedure.
The second parameter (FILENUM) returns a number that your program uses to identify
the file in subsequent operations. Once the file is opened, you use this number to
identify the file.
Opening Disk Files for Ensured Data Integrity
To ensure data integrity when you perform write operations to a disk file, you need to
open that file using a nonzero value for the sync-depth parameter as follows:
FILE^NAME ':=' "$OURVOL.MYSUBVOL.DATAFILE" -> @S^PTR;
LENGTH := @S^PTR '-' @FILE^NAME;
SYNC^DEPTH := 1;
ERROR := FILE_OPEN_(FILE^NAME:LENGTH,
FILENUM,
!access!,
!exclusion!,
!nowait^depth!,
SYNC^DEPTH);
Setting the sync-d
epth parameter to a nonzero value causes the disk I/O process to
checkpoint information to its backup process when performing I/O operations. If the
CPU on which the primary disk process is running fails, then the backup disk process
can use the checkpointed information to establish whether it needs to complete the
operation or whether the operation finished successfully before the failure occurred.
Recovery from a CPU failure in this way is invisible to the application process.
If you do not set the sync-dept
h parameter to a nonzero value on opening the file,
the backup disk process has no way of knowing whether the operation finished
successfully. If you open a disk file with a zero sync depth, then a CPU failure could
cause corruption of data.
Opening Devices
Opening a device file is similar to opening a disk file. The call to FILE_OPEN_ is the
same; the only difference is in determining the file name. Remember that device