.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".

.CCFIL - create file or catalog.

Usage:

Examples:

Where:

Description:

See Also: