DIR-VIEW

Creates a special Reality file that provides access to a host directory. The files in the directory appear as items in the Reality file and, unless defined as a binary view (see Options), each new line of text in a text file appears as an attribute (line) within the associated item (on read, newline characters are converted to attribute marks and on write, attribute marks are converted to newline characters).

Syntax

DIR-VIEW file-name directory {(options}

Syntax Elements

file-name The name of the directory view file. The format of a valid file name is described in Rules for File and Data Section Names.

directory The absolute path of the host directory to be associated with the Reality file.

Note: You can also use a relative path, but this is not recommended because the directory location will depend on the way in which you have logged onto the database.

Options

B Binary view. All files within the host directory are written to and read as binary items – no NEWLINE/Attribute Mark translations are performed.

F Binary view on read. All files within the host directory are read as binary items – no NEWLINE/Attribute Mark translations are performed. However, items are written as ASCII (with Attribute marks converted to newline characters) or binary depending on whether the data in memory is considered by Reality to be binary data.

R Read only. The host directory cannot be modified from Reality.

Restrictions

You can only use the DIR-VIEW command if Directory View is enabled in your security profile.

Access to a directory view file is also subject to the access permissions of the referenced host directory and files. Attempting to access the directory view of a directory to which you do not have access permissions will display an error message. If you do not have read access to particular files in the host directory, those files will not be visible in the directory view.

Note: When using DIR-VIEW on Windows, you must ensure that the Reality Users group has permission to access the directory concerned and all directories in the path of this directory. For example, if you are setting up a directory view of the directory C:\user1\accounts, the Reality Users group must have access to drive C: and to the directories C:\user1 and C:\user1\accounts.

Because the maximum size of a Reality item is 2Gb, host files larger than this will not be visible in a directory view. Similarly, special files such as sub-directories, pipes and devices are not visible in the Reality file.

Directory view should be used with care when accessing binary data (such as graphics). Unless the directory view file is defined as binary, data read from a binary file may be corrupted.

Directory view files do not take part in transactions or Transaction Logging.

The names of items you create in a directory view file must be valid file names on the host operating system.

Comments

The directory view file is virtually indistinguishable from an ordinary Reality database file, enabling the referenced host directory to be accessed and manipulated by a database user using standard TCL commands and other processors, such as English, DataBasic and Proc.

More than one directory view file can be created for the same host directory. Any operation in one (such as deleting an item) will affect all directory view files associated with that host directory.

A directory view file can be used to transfer data between the host and Reality environments.

DIR-VIEW will create a directory view file even if the specified directory does not exist in the host file system. However, any attempt to view such a directory will return the error message:

'directory' IS NOT A FILE NAME

Example

On a UNIX system, create the directory /user1/accounts, or on a Windows system, create the directory C:\user1\accounts. Next, create two sub-directories vat and log, and three files invoice109, invoice110 and invoice111.

Now, at TCL enter:

DIR-VIEW ACCOUNTS /user1/accounts (on UNIX)

DIR-VIEW ACCOUNTS C:\user1\account (on Windows)

as appropriate.

The following message is returned:

[417] FILE 'ACCOUNTS' CREATED.
D/CODE =DY, DIRECTORY = /user1/accounts

This creates the directory view file ACCOUNTS for the host directory /user/accounts or C:\user1\accounts, as appropriate.

Now use the LIST command to list items in the directory view file ACCOUNTS. Enter:

LIST ACCOUNTS

The following list is displayed:

ACCOUNTS...

invoice109
invoice110
invoice111

Note that the directory view file contains an item for each of the three invoice text files in the accounts directory, but not for the sub-directories log and vat.

Now enter:

CT ACCOUNTS invoice109

This displays the contents of the host file invoice109 in Reality item format.

You can transfer data between the host environment and a Reality database using the COPY TCL command; for example:

COPY BP DBPROG
TO: (ACCOUNTS

exports the DataBasic program DBPROG into a file in /user1/accounts.

Conversely,

COPY ACCOUNTS invoice109
TO: (INVOICES

imports the file invoice109 into database as an item in the file INVOICES.