Opening a Sculptor keyed file

openfile

Open a Sculptor keyed file

SYNTAX

openfile file_id [name = pathname | SQL_connection_string] [create | createbig | read | update] \
          [nsf = label] [fe = label] [err = label] [traps = label]

Open the specified Sculptor keyed file. The file must have been declared within the program by means of ![o]file.

If a file was declared by !file, meaning it is initially closed, or if it was declared initially open by using !ofile but has subsequently been closed, it should be opened before the data it contains can be accessed or the file updated. 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.

This command may also be used to open a file in an ODBC database.

file_id

The identifier of the file to be opened. The identifier is defined in the file’s !ofile declaration.

[name = pathname]

This optional clause may be used to specify the path and filename of the file required. The filename requires no extension. If this clause is absent, the pathname allocated when it was last opened is used, defaulting to the path allocated when it was declared.

[name = SQL_connection_string]

Alternative form for use with ODBC databases only. See SQL database connection strings.

[create[big] | read | update]

File mode. This clause is optional. If it is absent the mode specified in the file declaration is used, defaulting to update mode. The meanings of the 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 or match commands cause the record selected to be available for update, and locked from other users, who receive a Record in use status if they attempt to access the record in update mode.

create

This is identical to update mode, except that a new, empty file is created. The file is then available for update. The fe trap (see below) may be used to determine the action to be taken if the file already exists. If it does exist, and openfile create is executed, any records contained in it are destroyed. 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 in programs utilising a temporary batch file that requires clearing down each time the program is run. Note that in an ODBC database the file must already exist - the fe trap cannot occur.

If the file to be created already exists, the new file is created with the same size (standard or big) as the old one. createbig (see below) can be used to force a big file. It is not possible to force a standard file.

createbig

Identical to create mode, except that a big file is created, which 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.

See Testing file mode.

[nsf = label]

Traps the No such file error condition which is generated if the specified file does not exist. Control passes to the line indicated by label.

In order to open a keyed file in read or update mode Sculptor requires that the index file (.k extension) and the data file (no extension) are present in the directory specified. This directory is originally defined when the file is declared (!ofile), but may be overridden at run time by means of the openfile name = clause. Index-only files (created by the newkf -i option) require the index file only.

If a file is opened in create mode, the index file and data file need not exist as they are created automatically when the file is opened.

If this condition is not trapped, the error No such file is displayed and control passes to the active menu, if any. If no menu is active the program exits.

In a !report section, an untrapped NSF causes the command to be ignored.

[fe = label]

If a file is opened in create mode, and it already exists, its current contents are destroyed. This condition may be trapped by the Fe trap, which works as follows:

openfile file_id create

The fe condition is not trapped. The file is created and the old contents are lost.

openfile file_id create fe = label

The fe condition is trapped and control passed to a specified line label. Sculptor passes control to the line specified, and a new file is not created.

openfile file_id create fe = IGNORE

The fe condition is trapped with the special label IGNORE. A new file is not created . It is assumed that the programmer intends to check sys.Traps.

The fe condition cannot occur in an ODBC database - the file must exist already.

[err = label]

Error conditions other than No such file and File exists (such as permissions failures) return the trappable condition err, which may be trapped by the err = clause or by the general traps = clause. Control passes to the line indicated by label. The error number is stored in the system variable sys.Error. The error numbers are defined by manifest constants in the file errors.h, which is located in the Sculptor include directory. This file may be included in a program by means of a !include declaration.

If an error occurs and is not trapped, an error message is displayed and the program returns to the active menu, if any. If no menu is active the program exits.

If an untrapped error occurs in a !report section, the openfile command is ignored.

[traps = label]

General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped.

File position and buffers

Closing and reopening a file does not alter the current file position for next and prev type commands, nor does it clear any record buffers attached to the file. However, the clear command still operates on the buffers of closed files, unless the preserve command has been used on them.

Maximum number of files

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. If the maximum is exceeded, the program aborts. Note that each secondary index for an open file counts as an extra file.

Testing file mode

The read-only clause:

file_id->state

can be used to determine the mode in which a file is currently open. The values which file_id->state can have are as follows:

0

closed

1

read

2

create

3

update

NOTES

  • The open command may also be used to open a file. However, no traps may be attached to the open command, and it is not the recommended method.

  • A file may subsequently be closed by means of the close command.

  • The mode of a file can be changed by closing it, and then opening it in the new mode.

  • An attempt to open a file that is already open is ignored if the mode is unchanged.

  • This command may only be used to open a Sculptor keyed file or ODBC database file. In order to open a sequential file, use the open # command.

EXAMPLES

openfile Codes read traps = NOCODES
openfile Prices update nsf = PR_NSF traps = IGNORE
openfile File3 create fe = IGNORE
openfile RemData name = ServName / "/data/remdata" update

RELATED TOPICS

Keyed files

Traps

![o]file

close

closefile

open

open #