Documents: 4.3 Advanced DC Usage: Working with DOS files

MSG_META_DOC_OUTPUT_PHYSICAL_SAVE, MSG_GEN_DOCUMENT_PHYSICAL_SAVE, MSG_META_DOC_OUTPUT_PHYSICAL_UPDATE, MSG_GEN_DOCUMENT_PHYSICAL_UPDATE, MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE, MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS_FILE_HANDLE, MSG_META_DOC_OUTPUT_PHYSICAL_REVERT, MSG_GEN_DOCUMENT_PHYSICAL_REVERT

The document control can be used to handle DOS files. However, there are special issues to be aware of. When you use GEOS Virtual Memory files, the system takes care of swapping sections of the file in and out of memory as needed. You can use high-level commands to mark parts of the file as dirty, and when you need the document saved, only the dirty sections will be copied to the disk. The details of reading from and writing to the disk are transparent to the application.

When you use DOS files, on the other hand, you have to take care of all of these details yourself. It is usually impractical to keep all of a document in memory at one time, so you have to have some way of managing the data (perhaps by creating a temporary VM file and copying the DOS file into that).

For this reason, the document control sends out messages when it does many low-level things (such as save files). If the application needs to take special actions, it can define handlers for these messages. Most of these messages can be ignored if you are working with GEOS files.

If you want to implement "Save As" and "Revert" for DOS files, you will have to do most of it by hand. If you leave "Save As" and "Revert" enabled, the Document Control will do some of the work for you. For example, when the user chooses "Save As", the Document Control will first present a File Selector, letting the user choose a file name and location. The Document Control will then create the new file. After this it will send out MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE and MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS_FILE_HANDLE, passing the handle of the newly-created file. The application is responsible for writing the current version of the document to the new file, and reverting the original file to its last-saved state. The Document Control will automatically close the original file and update all Document Control instance data as necessary.

MSG_META_DOC_OUTPUT_PHYSICAL_SAVE

Boolean	MSG_META_DOC_OUTPUT_PHYSICAL_SAVE(
        word *		error, 
        optr 		document,
        FileHandle 		file);

If you need to take special steps to save a file, you should have a handler for either this message or MSG_GEN_DOCUMENT_PHYSICAL_SAVE . The handler should write the file completely to the disk. If an error occurs, return true and write the error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .)

If, for example, you copy a DOS file into a temporary VM file while you work on it, you would probably respond to this message by copying the data from the temporary file back to the DOS file.

Source: The GenDocumentGroup object.

Destination: Output of GenDocumentGroup (usually the Process object).

Parameters: error A pointer to a word in which an error should be returned.

document: The optr of the appropriate document object.
file: The FileHandle of the appropriate file.

Interception: DOS-based applications must handle either this message or MSG_GEN_DOCUMENT_PHYSICAL_SAVE . Applications which use GEOS data files will generally not intercept this message.

Return: true if error occurs.

*error: FileError code (or zero if there is no error).

MSG_GEN_DOCUMENT_PHYSICAL_SAVE

Boolean	MSG_GEN_DOCUMENT_PHYSICAL_SAVE(
        word *	error); 		/* Error code from FileError type */

This message is sent when the user saves a file. If you need to take special steps to save a file, you should have a handler for either this message or MSG_META_DOC_OUTPUT_PHYSICAL_SAVE . The handler should write the file completely to the disk. If an error occurs, return true and write the error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .)

If, for example, you copy a DOS file into a temporary VM file while you work on it, you would probably respond to this message by copying the data from the temporary file back to the DOS file.

Source: The GenDocument object.

Destination: The document object sends this message to itself.

Parameters: error A pointer to a word in which an error should be returned.

Return: true if error occurs.

*error: FileError code (or zero if there is no error).

Interception: DOS-based applications must handle either this message or MSG_META_DOC_OUTPUT_PHYSICAL_SAVE . Applications which use GEOS data files will generally not intercept this message.

MSG_META_DOC_OUTPUT_PHYSICAL_UPDATE

Boolean	MSG_META_DOC_OUTPUT_PHYSICAL_UPDATE(occurred */
        word *		error, 			/* Error code from FileError type */
        optr 		document,			/* Pointer to document object */
        FileHandle 		file);			/* Handle of DOS file */

This message is sent when the file is auto-saved (if this is enabled), and when the document is detached as part of a GEOS shutdown. If you need to take special steps to save a file, you should have a handler for either this message or MSG_GEN_DOCUMENT_PHYSICAL_UPDATE . The handler should write the file completely to the disk. If an error occurs, return true and write the error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .)

If, for example, you copy a DOS file into a temporary VM file while you work on it, you would probably respond to this message by copying the data from the temporary file back to the DOS file.

Source: The GenDocumentGroup object.

Destination: Output of GenDocumentGroup (usually the Process object).

Parameters: error A pointer to a word in which an error should be returned.

document: The optr of the appropriate document object.
file: The FileHandle of the appropriate file.

Return: true if error occurs.

*error: FileError code (or zero if there is no error).

Interception: DOS-based applications which will have auto-save capability must handle either this message or MSG_GEN_DOCUMENT_PHYSICAL_UPDATE . Applications which use GEOS data files will generally not intercept this message.

MSG_GEN_DOCUMENT_PHYSICAL_UPDATE

Boolean	MSG_GEN_DOCUMENT_PHYSICAL_UPDATE(
        word *	error); 		/* Error code from FileError type */

This message is sent when the file is auto-saved (if this is enabled), and when the document is detached as part of a GEOS shutdown. If you need to take special steps to save a file, you should have a handler for either this message or MSG_META_DOC_OUTPUT_PHYSICAL_UPDATE . The handler should write the file completely to the disk. If an error occurs, return true and write the error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .)

If, for example, you copy a DOS file into a temporary VM file while you work on it, you would probably respond to this message by copying the data from the temporary file back to the DOS file.

Source: A GenDocument object.

Destination: The document object sends this message to itself.

Parameters: error A pointer to a word in which an error should be returned.

Return: true if error occurs.

*error: FileError code (or zero if there is no error).

Interception: DOS-based applications which will have auto-save capability must handle either this message or MSG_META_DOC_OUTPUT_PHYSICAL_UPDATE . Applications which use GEOS data files will generally not intercept this message.

MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE

Boolean	MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE(
        word *		error,
        optr		document,
        FileHandle		file);

This message is sent when the Document Control is ready to "save-as" a DOS file. The Document Control will have asked the user what the new file should be, and will have created an appropriate file. The handler for this message must write the current version of the document to the new file, and restore the original file to its last-saved state.

Source: The GenDocumentGroup object.

Destination: The output of GenDocumentGroup (usually the Process object).

Parameters: error A pointer to a word in which an error code should be returned.

document: The optr of the appropriate document object.
file: The handle of the newly-opened file. The current version of the document should be saved to this file.

Return: true if an error occurred.

*file: A member of the FileError enumerated type (if an error occurred).

Interception: DOS-file applications must intercept this message (or MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS_FILE_HANDLE) if they wish to implement save-as/revert functionality.

MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS_FILE_HANDLE

Boolean	MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS_FILE_HANDLE(
        word *		error,
        FileHandle		file);

Source: A GenDocument.

Destination: The GenDocument object sends this message to itself.

Parameters: error A pointer to a word in which an error code should be returned.

file: The handle of the newly-opened file. The current version of the document should be saved to this file.

Return: true if an error occurred.

*error: A member of the FileError enumerated type (if an error occurred).

Interception: DOS-file applications must intercept this message (or MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE) if they wish to implement save-as/revert functionality.

MSG_META_DOC_OUTPUT_PHYSICAL_REVERT

Boolean	MSG_META_DOC_OUTPUT_PHYSICAL_REVERT(
        word *		error,
        optr		document,
        FileHandle		file);

The Document Control sends this message to revert a DOS file to its last-saved state. The handler must restore the file to its condition as of the last time it was saved.

Source: The GenDocumentGroup object.

Destination: The output of GenDocumentGroup (usually the Process object).

Parameters: error A pointer to a word in which an error should be returned.

document: The optr of the appropriate document object.
file: The FileHandle of the appropriate file.

Return: true if error occurs.

*error: FileError code (or zero if there is no error).

Interception: DOS-file applications must intercept this message (or MSG_GEN_DOCUMENT_PHYSICAL_REVERT) if they wish to implement save-as/revert functionality.

MSG_GEN_DOCUMENT_PHYSICAL_REVERT

Boolean	MSG_GEN_DOCUMENT_PHYSICAL_REVERT(
        word *		error,
        FileHandle		file);

The Document Control sends this message to revert a DOS file to its last-saved state. The handler must restore the file to its condition as of the last time it was saved.

Source: The GenDocumentGroup object.

Destination: The output of GenDocumentGroup (usually the Process object).

Parameters: error A pointer to a word in which an error should be returned.

file: The FileHandle of the appropriate file.

Return: true if error occurs.

*error: FileError code (or zero if there is no error).

Interception: DOS-file applications must intercept this message (or MSG_META_DOC_OUTPUT_PHYSICAL_REVERT) if they wish to implement save-as/revert functionality.

GEOS SDK TechDocs |

4.2 Multiple Document Model | Next:

4.4 Special-Purpose Messages