Documents: 4.1 Advanced DC Usage: Document Protocols

MSG_META_DOC_OUTPUT_OPEN_EARLIER_COMPATIBLE_DOCUMENT, MSG_META_DOC_OUTPUT_OPEN_EARLIER_INCOMPATIBLE_DOCUMENT, MSG_GEN_DOCUMENT_OPEN_EARLIER_COMPATIBLE_DOCUMENT, MSG_GEN_DOCUMENT_OPEN_EARLIER_INCOMPATIBLE_DOCUMENT

One difficulty in upgrading software is that an obsolete program may have created many documents. If the new version can't read those documents, people who used the old version will be inconvenienced; however, if the new versions always use the same document formats as the old versions, options for improvement will be limited. Above all, if document formats change, the new version should detect this gracefully, without crashing or damaging the old file.

The header for a GEOS Virtual Memory file contains two words for protocol numbers. The document control objects use the protocol numbers to insure that a document is compatible with the version of the application which is opening it. There are two parts to the protocol number: the major protocol number, and the minor protocol number. (If a document has a major protocol number of 3 and a minor number of 11, it is referred to has having protocol 3.11.) By convention, versions of an application with entirely compatible document formats will have the same major protocol number; if a new version of an application cannot read older documents without converting them in some way, it will have a higher major protocol number, and the minor number will be reset to zero.

When the GenDocumentGroup object opens a file, it checks the major and minor protocol numbers. It will then take appropriate action:

If the document's major and minor protocol numbers match the protocol attributes of the GenDocumentGroup object, the document will be opened normally.
If the document has a higher protocol number than the GenDocumentGroup (i.e. either the document has a higher major protocol number, or the document and the GenDocumentGroup have the same major protocol number and the document has a higher minor protocol number), the document control will display an appropriate alert box, after which it will close the file and delete the document object. (It will do all of this automatically, without any attention from the application.)
If the document has lower major protocol number than the document control, the document control will send MSG_META_DOC_OUTPUT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT (and a corresponding MSG_GEN_DOCUMENT_... ). If neither message is handled, or if a handler returns an error, the document control will display an alert box and will close the file and delete the document object.
If the document has the same major but a lower minor protocol number than the GenDocumentGroup, the document control will send MSG_META_DOC_OUTPUT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT (and a corresponding MSG_GEN_DOCUMENT_... ). After this, it will proceed normally, whether the messages were handled or not (since the document is presumed to be compatible). If a handler returns an error, it will close the file and free the document object.

Note that the document control will not change the file under any of these circumstances. In particular, if it opens an earlier document, it will not change the document's protocol number. If the application wishes to do this, it should do it explicitly (generally in the handlers for the "UPDATE_..._DOCUMENT " messages). The protocol numbers are among a file's extended attributes. For information about changing extended attributes, see the File System chapter.

MSG_META_DOC_OUTPUT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT

Boolean	MSG_META_DOC_OUTPUT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT(
        word *		error, 			/* Return error code from FileError */
        optr 		document,			/* pointer to document object */
        FileHandle 		file); 			/* handle of file opened */

The GenDocumentGroup object sends this message to its output when the user tries to open a document with the same major protocol number as the document control and a lower minor protocol number. Applications will commonly respond to this message by changing the document's protocol number to bring it up-to-date. If the application can't use the document, it should return true and set *error . (File access error codes are members of the FileError enumerated type, defined in file.h .) With an error, the document control will close the document unchanged. If the application successfully updates the document, it should return zero and set *error to zero.

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: You must write a handler for this message in whatever class will be receiving it (usually the process class).

MSG_GEN_DOCUMENT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT

Boolean	MSG_GEN_DOCUMENT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT(
        word *	error); /* Return error code from FileError type */

The document object sends this message when the user tries to open a document with the same major protocol number as the document control and a lower minor protocol number. Applications will commonly respond to this message by changing the document's protocol number to bring it up-to-date. If the application can't use the document, it should return true and put an error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .) With an error, the document control will close the document unchanged. If the application successfully updates the document, it should return zero and set *error to zero.

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).

MSG_META_DOC_OUTPUT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT

Boolean	MSG_META_DOC_OUTPUT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT(
        								/* Return true if error */
        word *error, /* Return error code from FileError enum. type */
        optr document, /* pointer to document object */
        FileHandle file); /* handle of file opened */

The GenDocumentGroup object sends this message to its output when the user tries to open a document with a lower major protocol number than the document control. Applications respond to the message by making any changes to the document necessary to make it compatible with the application. The application should also change the document's protocol numbers. If the application can't use the document, it should return true and put an error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .) With an error, the document control will close the document unchanged. If the application successfully updates the document, it should return zero and set *error to zero.

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: You must write a handler for this message in whatever class will be receiving it (usually the process class)

MSG_GEN_DOCUMENT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT

Boolean	MSG_GEN_DOCUMENT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT(
        word *	error); /* Return error code from FileError type */

The document object sends this message when the user tries to open a document with a lower major protocol number than the document control. Applications respond to this message by making any changes to the document necessary to make it compatible with the application. The application should also change the document's protocol numbers. If the application can't use the document, it should return true and put an error code in *error . (File access error codes are members of the FileError enumerated type, defined in file.h .) With an error, the document control will close the document unchanged. If the application successfully updates the document, it should return zero and set *error to zero.

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).

GEOS SDK TechDocs |

4 Advanced DC Usage | Next:

4.2 Multiple Document Model