The English documentation to the

                      Document History Protocol

                             Revision 01
                               08.03.97

                                  by

                             Mark Wherry

                   mark.wherry@mail.inxpress.co.uk



Contents
========

 1  Introduction

 2  Document-History-Protocol

 3  Usage

 4  DHST_Add()

 5  Contact Me

 6  Legal



1  Introduction
***************

There are so many great innovations on the Atari platform to put more
and more features at the user's disposal, making life easier. As
programmers, most of us can't wait to add support for these new tricks
in our own programs. However there are two obstacles that often stand
in the way.

Most of the documentation for modern enhancements remains in German,
and any code available is usually written for Pure-C.

To try and make life easier for the programmer, here is my attempt at
a translation of the Document History Protocol specification, and a
binding for use with Lattice C5.



2  Document-History-Protocol
****************************

The aim of the Document History (DHST) protocol, is to maintain a
global list of the last documents to be used on the operating system.
These files are then made accessable from a uniform place (e.g. The
Start-Me-Up menu) to make retrieval quicker and easier for the user.

Here is the structure and values in C notation:

----------------------------------------------------------------------

#define DHST_ADD 0xdadd
#define DHST_ACK 0xdade

typedef struct{
  char *appname,
       *apppath,
       *docname,
       *docpath;
}DHSTINFO;

----------------------------------------------------------------------

Every time the user opens a file, the application should search for
the cookie 'DHST'. If this is available, the lower word of the cookie
value should hold the AES-ID of the DHST server (e.g. Start-Me-Up) to
send the DHST_ADD message to.

The application places a DHSTINFO-structure in global memory and fills
it with the corresponding data:

 appname:     The  name of the application
              (e.g. "Texel")

 apppath:     The absolute path of the  application
              (e.g. "c:\program\texel.app")

 docname:     The name of the document
              (e.g. "balmer.txl")

 docpath:     The absolute path of the document
              (e.B. "d:\data\balmer.txl")

The application then sends the DHST-Server the following message:

----------------------------------------------------------------------

msg[0]         DHST_ADD
msg[1]         ap_id
msg[2]         0
msg[3]+msg[4]  Pointer to the DHSTINFO-structure
msg[5]         0
msg[6]         0
msg[7]         0

----------------------------------------------------------------------

On receiving the following message, the application can then release
the global memory used:

----------------------------------------------------------------------

msg[0]         DHST_ACK
msg[1]         ap_id
msg[2]         0
msg[3]+msg[4]  Pointer to DHSTINFO-structure
               (As passed with DHST_ADD)
msg[5]         0
msg[6]         0
msg[7]         0=error(s), else: OK

----------------------------------------------------------------------



3  Usage
********

In order to use my binding in your program, do the following...

ú Link the file "DHST4LC.O" into your code, via the project manager.

ú Copy the file "DHST4LC.H" into your headers folder.

ú Add the line "#include <DHST4LC.H>" into your other includes.

And finally,

ú Add a DHST_Add() call whenever a user opens an existing file, or
creates a new one.



4  DHST_Add()
*************

*_Synopsis_*

retval = DHST_Add(app_id, app_name, app_path, doc_name, doc_path);

int retval;      Return value
int app_id;      AES id of the program calling DHST_Add()
char *app_name,  Name of the application
     *app_path,  Absolute path of the application
     *doc_name,  Name of the document
     *doc_path;  Absolute path of the document

*_Description_*

Formats the passed values into a DHSTINFO-structure and sends a
DHST_ADD AES message to the DHST server.

*_Returns_*

This function returns 1 if everything was OK, or 0 if an error
occured.



5  Contact Me
*************

If you have any suggestions, criticisms, want to beta test for me, or
just want a chat- here's my address:

Snail mail: 4 Fernpark Close,
            Topsham Road,
            Exeter,
            Devon,
            EX2 6AW
            England

Email: mark.wherry@mail.inxpress.co.uk



6  Legal
********

I do hate this bit, but everyone else seems to do it these days, so...

_Disclaimer_

The user uses this distribution at their own risk! I, or anyone
mentioned in this document, are not responsible for any damages you
may suffer through the use of the files in this distribution.

_Copyright_

You may freely copy this distribution so long as the contents are not
altered in any way. The Document History Protocol and the original
specification is the work of Thomas Much. This distribution and
translation is seperate, and the work of Mark Wherry.

Whew ;-)