System Documents

All the documents and applications you use on your computer are stored as files on the hard disk(s) connected to or mounted on your machine, or floppy disk(s) or other similar permanent storage devices. Within 4D, we use the terms file or document to refer to these documents and applications. However, most commands in this theme use the term "document" because most of the time you will use them to access documents (rather than application or system files) on disk.

A hard disk can be formatted as one or several partitions, each of which is called a volume. It does not matter if two volumes are physically present on the same hard disk; at the 4D First level, you will usually treat these volumes as separate and equal entities.

A volume can be located on a hard disk physically connected to your machine or mounted over the network through a file sharing protocol such as TCP/IP, AFP ou SMB (Macintosh). Whatever the case, when using the System Documents commands at the 4D level, you treat all these volumes in the same way (unless you know what you are doing and use Plug-ins to extend the capability of your application in that domain).

Each volume has a volume name. On Windows, volumes are designated by a letter followed by a colon. Usually C: and D: are used to designate the volumes you use for booting your system (unless you configure your PC otherwise). Then the letters E: through Z: are used for the additional volumes connected or mounted to your PC (DVD drives, additional drives, network drives, and so on). On Macintosh, volumes have natural names; these are the names you see on the desktop at the Finder level.

Normally, you classify your documents into folders, which themselves can contain other folders. It is not a good idea to accumulate hundreds or thousands of files at the same level of a volume; it is messy and it slows down your system. On Windows, a folder is (or was) called a directory. Folders have always been called so on the Macintosh.

To uniquely identify a document, you need to know the name of the volume and the name(s) of the folder(s) where the document is located as well as the name of the document itself. If you concatenate all these names, you get the pathname to the document. Within this pathname, folder names are separated by a special character called the folder separator symbol. On Windows, this character is the backslash (\); on Macintosh it is the colon (:).

Let's look at an example. You have a document Important Memo located in the Memos folder, which is located in the Documents folder, which is located in the Current Work folder.

On Windows, if the whole thing is located on the C: drive (volume), the pathname of the document is:

C:\Current Work\Documents\Memos\Important Memo.TXT

Note: The \ character is also used by the method editor of 4D to designate escape sequences. In order to avoid any interpretation problems, the editor automatically transforms pathnames such as C:\Disk into C:\\Disk. For more information, refer to the paragraph below titled “Specifying Document names or Document pathnames”.

On Macintosh, if the whole thing is located on the disk (volume) Internal Drive, the pathname of the document is:

Internal Drive:Current Work:Documents:Memos:Important Memo

On Windows, the name of the document is suffixed with .TXT; we will see why in the next section.

Whatever the platform, the full pathname of a document can be expressed as follows:

VolName DirSep { DirName DirSep { DirName DirSep { ... } } } DocName

All the documents (files) located on volumes have several characteristics, usually called attributes or properties: the name of the document itself, the type and the creator.

A document is open in read/write mode, open in read-only mode or closed. Using the built-in 4D commands, a document can be opened in read/write mode by only one process at a time. One process can open several documents, several processes can open multiple documents, you can open the same document in read-only mode as many times as necessary, but you cannot open the same document in read/write mode twice at a time.

You open a document with the Open document, Create document and Append document commands. The Create document and Append document commands automatically open documents in read/write mode. Only the Open document command lets you choose the opening mode. Once a document is open, you can read and write characters from and to the document (see the RECEIVE PACKET and SEND PACKET commands). When you are finished with the document, you usually close it using the CLOSE DOCUMENT command.

All open documents are referred to using the DocRef expression returned by the Open document, Create document and Append document commands. A DocRef uniquely identifies an open document. It is formally an expression of the Time type. All commands working with open documents expect DocRef as a parameter. If you pass an incorrect DocRef to one of these commands, a file manager error occurs.

Note: When it is called from a preemptive process, a DocRef reference can only be used from this preemptive process. When it is called from a cooperative process, a DocRef reference can be used from any other cooperative process.

When you access (open, close, delete, rename, copy) documents, when you change the properties of a document or when you read and write characters in a document, I/O errors may occur. A document might not be found; it may be locked; it may be already open in write mode. You can catch these errors with an error-handling method installed with ON ERR CALL. Most of the errors that can occur while using system documents are described in the section OS File Manager Errors (-124 -> -33).

The commands Open document, Create document, Append document and Select document enable you to access a document using the standard Open or Save file dialog boxes. When you access a document through a standard dialog, 4D returns the full pathname of the document in the Document system variable. This system variable has to be distinguished from the document parameter that appears in the parameter list of the commands.

Additional information on the Document system variable can be found in the System Variables section.

Most of the routines of this section expecting a document name accept both a name or a pathname to the document (except when signaled otherwise). If you pass a name, the command looks for the document within the folder of the database. If you pass a pathname, it must be valid.

If you pass a wrong name or a wrong pathname, the command generates a file manager error that you can intercept using an ON ERR CALL method.

The method editor of 4D allows the use of escape sequences. An escape sequence is a set of characters that are used to replace a “special” character. The sequence begins with a backslash \, followed by a character. For example, \t is the escape sequence for the Tab character.

The \ character is also used as the separator in pathnames in Windows. In general, 4D will correctly interpret Windows pathnames that are entered in the method editor by replacing single backslashes \ with double backslashes \\. For example, C:\Folder will become C:\\Folder.

However, if you write C:\MyDocuments\New, 4D will display C:\\MyDocuments\New. In this case, the second \ is incorrectly interpreted as \N (an existing escape sequence). You must therefore enter a double \\ when you want to insert a backslash before a character that is used in one of the escape sequences recognized by 4D.

The following escape sequences are recognized by 4D:

Most commands for managing 4D documents and folders accept either relative or absolute pathnames:

• Relative pathnames define a location with respect to a folder located on disk. In 4D, a relative pathname is usually expressed with respect to the database folder, i.e. the folder containing the structure file. Relative pathnames are especially useful when deploying applications in heterogenous environments.
• Absolute pathnames define a location with respect to the root of the volume and so they do not depend on the current location of the database folder.

To determine whether a pathname passed to a command must be interpreted as absolute or relative, 4D applies a specific algorithm on each platform.

If the parameter contains only two characters and if the second one is a ':',
    or if the text contains ':' and '\' as the second and third character,
    or if the text starts with "\\",
then the pathname is absolute.       

In all other cases, the pathname is relative.

Examples with the CREATE FOLDER command:

If the text starts with a folder separator ':',
    or if does not contain any,
then the path is relative.

In all other cases, it is absolute.

Examples with the CREATE FOLDER command:

• Detecting on which platform you're running

Although 4D provides commands, such as MAP FILE TYPES, for eliminating coding variations due to platform specificities, once you start to work at a lower level when handling documents on disk (such as programmatically obtaining pathnames), you need to know if you are running on a Macintosh or a Windows platform.

The On Windows project method listed here tells whether your database is running on Windows:

• Extracting the file name from a long name

Once you have obtained the long name (pathname + file name) of a document, you may need to extract the file name of the document from that long name in order, for example, to display it in the title of a window. The Long name to file name project method does this on both Windows and Macintosh.

• Extracting the pathname from a long name

Once you have obtained the long name (pathname + file name) of a document, you may need to extract the pathname of the directory where the document is located from that long name; for instance, you may want to save additional documents at the same location. The Long name to path name project method does this on both Windows and Macintosh.