Declaring a Sculptor keyed file¶
!file |
Declare a Sculptor keyed file which is initially closed |
!ofile |
Declare a Sculptor keyed file which is initially open |
Contents
Syntax¶
!file file_id “pathname” | pathname [read|create|createbig|update]
!ofile file_id “pathname” | pathname read|create|createbig|update
Declare a Sculptor keyed file.
The !ofile command is used to declare a file that is initially open.
The !file command is used to declare a file that is initially closed. Before the file can be accessed it should be opened with the openfile or open command. Sculptor opens a file automatically if it is required by a file access or update statement and is found to be closed, but it is strongly recommended that programs open files explicitly rather than depending on this behaviour.
To receive a warning when Sculptor opens a closed file automatically, set the Sculptor system variable sys.Warn to >= 4.
file_id |
The identifier by which the file is subsequently known within the program. A default record buffer with the same name is automatically created. The file_id must obey the usual identifier naming rules, and must be unique as an identifier name within the program. |
pathname |
The full directory path and filename of the file required. The filename requires no extension. Note See -i scc compiler flag related to the relative pathname interpretation. |
File mode¶
This clause is mandatory for !ofile and optional for !file. The available modes are:
read |
The file is opened in read-only mode. Records may be accessed, but may not be amended or deleted; nor may new records be created. Records are not locked out from other users. A Record in use status cannot normally occur on records in files open in read-only mode. The exception to this occurs on certain systems where a write lock on a file prevents even a read-only process from reading the file. |
update |
The file is opened in update mode. All successful read, find, next, prev and match commands cause the record selected to be available for update, and locked from other users, who will receive a Record in use status if they attempt to access the record in update mode. |
create [big] |
This is identical to update mode, except that a new, empty file is created. The file is then available for update. The file may or may not exist already; if it does exist, any records contained in it are destroyed. The current file ownership and access permissions are preserved. Obviously care is required here. Opening a file in create mode is the equivalent of performing a newkf on the data dictionary file, and then opening it in update mode. One appropriate use for this mode would be programs that utilise a temporary batch file that must be cleared down each time the program is run. A file can be of two sizes, standard or big. A big file can be up to 128Gb in size with up to 134,217,727 records (the maximum for a standard file is 16,777,215 records). See Maximum number of records; creating big files. If create is used, and the file to be created already exists, the new file is created with the same size (standard or big) as the old one. If the file does not exist, a standard file is created. If createbig is used, a big file is created regardless of whether the file already exists. Note that a create or createbig mode specified in ![o]file is ignored if the openfile command is used to create or recreate the file later. In this case the mode in the openfile command takes precedence. The mode specified in !file is used only if the file is opened automatically by Sculptor, which happens if the program tries to access the file when it is closed. |
The file mode clause, if used with !file, specifies the mode to be used if the file is first opened by means of the open command (the default is update mode). The open command has no mode clause, and refers to the file’s !file or !ofile declaration to determine the mode to be used. The openfile command is not affected, as it has a mode clause of its own (also defaulting to update mode).
The read-only state attribute can be used to test a file’s mode at run time.
Files required¶
At compile time, the data dictionary file (.d extension) must reside in the directory specified in pathname, or in the current working directory if no path was specified.
At run time, an index file (.k extension) and data file (no extension) must exist for the named file if it is accessed or updated. They will normally be in the same directory as the data dictionary. However, the interpreter does not check for the presence of these files when the program loads, and the path can be specified at run time by means of the name = clause of the openfile command. This can be useful, for example, if the location of the files is determined by an environment variable or user name. It is advisable in these circumstances to copy the data dictionary to every such location.
If the file was created as index-only, then only the index file is required. See newkf.
If !ofile is used with create mode, the index file and data file need not exist when the program loads, since they will be created when the file is opened.
If !file is used, the data and index files are only required if the file is opened. The openfile command can be used to create them at run time.
Maximum number of files open¶
There is no specific limit to the number of Sculptor keyed files that may be open at any one time, available memory being the only limiting factor. The exception to this is that clients who connect to kfserver using earlier versions of Sculptor than 4.2 are restricted to 400 open files. See Servers.
The number of files that may be open at any one time is also dependent on the operating system. !file is therefore very useful if the operating system imposes more limits on the number of open files than does Sculptor. If the maximum number of files permitted by the operating system is exceeded, the program aborts. Note that each secondary index for an open file counts as an extra file.
NOTES
At run time, the read-only File state attribute can be used to test if a file is open, and if so in which mode.
New Sculptor keyed files are created by the newkf utility. The -i option allows the creation of an index-only Sculptor file.
If file_id is not unique, or is a reserved word, then a compiler error results.
The mode of a file may be changed by first closing it, and then opening it in the new mode.
The two environment variables SCDATA and SAGEDATA allow a prefix to be prepended to a filename. If the environment variable SCDATA is defined, it is prepended at run time to the name of any file declared within a screen form program, unless the file name contains an embedded “:”, which is taken to indicate a remote pathname over a network or an absolute pathname on MS-DOS. If SCDATA is defined, SAGEDATA is ignored. If, however, SCDATA is undefined but SAGEDATA is defined, then SAGEDATA is prepended, unless the file name begins with “\” or “/”, or contains an embedded “:”.
All pathnames may use the forward slash character /, except when used as part of an exec command on an MS-DOS system. This provides portability between UNIX and DOS systems.
Environment variables may be used within a file definition, as in the third example below.
File runtime reference¶
Since Sculptor version 6.2.0 a runtime reference is supported to access a !record or ![o]file fields or subrecords when using a pointer or function arguments.
Client cache service attributes¶
Since Sculptor version 6.2.0 a client cache service has been implemented. Which can be configured in a file by file basis using a new set of ![o]file attributes.
EXAMPLES
!file Samples "data/samples"
!ofile Address "/usr/db/add" read
!ofile Personal "$MYDIR/$MYSUBDIR/myfile" update
RELATED TOPICS |