Guardian Programmer's Guide

Using the File System
Guardian Programmer’s Guide — 421922-014
2 - 11
Creating Files
Disk files, for example, can be created programmatically using the
FILE_CREATE[LIST]_ procedure or interactively using the TACL CREATE or File Utility
Program (FUP) CREATE command. Device files are created either at operating-
system generation time or by COUP (D-series releases) and SCF (G-series releases);
they are not created programmatically. Process files are created when a process is
created either programmatically using the PROCESS_LAUNCH_ or
PROCESS_CREATE_ procedure or interactively using the TACL RUN command. One
of the most important effects of creating a file is that a file name is given to the file.
Creating Disk Files
You can use either the FILE_CREATE_ or FILE_CREATELIST_ procedure to create
disk files programmatically. FILE_CREATE_ allows you to specify most of the
commonly used properties that a disk file can have, such as the file type (unstructured,
relative, entry sequenced, or key sequenced), block length, record length, and extent
sizes. Some files, however, need properties that you cannot assign using
FILE_CREATE_ (such as alternate-key files and partitioned files); for these files, you
need to use the FILE_CREATELIST_ procedure.
Some examples of what you can do with the FILE_CREATE_ procedure are given
here. For specific examples of using FILE_CREATELIST_, see Section 5,
Communicating With Disk Files. For complete details of both of these procedures, see
the Guardian Procedure Calls Reference Manual.
The following lines of code create a permanent, unstructured disk file:
STRING NAME[0:ZSYS^VAL^LEN^FILENAME - 1];
STRING .S^PTR;
.
.
NAME ':=' "$OURVOL.MYSUBVOL.DATAFILE" -> @S^PTR;
LENGTH := @S^PTR '-' @NAME;
ERROR := FILE_CREATE_(NAME:ZSYS^VAL^LEN^FILENAME,
LENGTH);
The first parameter to the call passes the name of the file to be created. In this case,
the name is $OURVOL.MYSUBVOL.DATAFILE. Because the node name is not
specified, the node name in the =_DEFAULTS DEFINE is used.
The first parameter also indicates the maximum length of the file name in bytes. The
buffer (NAME in this example) should also have a length equal to the maximum file-
name length. In this case, the literal ZSYS^VAL^LEN^FILENAME provided in the
ZSYSTAL file has been used to reserve a buffer large enough for any file name
including space for future expansion of file names. Here, the maximum length need
only reserve enough space for the supplied file-name string, because the actual length
of the file name is known on input.
Note. File names should normally be passed to a process either in a DEFINE (see Section 7,
Using DEFINEs) or in the Startup message (see Section 8, Communicating With a TACL
Process). For simplicity, however, examples throughout this section receive hard-coded file
names.