
                    RSUM  DES MESSAGES
          DU PROTOCOLE DE  COMMUNICATION  GEM 

Dans  tout  ce  qui suit,  les nombres en  hxadcimaux  sont  en 
notation assembleur, c'est  dire prcd simplement du signe $.
A vous de rectifier suivant votre langage de programmation.

Avant de commencer,  une remarque pour les programmeurs en  Basic 
(entre  autre  le GFA).  Le type de variable t& est  cod  sur  2 
octets  avec signe.  Ceci gnre des comportements  qui  mritent 
notre  attention:  le  flag  de fin de  la  liste  Protocole  est 
constitu  de  deux  octets formant le  mot  &HFFFF.  Or  il  est 
impossible  d'affecter  une  telle  valeur    une  variable  '&' 
(t&=&HFFFF  est  impossible).  Par  contre  il  est  possible  de 
raliser un test du genre IF Dpeek(truc%)=&HFFFF.  Ceci  explique 
que vous trouverez parfois &HFFFF dans les listings, mais d'autre 
fois -1,  suivant qu'il s'agit d'affecter une variable ou bien de 
jouer    Peek  et  Poke  dans  les  zones  mmoires  des  autres 
applications. Idem pour les valeurs &HFFFD et &HFFFE servant pour 
les messages de type 500 (voir le listing d'ACC_500).

   Par convention l'utilisateur dclenche toujours  l'application 
devant  mettre  les informations.  Les messages mis  par  cette 
application  (application  mtrice) auront des  numros  paires. 
Ceux mis par l'application destinataire (devant donc globalement 
recevoir les informations) auront des numros impairs.  Dans  ces 
messages, conformement  la norme GEM, le second mot est l'APP_ID 
de  l'application qui crit le message.  Dans les  documents  qui 
suivent nous avons not "E" l'APP_ID de l'application mtrice et 
"D" celui de l'application rceptrice. Le troisime mot, toujours 
conformement  la norme GEM, donne la taille du message - 16. Nos 
messages tant toujours sur 16 octets, cette taille sera toujours 
  0.  Par  dfaut  les donnes sont codes sur  un  mot  (word=2 
octets).  Lorsqu'elle  sont sur 4 octets (Long mot),  elles  sont 
suivies  de  .L.   Sous  chaque  message  se  trouve  une  petite 
explication concernant celui-ci.

    A la suite de chaque message nous avons indiqu  si  celui-ci 
devait   obligatoirement   engendrer  une  rponse   de   l'autre 
application,  en indiquant les numros de messages valables  pour 
cette rponse.  Le signe X signifie qu'il est possible de ne  pas 
rpondre.  La  distinction est trs importante.  Une rponse  qui 
devra obligatoirement venir sera attendu par Evnt_mesag,  ce  qui 
bloquera l'application jusqu' rception de celle-ci. Dans le cas 
d'une  rponse  simplement ventuelle  (cas  "X"),  l'application 
attendra avec Evnt_multi afin de ne pas tre  bloque.  L'attente 
se fera donc conjointement avec Evnt_mesag et Evnt_timer avec  un 
temps   d'attente  de 5 diximes de seconde.   Ce  temps   de   5 
diximes  de  seconde est suffisement long pour permettre    une 
application "lente" de rpondre. Afin de rduire le plus possible 
le  temps  d'attente,  il est souhaitable  que  les  applications 
rpondent   plutt   que  de   laisser   l'application   mtrice 
"patienter" durant tout ce temps.   cette fin,  dans chacune des 
sries du protocole,   nous avons prvu un message (301,  401  ou 
501)  permettant d'indiquer  l'application mtrice le refus  de 
recevoir  les  messages de cette  srie.  Ainsi  une  application 
n'acceptant  que les messages de la srie  300,  devra  nanmoins 
rpondre  par "401"  un message 400,  et par "501"  un  message 
500, ce qui rduira le temps d'attente.

    Note:  Nous  avons  essay d'utiliser  le  mme  principe  de 
numrotation pour les diffrentes sries du Protocole.  Ainsi les 
'Fins de Communication's sont indiques par'308', '408' ou '508', 
les 'Abondons' par '309',  '409' ou '509', etc... Sachant que les 
trois sries possdent des fonctions diffrentes,  il est  normal 
que  certains  numros de messages soient  manquants.  Ainsi  les 
numros '402' et '404', par exemple, n'existent pas.

--> MESSAGES DE TRANSMISSIONS DE DONNEES (Srie 300)

300,E,0,0,0,0,0,0 (X ou 301 ou 303)
  Es-tu compatible avec la srie de messages type 300 ?

301,D,0,0,0,0,0,0 (X)
  Non, je ne suis pas compatible avec les messages type 300 !

302,E,0,0,0,0,0,0 (305 ou 309)
    Je  vais  peut-tre  communiquer  avec   toi.    Demande     
l'utilisateur s'il est d'accord et si tu as des prcisions   lui 
demander, vas-y.

303,D,0,ADR_DESCRIP.L,0,0,0 (X ou 302 ou 304)
    Oui,  je suis compatible avec les messages  type  300.  Voici 
l'adresse  de  ma  liste  de  descripteurs  (Voir  plus  loin  la 
structure de cette liste)

304,E,0,NUM_DESCRIP.W,0,0,0,0 (305 ou 309)
  J'ai transmit  l'utilisateur ta liste de descripteurs,  tu  as 
t  choisit  pour  communiquer,  et  plus  particulirement  ton 
descripteur numro NUM_DESCRIP (attention, cod sur un word!). Si 
tu  as  des  prcisions    demander    l'utilisateur  avant  la 
transmission, vas-y.

305,D,0,0,0,0,0,0 (306 ou 308)
   Toutes les ventuelles prcisions ont t demandes,  je  suis 
prt  recevoir les donnes.

306,E,0,NBR_CPL_DATA.L,ADR_TAB_DATA.L,0 (305 ou 307 ou 309)
   Voici les donnes.  Tu trouveras dans ce message le nombre  de 
couples de ce tableau de donnes et l'adresse de ce tableau (Voir 
plus loin le descriptif sur la structure du tableau de donnes).

307,D,0,0,0,0,0,0 (306 ou 308)
    J'ai  fait  une erreur !   S'il te plat  rpte  le  dernier 
tableau.

308,E,0,0,0,0,0,0 (X)
  La transmission des donnes est termine.

309,D,0,0,0,0,0,0 (X)
   J'abandonne la rception (par ex.  buffers  pleins,  problmes 
disquette etc...)

DESCRIPTIF DES TABLEAUX UTILISES POUR LE PROTOCOLE SRIE 300

Structure liste des descripteurs.
   Cette liste contient des phrases de 32 octets  chacune.  A  la 
suite du dernier octet de chaque phrase, on ajoute deux octets de 
valeur $00,  sauf pour la dernire phrasee qui,  elle, est suivie 
d'un  octet   $00 et d'un octet  $FF.  Cette suite  de  phrases 
donne  la  description  des diffrents lieux  de  rception  dans 
lesquels  l'application accepte de recevoir  des  donnes.  Cette 
description  doit tre simple mais prcise.  Les phrases  doivent 
employer des codes ASCII 'classiques' (pas de codes de  controls) 
car  l'application  qui  recevra l'adresse  de  cette  liste  est 
suceptible   d'afficher   les  phrases  pour  les   prsenter    
l'utilisateur. Exemple en assembleur:

DESCRIPTEUR  DC.B   "Transforme texte --> 1stWord ",0,0
       DC.B   "Transforme texte --> ASCII  ",0,0
       DC.B   "Transforme texte --> Signum  ",0,$FF

La mme chose en basic:

A$="Transforme texte --> 1stWord " + CHR$(0) + CHR$(0)
B$="Transforme texte --> ASCII  " + CHR$(0) + CHR$(0)
C$="Transforme texte --> Signum  " + CHR$(0) + CHR$(255)

DESCRIPTEUR$=A$+B$+C$
Il  faut utilise bien sr l'adresse de ce  descripteur,  c'est   
dire Varptr(descripteur$).

  Lorsque l'application reoit l'adresse de cette liste, elle lit 
les phrases pour les prsenter,  et  la lecture, les numrotes  
partir  de 0.  Ainsi le descripteur "Transforme texte -->  ASCII" 
portera  le numro 1.  Si c'est ce descripteur qui a t  choisit 
par l'utilisateur il y aura donc une transmission de message  304 
avec pour valeur de NUM_DESCRIP le chiffre 1 (il s'agit bien de 1 
et  non pas du code ASCII de "1").  Si c'est "-->  1stWord"  nous 
aurons NUM_DESCRIP=0 etc...
   Note:  NUM_DESCRIP est cod sur un Word (2 octets) et non  pas 
sur un long.

  Structure tableau des donnes.
   Ce tableau contient les tailles des donnes et leur  adresses. 
Exemple:  nous  voulons transmettre en une seule fois  5  images. 
Nous  allons donc transmettre en fait l'adresse d'un tableau  qui 
contiendra: Taille premire image (sur 4 octets) Adresse premire 
image (sur 4 octets) Taille seconde image (sur 4 octets)  Adresse 
seconde image (sur 4 octets) etc...  ce qui permet de transmettre 
en  une seule fois de trs nombreux paquets de donnes.  Dans  le 
message 306, ADR_TAB_DATA.L c'est donc l'adresse de ce tableau et 
NBR_CPL_DATA.L  c'est  le  nombre de  couples  contenus  dans  ce 
tableau.  Dans le cas par exemple de la transmission de 5 images, 
NBR_CPL_DATA.L vaudra 5.


--> MESSAGES DE TRANSMISSIONS DE MENUS DEROULANTS (Srie 400)

400,E,0,0,0,0,0,0 (X ou 401 ou 403)
   Es-tu compatible avec la srie de messages type 400,  c'est   
dire peux-tu grer mon menu droulant ?

401,D,0,0,0,0,0,0 (X)
  Non, je ne suis pas compatible avec cette partie du protocole 
!

403,D,0,0,0,0,0,0 (X ou 406 ou 408)
  Oui, je suis compatible avec cette partie du protocole, tu peux 
m'envoyer l'adresse de ton menu.

405,D,0,0,0,0,0,0 (408)
  Ok,  j'ai bien reu ton menu,  je l'ai mis en place et je  suis 
prt  te transmettre les informations.

406,E,0,ADR_MENU.L,0,0,0 (405 ou 409)
   Voici donc l'adresse de mon menu droulant,  adresse que  j'ai 
trouv avec la fonction RSRC_GADDR. Prpare toi tranquillement et 
met le en place.

407,D,0,Index du titre,Index de l'article,0,0,0 (X ou 408)
  Un vnement menu est survenu.  Comme je sais que ce menu est  
toi,  je te transmet les informations que j'ai reu du GEM  (Mme 
format)

408,E,0,0,0,0,0,0 (X)
  Je n'ai plus besoin que tu gres mon menu,  tu peux remettre le 
tien.

409,D,0,0,0,0,0,0 (X)
  J'ai dsactiv ton menu,  tu ne recevras donc plus de  messages 
dcrivant les actions dans celui-ci

    Avec cette srie de messages,  nous pouvons imaginer  le  cas 
suivant:  PRG  Traitement de Textes,  ACC Tableur,  ACC  Base  de 
Donnes, chacun avec une fentre prsente  l'cran. L'activation 
de la fentre du tableur entraine l'envoi de l'adresse du menu de 
celui-ci  vers  le PRG,  qui se met alors   le  grer.  Lors  de 
l'activation  de  la  fentre de la  base  de  donnes,  celle-ci 
enverra l'adresse de son menu au PRG.  Celui-ci dsactivera  donc 
le menu en place (celui du tableur),  avec un message "409", puis 
activera celui de la base de donnes.


--> MESSAGES DE DECLENCHEMENTS DE ROUTINES (Srie 500)

500,E,0,0,0,0,0,0 (X ou 501 ou 503)
   Es-tu compatible avec la srie de messages type 500,  c'est   
dire puis-je t'envoyer des ordres pour dclencher tes routines ?

501,D,0,0,0,0,0,0 (X)
  Non, je ne suis pas compatible avec cette partie du protocole !

503,D,0,ADR_DESCRIPTIF.L,0,0,0 (X ou 506 ou 508)
   Oui, je suis compatible avec les messages de type 500. Je peux 
donc  recevoir  la  liste des ordres  pour  mes  routines.  Voici 
l'adresse  de  mon  descripteur.  (voir plus  loin  note  sur  ce 
descripteur.)

505,D,0,ADR_RETOUR.L,0,0,0 (506 ou 508)
    J'ai fini de lire ta liste d'ordres,  voici l'adresse  de  la 
liste des paramtres de retour.

506,E,0,ADR_TAB_ROUTINE.L,0,0,0 (505 ou 507 ou 509)
    Voici  l'adresse  de la liste d'ordres  pour  dclencher  tes 
routines (Voir plus loin le descriptif de cette liste)

507,D,0,0,0,0,0,0 (506 ou 508)
    J'ai  fait  une erreur en lisant  la  liste,  peux-tu  me  la 
renvoyer...

508,E,0,0,0,0,0,0 (X)
     C'est fini, je n'ai plus de liste d'ordres  te transmettre

509,D,0,ADR_RETOUR.L,0,0,0 (X)
    Grave  erreur  durant la lecture des ordres de  la  liste  ou 
durant  l'excution  d'une des routines.  Voici l'adresse  de  la 
liste des paramtres de retour.

DESCRIPTIF DES LISTES UTILISES POUR LE PROTOCOLE SRIE 500
  * Descripteur *
    L'adresse  de ce descripteur est transmise dans  le   message 
503.  Cette  une phrase de 32 caractres dcrivant  l'application 
(afin de permettre le choix par l'utilisateur) suivie d'un  octet 
 $00 et d'un octet  $FF,  donc mme format que pour le  message 
303,    la  difference qu'il n'y a qu'une seule phrase  dans  le 
message 503 (aucune utilit d'en avoir plusieurs!).

  * Liste des ordres pour dclencher les routines *
   Dans la documentation du logiciel,  l'utilisateur trouvera  un 
descriptif des routines pouvant tre pilotes de l'extrieur.
     Chaque  routine  porte  un  numro  et  ventuellement    un 
descriptif des paramtres qui lui sont ncessaires. Ce descriptif 
permet de fabriquer une liste d'ordres d'aprs le modle suivant: 
Numro de routine (sur un word) Taille du paramtre qui va suivre 
($FFFD pour indiquer que le paramtre est sur un word, $FFFE pour 
un  long  mot)  Paramtre,  Taille du paramtre  qui  va  suivre, 
Paramtre,  etc...  Numro de routine, Taille du paramtre qui va 
suivre,  Paramtre,  $FFFF  (Indication de fin  de  tableau).  Ce 
systme rapellera,  pour ceux qui le connaisse,  le principe  des 
Metafiles.

   Par exemple si nous avons une routine de traage  de  cercles, 
numrote 4, attendant les coord. X, Y puis R pour le rayon, puis 
une routine numrote 5,  traant un rectangle  (paramtres=coord 
coin sup.  gauche et coord coin inf.  droit) avec une liste telle 
que:

4,$FFFD,100,$FFFD,150,$FFFD,50
4,$FFFD,70,$FFFD,150,$FFFD,25
5,$FFFD, 10,$FFFD,10,$FFFD,250,$FFFD,300,$FFFF



nous tracerons 2 cercles (x=100,  y=150, r=50 puis x=70, y=150 et 
r=25)  et ensuite un rectangle (coin sup gauche 10/10,  coin  inf 
droit 250/300)

 * Tableau des retours *
    Certaines  routines doivent  retourner  des  paramtres,  des 
rsultats etc... Par les messages 505 ou 509, l'application qui a 
xcute  les routines donne l'adresse d'une liste contenant  les 
valeurs  de  retour.  Le principe est le mme que pour  la  liste 
d'ordres:  chaque donne de retour est prcde de $FFFD si  elle 
est code sur un mot,  ou de $FFFEE si elle est code sur un long 
mot. La liste se termine par $FFFF. Si la liste de commande tait 
compose d'ordres relatifs  plusieurs routines,  les valeurs  de 
retours seront les unes aprs les autres, dans l'ordre d'appel de 
ces routines.  Le descriptif des retours devra bien videment  se 
trouver dans la doc.  du logiciel (nombre de paramtres de retour 
par fonction, signification, valeurs possibles, etc...).

   Par ce principe de paramtres,  il faut remarquer qu'il  n'est 
pas   possible  (ou  en  tout  cas  c'est  trs  malcommode)   de 
transmettre  une chaine de caractres.  Nous devrons pour un  tel 
besoin,  transmettre  l'adresse  de la chaine.  Avec  un  peu  de 
propret  dans la conception des routines,  cela ne pose  pas  de 
problmes. Encore faut-il savoir programmer proprement...


