.CCFIL - create file or catalog.
Alternate Entry Name: CCFIL
Usage:
B:
status = .ccfil(path[,size[,action[,cat_action]]]);
C:
int _ccfil(const char *path, [int size, const char *action,
const char *cat_action]);
Examples:
.ccfil("myfile");
.ccfil("cat/file",10,"rw","r");
Where:
- path
- points to a string giving the name of the file or catalog
to be created.
- size
- is an optional integer argument. If "size" is
0, .CCFIL will create a catalog with the given
"path" name. If "size" is non-zero,
.CCFIL will create a file. The bottom half of the
"size" word gives the initial size for the file
being created. If the top half of "size" is
non-zero, the value of the top half is set as the maximum
size of the file; otherwise, the file will have
"unlimited" size. If you do not specify a
"size" argument, the initial size is 1 llink
and the maximum size is unlimited.
- action
- is an optional string argument. The characters in the
string give options for the file/catalog creation.
Possible options are described later on.
- cat_action
- is an optional string argument. If "cat_action"
is present and non-zero, .CCFIL will create any
intervening catalogs that are needed to create the given
"path". For example, suppose you try to create
"user/newcat/file" but the catalog
"newcat" does not exist. If
"cat_action" is specified, .CCFIL will
automatically create "newcat" as well as
"file". The "cat_action" string gives
options for the creation of the intervening catalogs, in
the same way that "action" gives options for
the creation of the target file or catalog.
- status
- is the negative of the FMS major status. Non-zero values
indicating that the creation failed will only be returned
if the "f" action was specified.
Description:
.CCFIL creates a file or catalog. When a file is created, the
external PRM.CR is assumed to contain default permissions for the
file. For created files, the value of PRM.CR is used to specify
general permissions and other create options. Permissions and
other options will be "added" to those specified in
PRM.CR unless the "i" action is specified, in which
case the value of PRM.CR will be ignored. There are no default
permissions when a catalog is created.
The "action" string specifies various options for
the creation. When a file is being created, the options are
normally added to the default permissions in PRM.CR. However,
there is an "action" option which says that
"action" options should be used INSTEAD of the default
permissions in PRM.CR.
The following characters may appear in the "action"
string (in any order).
- a - Append permission
- gives the file/catalog general Append permission.
- b - Block mode
- creates a random file. By default, .CCFIL creates a
sequential file.
- c - Concurrent/Create permission
- gives a catalog general Create permission. When creating
a file, "c" gives the file ACCESS/CONCURRENT/
concurrency. This will override the default concurrency
from PRM.CR. (Normally this is "Read While
Write".)
- f - FMS error recovery
- If an error occurs, .CCFIL will return control with a
status. The default action is to EXIT with an error
message.
- i - Ignore PRM.CR
- indicates that .CCFIL should ignore PRM.CR when creating
a file. General permissions, concurrency, and locks will
be as specified by "action".
- k - write locK
- creates a file with a write lock, i.e. the file cannot be
opened for write after writing to it once.
- l - Lock permission
- gives the file/catalog general Lock permission.
- m - Message
- prints an error message even though the "f"
action is specified. Normally, when "f" is
specified, .CCFIL just returns an error status, without
printing a message.
- n - Normal concurrency
- gives the file ACCESS/NORMAL/ concurrency. This will
override the concurrency specified in PRM.CR.
- p - Purge permission
- gives the file/catalog general Purge permission.
- r - Read permission
- gives the file/catalog general Read permission.
- s - Security lock
- creates the catalog or file with a security lock turned
on.
- v - recoVery permission
- gives the file/catalog general Recovery permission.
- w - Write permission
- gives the file/catalog general Write permission.
- x - eXecute permission
- gives the file/catalog general Execute permission.
- y - modifY permission
- gives the file/catalog general Modify permission.
- 1 - 1 writer
- gives the file ACCESS/READ WHILE WRITE/. This will
override the concurrency specified in PRM.CR.
General permissions are explained in "expl file system".
IMPORTANT NOTE: In commands like ACCESS, some permissions
imply others. For example, if you use ACCESS to give a file
general Write permission, it is automatically given general Read.
However, .CCFIL does not work this way -- you only get the
permissions you ask for. For example, if you create a file with
.ccfil("filename", 0, "iw");
the file will ONLY have general Write permission. If you want
all the permissions usually implied by ACCESS's Write permission,
use
.ccfil("filename",0,"rwax");
The "cat_action" string has the same format as the
"action" string. As noted above, the presence of a
non-zero "cat_action" string means that .CCFIL should
create any intervening catalogs needed to create the target
file/catalog and should give those catalogs the permissions
indicated by "cat_action". "cat_action" may
contain any of the options that are valid for "action",
with the exception of "b", "i",
"k", "n", and "1".
Note that "cat_action" may or may not contain an
"f" indicating FILACT error recovery. If
"action" contains an "f" but
"cat_action" does not, .CCFIL will handle errors in
creating the target file/catalog but will abort if errors occur
in creating the intervening catalogs. If you want to handle all
possible errors, put "f" in both "action" and
"cat_action".
$CCFIL posts any errors it detects through the usual .EPOST
facilities. For more information, see "expl
b lib .epost".
See Also:
- expl b lib .rfile
- for a function to release a file.
- expl b lib external flsyerr
- for a vector of error messages.
- expl b lib external prm.cr
- for the default permissions and concurrency word.
Copyright © 1996, Thinkage Ltd.