System Documents

version 2003 (Modified)

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 4th Dimension, 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 NetBEUI (Windows) or AFP (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 A: and B: are used to designate the 5 1/4 or 3 1/2 floppy drives. Usually C: designates the volume you use for booting your system (unless you configure your PC otherwise). Then the letters D: through Z: are used for the additional volumes connected or mounted to your PC (CD-ROM drives, additional drives, network drives, and so on). On Macintosh, volumes have natural names whose maximal length is 31 characters; 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 directory (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:

Note: The \ character is also used by the method editor of 4th Dimension 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:

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:

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.

On Windows, a document has a type. On Macintosh, a document has a type and a creator. The type of a document generally indicates what the document is or what it contains. For instance, a text document contains some text (without style variations).

On Windows, the type of a document is determined by the suffix (called the file extension) attached to the document name. For instance, .TXT is the Windows file extension for text documents. On Macintosh, the type of a document is determined by the file type property, which is a 4-character signature (not displayed at the Finder level). For instance, the file type of a text document is "TEXT".

In addition, on Macintosh, a document has a creator, which designates the application that created the document. This concept does not exist on Windows. The creator of a document is determined by the file creator property, which is a 4-character signature (not displayed at the Finder level). For instance, the file creator of a document created by 4D V6 is "4D06".

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.

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.

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.

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.

Warning: The maximum length of the document parameter is 255 characters. If you pass a longer name, it will be truncated and a File manager error will be generated.

The method editor of 4th Dimension 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 under Windows. In general, 4th Dimension 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, 4th Dimension 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 4th Dimension.

The following escape sequences are recognized by 4th Dimension:

Although 4th Dimension 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:

      ` On windows Project Method
      ` On windows -> Boolean
      ` On windows -> True if on Windows

   C_BOOLEAN($0)
   C_LONGINT($vlPlatform;$vlSystem;$vlMachine)

   PLATFORM PROPERTIES($vlPlatform;$vlSystem;$vlMachine)
   $0:=($vlPlatform=Windows)

• Using the right directory separator symbol

On Windows, a directory level is symbolized by an backslash (\). On Macintosh, a folder level is symbolized by a colon (:). Depending on which platform you are running, the Directory symbol project method listed here returns the ASCII code of the correct directory symbol (character).

      ` Directory symbol Project Method
      ` Directory symbol -> Integer
      ` Directory symbol -> ASCII of "\" (Windows) or ":" (Mac OS)

   C_INTEGER($0)

   If (On Windows )
      $0:=Ascii("\\")
   Else 
      $0:=Ascii(":")
   End if 

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.

      ` Long name to file name Project Method
      ` Long name to file name ( String ) -> String
      ` Long name to file name ( Long file name ) -> file name

   C_STRING(255;$1;$0)
   C_INTEGER($viLen;$viPos;$viChar;$viDirSymbol)

   $viDirSymbol:=Directory symbol 
   $viLen:=Length($1)
   $viPos:=0
   For ($viChar;$viLen;1;-1)
      If (Ascii($1[[$viChar]])=$viDirSymbol)
         $viPos:=$viChar
         $viChar:=0
      End if 
   End for 
   If ($viPos>0)
      $0:=Substring($1;$viPos+1)
   Else 
      $0:=$1
   End if 
   If (<>vbDebugOn) ` Set this variable to True or False in the On Startup database method
      If ($0="")
         TRACE
      End if 
   End if 

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.

      ` Long name to path name Project Name
      ` Long name to path name ( String ) -> String
      ` Long name to path name ( Long file name ) -> Path name

   C_STRING(255;$1;$0)
   C_STRING(1;$vsDirSymbol)
   C_INTEGER($viLen;$viPos;$viChar;$viDirSymbol)

   $viDirSymbol:=Directory symbol 
   $viLen:=Length($1)
   $viPos:=0
   For ($viChar;$viLen;1;-1)
      If (Ascii($1[[$viChar]])=$viDirSymbol)
         $viPos:=$viChar
         $viChar:=0
      End if 
   End for 
   If ($viPos>0)
      $0:=Substring($1;1;$viPos)
   Else 
      $0:=$1
   End if 
   If (<>vbDebugOn) ` Set this variable to True or False in the On Startup database method
      If ($0="")
         TRACE
      End if 
   End if 

Append document, CLOSE DOCUMENT, COPY DOCUMENT, Create document, CREATE FOLDER, DELETE DOCUMENT, Document creator, DOCUMENT LIST, Document type, FOLDER LIST, Get document position, GET DOCUMENT PROPERTIES, Get document size, MAP FILE TYPES, MOVE DOCUMENT, Open document, Select document, SET DOCUMENT CREATOR, SET DOCUMENT POSITION, SET DOCUMENT PROPERTIES, SET DOCUMENT SIZE, SET DOCUMENT TYPE, Test path name, VOLUME ATTRIBUTES, VOLUME LIST.