
           TRANSMISSION DE DONNES ENTRE APPLICATIONS
            DOCUMENTATION RELATIVE AU PROTOCOLE GEM


Auteurs de ce protocole:
LAMBALLAIS Pierre-Louis    (Le Froce Lapin)
Ecole Publique
53110 Ste Marie du Bois
Tl:43.08.59.46

ALLEN Douglas            (Dad)
La Retardire
Rennes en Grenouille
53110 Lassay les Chateaux
Tl:43.08.51.00


 -- Fonctionnement / Point de vue de l'utilisateur --

 Par convention,  l'utilisateur dclenche toujours  l'application 
mtrice des donnes.  Ainsi un PRG traitement de texte  dsirant 
envoyer  un  texte  vers  un ACC qui  pourra  le  compacter  sera 
l'metteur.  Par  contre lorsque l'on voudra recharger  ce  texte 
compact,  c'est  l'accessoire qui sera l'metteur puisque  c'est 
lui qui enverra le fichier aprs l'avoir dcompact.
L'utilisateur dclenche donc l'application mtrice des  donnes, 
celle-ci  lui  propose  la liste des  applications  prsentes  en 
mmoire,  compatibles  avec  cette  srie de  protocole  et  donc 
suceptibles  de  recevoir  ces  donnes.   L'utilisateur  choisit 
l'application   rceptrice   et  le  transfert   se   fait   avec 
ventuellement   demande   de   paramtres   pour   l'application 
rceptrice.

 -- Fonctionnement / Point de vue du programmeur --
  Pour crire,  une application utilise la fonction APPL_WRITE   
laquelle  elle fournit l'APP_ID de l'application destinataire  du 
message,  la taille de celui-ci et son adresse.  Les applications 
compatibles  avec ce protocole noterons donc leur APP_ID dans  un 
tableau, dont l'adresse sera note dans le Cookie-Jar, avec comme 
identificateur _TUB.
Ce  systme de notation et d'utilisation sera fait avec  quelques 
rserves,  cause de l'existence de programmes tels que MULTIDESK 
ou  STUFFER,  mais  aussi afin d'envisager le cas  d'une  version 
multitche du GEM.

Le  tableau dans lequel seront nots les APP_ID des  applications 
compatibles avec ce protocole, sera compos comme ceci:
PROT           */ identificateur en ascii donc sur 4 octets */
NBR_APPID      */ nbr de slot de ce tableau (sur un word)   */
slot1          */ les slots contenant les APP_IDs           */
slot2          */ des applications compatibles              */
END_FLAG       */ indication de fin des APP_ID ($FFFF)      */
emplacement pour les autres APP_ID possibles.

NBR_APPID indique donc le nombre maxi d'APP_ID que peut  contenir 
le  tableau,  mais pas le nombre d'APP_ID en  place.  Le  dernier 
APP_ID est suivi d'un indicateur de fin (word  $FFFF). 
(ainsi  un  tableau pouvant contenir 10 APP_ID fera  en  tout  28 
octets)
     Comme dans le cas du Cookie-jar, il est tout  fait possible 
de fabriquer une nouvelle liste,  plus grande,  et d'y transfrer 
le  contenu de l'ancienne,  si une application voulant y  dposer 
son APP_ID s'apperoit qu'elle est pleine. 

     Il  convient  cependant  d'tre  trs  prudent:   il  faudra 
vrifier avant chaque transmission,  le bon tat du  tableau.  En 
effet, tout comme pour le Cookie-Jar, il est tout a fait possible 
que   des   applications   non-respectueuses   des   rgles    de 
programmation  viennent pitiner nos  plates-bandes!  C'est  trs 
gnant  car en cas de tentative d'criture par APPL_WRITE    une 
application inexistante, il y a plantage de la machine, le GEM ne 
renvoyant aucun numro d'erreur, mais juste quelques bombes...

     Une   vrification   de  l'en-tte   (PROT)   ainsi   qu'une 
vrification,  en  cours  de lecture du  tableau,  d'un  ventuel 
dbordement  (vit  en comptant les APP_ID lus et  en  comparant 
avec NBR_APPID) est donc fortement conseill!

  -- Initialisation / Point de vue d'un ACC --
L'accessoire va chercher dans le Cookie-Jar le cookie _TUB. Il en 
dduit  l'adresse  du tableau des APP_ID.  Il  vrifie  alors  la 
validit  de  ce tableau  l'aide de son  en-tte,  et  si  cette 
vrification  est  correcte,  il place son propre AP_ID  dans  la 
liste.  Le  cas des accessoire lancs avec Multidesk  ou  Stuffer 
doit  tre  prvu.  L'accessoire envisageage donc le cas  ou  son 
APP_ID  serait dja inscrit dans la liste,  auquel cas il  ne  le 
rajoute  pas.  Si  l'accessoire se rajoute,  il n'oublie  pas  de 
reculer le flag de fin ($FFFF). Si par hasard le tableau est dja 
plein  (on le vrifie en comptant les APP_ID de celui-ci  est  en 
comparant ce nombre avec NBR_APPID indiquant combien d'emplcament 
son  disponible),  l'accessoire   la possibilit  de  crer  une 
nouvelle liste d'APP_ID,  plus grande, d'y recopier le contenu de 
l'ancienne  puis  de noter son adresse dans le  Cookie-Jar    la 
place de l'adresse de l'ancienne liste.  Ceci explique  galement 
qu'il  faudra  demander   chaque transmission  l'adresse  de  la 
liste,  plutt  que  de  se fier  l'adresse  trouv  lors  d'une 
prcdente demande.  

S'il  estime  que  l'initialisation est  bonne  il  continue  son 
droulement normal.  Si par contre il estime que l'initialisation 
n'est  pas  correcte (par exemple s'il n'a pas trouv  de  Cookie 
_TUB,  ou  bien  si l'en-tte du tableau n'est pas bonne)  il  va 
crer un nouveau tableau et placer l'adresse de celui-ci, avec le 
Cookie _TUB,  dans le Cookie-Jar en crant ventuellement  celui-
ci.

 -- Initialisation / Point de vue d'un programme --
 Au dmarrage un PRG doit se dclarer, la liste ne comprenant que 
les  APP_ID des accessoires.  Il va donc chercher le cookie  _TUB 
dans le Cookie-Jar.  S'il ne le trouve pas,  il en dduit que  la 
transmission sera impossible,  idem si le Cookie-Jar existe  mais 
qu'il  ne  contient  pas de Cookie  _TUB.  Lorsque  le  programme 
possde  l'adresse du tableau pour le protocole,  il teste  l'en-
tte de celui-ci.  Si cette liste n'est pas valable, il abandonne 
(tant  un  programme il ne peut pas fabriquer de  liste  puisque 
celle-ci disparaitrait avec lui), sinon il y rajoute son APP_ID.
Lorsque  l'on quittera le programme,  celui-ci devra retirer  son 
APP_ID de la liste,  afin que les accessoires ne cherchent pas   
communiquer avec lui alors qu'il n'est plus en mmoire.
S'il n'y a plus de place dans la liste des APP_ID,  le  programme 
ne pourra pas tre appel.  Cependant rien ne l'empchera de lire 
cette  liste  et donc d'appeler  les  autres  applications.  Pour 
viter d'avoir une liste d'APP_ID pleines, les accessoire doivent 
en prvoir une assez grande.  Dans les exemples fournis sur cette 
disquette,  la liste d'APP_ID permet d'en recevoir 10.  Il serait 
normal  de songer  en mettre par exemple une de 16,  au  cas  ou 
celle  de  10  serait  pleine.  Il  est  galement  tout    fait 
envisageable  de  raliser un petit programme  plac  en  dossier 
AUTO,  qui fabriquerait une liste,  et pourquoi pas un Cookie-Jar 
ventuel (pour penser aux STF!). 

A  chaque fois qu'un programme tentera de placer son APP_ID  dans 
la liste,  il devra imprativement la parcourir afin de  vrifier 
si cet identificateur ne s'y trouve pas dja, ceci pour envisager 
le cas d'un programme ayant prcdement plac son APP_ID et ayant 
oubli de le retirer (cas d'un programme quittant par une  erreur 
par exemple).

 -- Prparation d'une transmission  -- 
L'application va chercher l'adresse du Cookie-Jar,  y cherche  le 
Cookie  _TUB,  et  en  dduit  l'adresse  du  tableau  Protocole. 
L'application vrifie l'en-tte de ce tableau.  Deux cas  peuvent 
se prsenter:
 1) donnes incorrectes: transmission impossible
 2) donnes correctes: dbut de communication

  Cette tape de prparation sera excute  chaque  fois  qu'une 
transmission  sera demande car il est tout   fait  envisageable 
qu'une application trangre vienne dtruire le tableau protocole 
(ou  mme le Cookie-Jar)  notre insu.  Il est donc impratif  de 
tout vrifier avant chaque transmission.

 -- COMMUNICATION ENTRE 2 APPLICATIONS  --
  L'application dsirant correspondre avec une autre  application 
est  donc  actuellement en possession de l'adresse  d'un  tableau 
contenant  les  APP_ID des applications actives  en  mmoire.  Ce 
tableau contient la liste des APP_ID, que ceux-ci appartiennent  
des  applications compatibles avec le protocole ou non.  (cas  de 
Multidesk ou d'autres lanceurs d'accessoires...)

Petite  explication pour multidesk:  celui-ci une fois  lanc  ne 
note pas son APP_ID dans la liste puisqu'il n'est pas compatible. 
Nous lanons ensuite grce  Multidesk,  un accessoire compatible 
avec le protocole.  Cet accessoire va donc noter son APP_ID  dans 
la  liste,  mais il s'agit en fait du mme APP_ID que  Multidesk. 
Lorsque nous quittons cet accessoire (il disparait de la  mmoire 
  cause  de Multidesk),  son APP_ID reste dans  la  liste.  Nous 
allons  donc  envoyer des messages  Multidesk,  en  croyant  les 
envoyer  une application compatible!

 Le communication va pouvoir commencer,  en utilisant la fonction 
APPL_WRITE.  L'application recevant le message sera en mesure  de 
le lire aprs un EVNT_MESAG ou bien un EVNT_MULTI.  Le  protocole 
consiste en fait  se mettre d'accord sur les numros de  message 
que  nous  allons  utiliser et sur le  format  de  ces  messages. 
Toujours par convention nous avons attribu aux messages mis par 
les applications engageant la conversation,  des numros  paires. 
L'application  rpondant  envoyant des  messages  impaires.  Nous 
avons mis au point 3 sries de codes.

  La  premire srie est utilise pour  transmettre  des  donnes 
(change de blocs mmoires divers) et ces messages sont numrots 
 partir de 300.
   La  seconde  srie  est  utilise  pour  l'change  de   menus  
droulants.  Son utilisation permet  un ACC d'avoir un vritable 
menu  droulant GEM,  classiquement fabriqu avec un  diteur  de 
ressource  et gr tout aussi classiquement.  Ces  messages  sont 
numrots  partir de 400.
   La  troisime  srie  est  utilise  pour  le   pilotage   des 
applications.  Avec cette srie de messages, une application peut 
en  piloter  une  autre.  Ainsi un  ACC  pourra  automatiser  les 
procdures de recherches d'une base de donnes,  par exemple. Les 
messages de cette srie sont numrots  partir de 500.

 Vous trouverez ci-joint la liste et la description des  messages 
du   protocole,   ainsi  que  les  listings  en   assembleur   de 
l'initialisation vue par un ACC, l'initialisation vue par un PRG, 
la prparation des transmissions, etc... Vous trouverez galement 
le listing d'un ACC et d'un PRG s'changeant des documents,  ceux 
d'un ACC et d'un PRG dont le second gre le menu du  premier,  et 
enfin  ceux  d'un ACC et d'un PRG dont le premier  dclenche  les 
routines  de  dessins du second.  Il est bien vident  qu'il  est 
possible  de  raliser des applications rpondant    toutes  ces 
fonctions, mais ces listings n'tant que des exemples, nous avons 
jug plus clair de montrer sparement les possibilits.

     Bonne utilisation de ce protocole !!!

