Open document

version 6.8 (Modified)

Open document (document{; fileType{; mode}}) DocRef

The Open document command opens the document whose name or pathname you pass in document.

If you pass an empty string in document, the Open File dialog box is presented, and you then select the document to be open. If you cancel the dialog, no document is opened; Open document returns a null DocRef and sets the OK variable to 0.

• If the document is correctly opened, Open document returns its document reference number and sets the OK variable to 1.

• If the document is already open and the mode parameter is omitted, Open document opens the document in Read mode and sets the OK variable to 1.

• If the document is already open and you try to open it in Write mode, an error is generated.

• If the document does not exist, an error is generated.

On Macintosh, if you use the Open File dialog box, all documents are presented by default. To show another type of document, specify a document type in the optional fileType parameter.

On Windows, if you use the Open File dialog box, all types of documents *.* are presented by default. To show another type of document, in fileType, pass a 1 to 3-character Windows file extension or a Macintosh file type mapped using the MAP FILE TYPES command.

On Windows, even if you do not use the Open File dialog box, you might pass the fileType parameter to specify the file extension of the document you want to open. By default, Open document attempts to open a .TXT file. If you specify the fileType parameter, Open document tries to open the document whose name is "Document.fileType". For example:

   vhDocRef:=Open document("C:\\Letter";"WRI")

will try to open the document "C:\\Letter.WRI" on your disk. If you pass more than three characters in fileType, Open document only takes the first three characters into account. If a document type is not specified, Open document tries to open the document with no file extension. If it does not find it, it tries to open the document with the .TXT extension. If it still does not find it, it will return a "File not found" error.

If a document is open, Open document initially sets the file position at the beginning of the document while Append document sets it at the end of the document.

Once you have opened a document, you can read and write in the document using the RECEIVE PACKET and SEND PACKET commands that you can combine with the Get document position and SET DOCUMENT POSITION commands in order to directly access any part of the document.

The optional mode parameter allows you to define how document is to be opened. Four different open file modes are possible. 4th Dimension offers the following predefined constants, located in the "System Documents" theme:

Do not forget to eventually call CLOSE DOCUMENT for the document.

1. The following example opens an existing document called Note, writes the string "Good-bye" into it, and closes the document. If the document already contains the string "Hello", this string would be overwritten:

   C_TIME(vhDoc) 
   vhDoc:=Open document ("Note";Read and Write)   ` Open a document called Note 
   If (OK=1) 
      SEND PACKET (vhDoc"Good-bye")   ` Write one word into the document 
      CLOSE DOCUMENT (vhDoc)  ` Close the document 
   End if

2. You can now read a document even if it is already open in write mode:

   vDoc:=Open document ("PassFile";"TEXT") ` The file is open
      ` Before the file is closed, it is possible to consult it in read-only mode: 
   vRef:=Open document ("PassFile";"TEXT";Read Mode)

If the document is correctly opened, the OK system variable is set to 1; otherwise, it is set to 0. After the call, the Document system variable contains the full name of the document.

If you call Open document with a mode of 3, the function returns ?00:00:00? (no document reference). The document is not opened but the Document and OK system variables are updated:

• OK is equal to 1.

• Document contains either the name or the full pathname and the name of document, depending on the value passed in document (if you passed a file name, Document contains this name; if you passed a full pathname, Document contains this full pathname).

Note: If the file defined in document is not found or if you pass an empty string in document, an open file dialog box appears. If the user chooses a document and clicks the OK button, document is set to the path of the document the user selected and OK is set to 1. If the user clicked the Cancel button, OK is set to 0.

Append document, Create document.