                Remote control of GEM applications with

                              GEMScript

                       15.11.1998 (Release 1.2)

                                 by

              Thomas Much, Holger Weets, Manfred Lippert
              
                  English Translation by Peter West
                          


Table of contents
=================

 1  Introduction

 2  The concept in overview

 3  GEM messages
    3.1  Initialisation
         3.1.1  GS_REQUEST
         3.1.2  GS_REPLY
         3.1.3  The GS_INFO structure
    3.2  Termination
         3.2.1  GS_QUIT
    3.3  Remote control
         3.3.1  GS_COMMAND
         3.3.2  GS_ACK
    3.4  Macros
         3.4.1  GS_OPENMACRO
         3.4.2  GS_MACRO
         3.4.3  GS_WRITE
         3.4.4  GS_CLOSEMACRO

 4  Subsequent starting of a GS interpreter

 5  Standard GS commands
    5.1  AppGetLongName
    5.2  CheckCommand
    5.3  Close
    5.4  Copy
    5.5  Cut
    5.6  Delete
    5.7 GetAllCommands
    5.8  GetFront
    5.9  New
    5.10  Open
    5.11  Paste
    5.12  Print
    5.13  Quit
    5.14  Save
    5.15  SaveAs
    5.16  SelectAll
    5.17  ToFront
    5.18  Undo

 6  Further GS commands
    6.1  Exec
    6.2  CheckApp

 7  Parameters
    7.1  Empty parameters
    7.2  Hex-coded parameters
    7.3  File
    7.4  File+Path
    7.5  Script

Appendix
========

 A  History

 B  Contacts



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

GEMScript is a protocol for remote-controlling GEM applications. The 
protocol itself has been kept very simple, so that programmers should 
have no major problems to support GEMScript in their own programs.

This documentation defines this GEMScript protocol and is therefore
aimed primarily at programmers. Mark well that with GEMScript we are 
not yet dealing with a program as such, but only with the definition 
of a communication between GEM programs.

The most common use of communication via GEMScript may be one through a 
script interpreter. One such interpreter is represented by Holger Weets' 
'Scripter', for instance. Controlled by a script that this interpreter 
understands, the interpreter transmits commands via the defined GEMScript 
protocol to GEM programs which then execute the desired actions.

Naturally GEM programs can also communicate between themselves via 
GEMScript without a script interpreter.

The high flexibility of the GEMScript protocol is due to the fact that 
the commands to be sent are not prescribed in any way. The protocol only 
defines how commands are sent but not, however, what commands these 
should be.

Each application can therefore offer its own commands, depending on 
what capabilities it has. A drawing program, say, will certainly
wish to offer different commands to a desktop or a spreadsheet.

There are, however, a few standard commands that are likely to be 
useful for virtually every application, say the opening of a document. 
Therefore this GEMScript documentation also describes a set of such 
standard GS commands, to which every GEMScript-capable application 
should keep, as far as possible. However, this is not a mandatory 
requirement.



2  The concept in overview
**************************

As already mentioned in the introduction, with GEMScript we are dealing 
with communication in which commands are sent back and forth between GEM 
programs. The exchange itself is based on normal AES messages.

The basic principle of the communication is actually very simple:

 1. An application that wishes to communicate with another first of 
     all announces itself to this application ('Hallo! I am here 
     and I would like to talk to you via GEMScript.'). The messages
     GS_REQUEST and GS_REPLY exist for this purpose.

 2. After this one can already start the 'session', i.e. one can merilly
     send commands back and forth. For this the messages GS_COMMAND and
     GS_ACK exist. The applications talk to each other and say mutually 
     what is to be done. In most cases the whole thing is rather one-
     sided, i.e. one application commands what is to be done (normally
     the script interpreter) and the other application carries it out.
     But naturally other 'conversations' are also possible.

 3. If an application does not wish to continue the conversation, it 
     simply announces its departure ('Goodbye!'). For this the message 
     GS_QUIT exists.

For people for whom this is too simple there is still a small titbit 
that one can incorporate in one's GEMScript-capable applications - but 
does not necessarily have to: The recording of actions (macros).
An application that supports this is called 'record-capable'.

For this it is imperative to have a script interpreter which is capable 
also of recording commands, and able to replay them later on. It must, 
so to speak, itself create scripts based on information that is sent 
to it by an application. If one replays ('executes') a script created 
this way at a later time, then the application will repeat exactly what 
it did during the recording process.

Here are the principles for making a recording:

 1. The user activates recording in an application. Following this the 
     application searches for the GEMScript interpreter (if necessary
     it will start it up) and initialises the GEMScript communication 
     in the usual way with GS_REQUEST/GS_REPLY. Normally the user also
     has to select a file now in which the script to be recorded is 
     to land up.

 2. The application informs the interpreter that it would now like to 
     record. For this the message GS_OPENMACRO exists. If the interpreter 
     agrees, it returns GS_MACRO to signify that recording can start now.

 3. The application now sends all actions that are to be recorded with 
     the message GS_WRITE to the interpreter. This then creates the 
     script from this.

 4. When the user terminates the recording, the application informs the 
     interpreter of this with the GS_CLOSEMACRO message. Finished.

If one has succeeded in programming an application to make it GEMScript-
capable, then basically adding the recording capability should present 
no serious problems.

To complete the whole section, there is also a further small variant of 
recording: The application-independent recording.

For this a further special application is required that coordinates this 
recording: The recording-server. The desktop 'jinnee' functions as such
a server, for instance.

This application-independent recording too can be described briefly:

 1. The user activates the application-independent recording in the 
     recording-server. As for a normal recording, this server looks 
     for the GEMScript interpreter and initialises the GEMScript 
     communication with GS_REQUEST/GS_REPLY.

 2. As with the normal recording the server begins to start a recording
     at the interpreter (GS_OPENMACRO). The interpreter replies with
     GS_MACRO.

 3. In addition, the recording-server attempts to make GEMScript contact 
     with all running applications (with GS_REQUEST/GS_REPLY). For the 
     applications where this has succeeded the server triggers more-
     or-less 'externally' recording with the message GS_MACRO. If the 
     applications are externally record-capable, they now merrily start 
     to send their commands via GS_WRITE to the server. (For these
     applications the server in this case is the interpreter.)

 4. The server collects together all the commands of all running 
     applications to be recorded, identity-marks these specially (so 
     as to be able to recognise them later when replaying the script)
     and passes these new commands as 'its own' commands to be recorded 
     to the interpreter. This records them in the script.

 5. When the user terminates the recording, the server interrupts the 
     recording for all applications, likewise again 'externally'. In
     the same way it terminates its own recording with the interpreter 
     (both with GS_CLOSEMACRO). Finished.

 6. When one replays a script created in this way, the interpreter only 
     finds commands that are intended for the server, and then sends
     them to it. The server in turn recognises that it is dealing with 
     commands for other applications, and simply passes them on as 
     appropriate. Here one can see the advantage that the server has 
     if it is part of a desktop (as in the case of jinnee): If during 
     replay of the script an application is not running, then usually
     it is possible to start it subsequently without much difficulty, 
     provided that the application has been installed in the desktop.



After this overview of the possibilities offered, the actual 
documentation of the GEMScript protocol can start.



3  GEM messages
***************


3.1  Initialisation
===================


3.1.1  GS_REQUEST
-----------------

In order to find out whether an application suports GEMScript one sends
it the following message:

GS_REQUEST
msg[0] 0x1350 (4944)
msg[1] ap_id
msg[2] 0
msg[3]
    +  pointer to GS_INFO structure
msg[4]
msg[5] 0
msg[6] 0
msg[7] any desired ID (except -1)

For ID one can choose any desired number apart from -1. The ID -1 is 
the 'invalid ID'. This makes matters easier for the programmer, as he 
can use the invalid ID -1 internally for, say, non-active GEMScript 
links so he does not need an extra flag (in case he needs something like 
this at all).


Reply:

If the application understands GEMScript, then one receives the reply
GS_REPLY.

Naturally, each application needs to be tested only once before the first 
command for GEMScript capability.


3.1.2  GS_REPLY
---------------

GS_REPLY is sent by a GEMScript-capable application as a reply to 
GS_REQUEST.

GS_REPLY
msg[0] 0x1351 (4945)
msg[1] ap_id
msg[2] 0
msg[3]
    +  pointer to GS_INFO structure
msg[4]
msg[5] 0
msg[6] 0:      OK, Application can perform GS communication
       2:      'Another ID please'
       Otherwise: Error, GS communication not possible at present
msg[7] ID from GS_REQUEST


If an application reports an error in msg[6], one may not send any 
further GS messages to it. One can, however, inquire again later on
with GS_REQUEST about GEMScript-capability.

One should note that an application can receive several GS_REQUEST 
messages. First of all several different applications can start a
communication, but thanks to the ID one application can even communicate
simultaneously in several 'sessions'.

If an application is restricted to only one running communication at a 
time (say because the current communications partner is entered in a
global variable), then one must ensure that all following GS_REQUEST 
messages are correctly refused if a communication is already running.
(Best with the value 1 in msg[6].)

If the application replies in msg[6] with 2, then it is asking for a 
different session ID. So choose another session ID and try GS_REQUEST 
again. The reason for this: If two applications simultaneously send a 
GS_REQUEST to each other with the same session ID (extremely unlikely, 
but possible), then any following commands could not be assigned 
unambiguously to the sessions. An application that has just transmitted 
a GS_REQUEST and (while it is actually waiting for a GS_REPLY) also 
receives a GS_REQUEST from the same partner application with the same 
session ID, must refuse this GS_REQUEST with msg[6] = 2.


3.1.3  The GS_INFO structure
----------------------------

typedef struct {
   long len;       /* Length of the structure in bytes                 */
   int  version;   /* Version number of the protocol at the sender
                      (currently 0x0120 = 1.2)                         */
   int  msgs;      /* Bitmap of the supported messages and
                      capabilities (GSM_xxx)                           */
   long ext;       /* Extension used, say '.SIC'                       */
} GS_INFO;

GSM_COMMAND = 0x0001  /* Can receive GS_COMMAND                        */
GSM_MACRO   = 0x0002  /* Can receive GS_OPENMACRO, GS_WRITE and 
                         GS_CLOSEMACRO, and send GS_MACRO (interpreter)*/
GSM_WRITE   = 0x0004  /* Can send GS_OPENMACRO, GS_WRITE and 
                         GS_CLOSEMACRO, and receive GS_MACRO 
                         (recording-capable application)               */
GSM_HEXCODING = 0x0008 /* Hex coding                                   */


Notes about the GS_INFO structure:

    The structure must be allocated to global memory with Mxalloc().

    The structure may not be altered by the receiver, i.e. GS_REQUEST- 
     and GS_REPLY-sender must each allocate their own structure.

    As one cannot ascertain when the receiver read out the structure,
     it should remain basically available. It is recommended, therefore,
     to allocate the structure at the start of the program and only 
     release it again at its end.

    long occupies 32 bits. Thus it corresponds also to size_t or the
     sizeof() type in Pure-C.

    int occupies 16 bits.

    ext is intended for the interpreter. Other applications can enter
     a 0 here.

    The capabilities of a GEMScript partner should always be inquired 
     via 'msgs' if possible and not via the version number (version) of 
     the supported protocol.


3.2  Termination
================


3.2.1  GS_QUIT
--------------

GS_QUIT should be sent to the communications partner when a remote-
controlling application no longer sends GS_COMMAND commands, or when 
a remote-controlled application no longer can/wishes to evaluate such 
messages (say because the application terminates).

GS_QUIT
msg[0] 0x1354 (4948)
msg[1] ap_id
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] ID from GS_REQUEST


3.3  Remote control
===================


3.3.1  GS_COMMAND
-----------------

GS_COMMAND
msg[0] 0x1352 (4946)
msg[1] ap_id
msg[2] 0
msg[3]
    +  pointer to command line (see below)
msg[4]
msg[5] 0
msg[6] 0
msg[7] ID from GS_REQUEST

The command line contains the actual command, followed by optional
parameters. Command and parameters are separated by ASCII #0, and
at the end of the command line there is ASCII #0#0, so in C-notation 
for instance one would write:

"command\0parameter 1\0parameter 2\0\0"

The commands must be evaluated by the receiver without regard to case
(i.e. CAPS = lower case). It would be nice if there was support for as 
many of the standard GS commands as possible.

See also: Parameters

The character-string must be allocated to global memory with Mxalloc().

Reply:

As a reply one receives the message GS_ACK, which can be used for 
releasing this memory.


3.3.2  GS_ACK
-------------

The following message is sent by a GEMScript-capable application as a 
reply to GS_COMMAND. The remote-controlling application can, when it 
receives this message, release the memory from msg[3/4] once more, for 
instance.

GS_ACK
msg[0] 0x1353 (4947)
msg[1] ap_id
msg[2] 0
msg[3]
    +  exactly the values of the received GS_COMMAND message
msg[4]
msg[5]
    +  result or error message as ASCIIZZ text (see below) or NULL
msg[6]
msg[7] 0: (GSACK_OK)      OK, command has been or will be executed
       1: (GSACK_UNKNOWN) Command unknown
       2: (GSACK_ERROR)   Error (command not executed)

If a reply is returned in msg[5/6], then it will have the same format as
the GS_COMMAND command line, i.e. the individual values will be separated 
by ASCII #0 and have ASCII #0#0 at the end of the return string.

Reply:

If the evaluating application returns the result of a function or an 
error description in msg[5/6] (i.e. a value other than NULL), then the
remote-controlling application has to return the following reply. The 
evaluating application can then for its part release the memory occupied 
by the result.

GS_ACK
msg[0] 0x1353 (4947)
msg[1] ap_id
msg[2] 0
msg[3] 0
msg[4] 0
msg[5]
    +  exactly the values of the received GS_ACK-message
msg[6]
msg[7] 0

Notes about the return string:

The return value of a command should always be returned in msg[5]+msg[6],
one should not 'misuse' msg[7] for this. This applies, above all, for 
commands that return true or false. If the command could be executed 
correctly, one should return for 'true' any desired non-empty return 
string (for instance '1'), for 'false' the recommendation is an empty
string or a null-pointer.

This is very useful for the interpreter 'Scripter' by Holger Weets, 
for instance, because true/false commands can be conveniently 
interrogated by the following script:

if (command(...))
{
        /* True */
}
else
{
        /* False */
}

If the result was returned in msg[7], one would have to write in the
'Scripter' example the following:

command(...)
if (errno == 0)
{
        /* True */
}
else
{
        /* False */
}


3.4  Macros
===========


3.4.1  GS_OPENMACRO
-------------------

GS_OPENMACRO
(App->Interpreter)
msg[0] 0x1355 (4949)
msg[1] ap_id
msg[2] 0
msg[3]
    +  pointer to the filename under which the script is to be saved
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0

An application wishes to be recorded by the script interpreter. As a 
reply it receives GS_MACRO.

The interpreter should be searched for via the environment variable 
GEMSCRIPT and started up if not already running.

The file extension for scripts can be established by the application from 
the interpreter via the GS_INFO structure in GS_REPLY. This extension 
may be required by the file-selector, which will be called in most cases 
before a recording starts.

Summary of the procedure of a recording:

    Find interpreter and if necessary start it up (GEMSCRIPT variable)

    Announce itself to the interpreter (GS_REQUEST)

    Interpreter replies with GS_REPLY (returns GS_INFO)

    Call file-selector (extension from GS_INFO from interpreter)

    Start recording with GS_OPENMACRO

    Interpreter returns GS_MACRO

    Record via GS_WRITE/GS_ACK

    At the end terminate recording with GS_CLOSEMACRO


3.4.2  GS_MACRO
---------------

GS_MACRO
(Interpreter->App)
msg[0] 0x1356 (4950)
msg[1] ap_id
msg[2] 0
msg[3]
    +  exactly the values of the received GS_OPENMACRO message
       or NULL for record invitation
msg[4]
msg[5] ID (simplest is filehandle) for identifying the script
msg[6] 0: File is open, recording can start; otherwise:Error
msg[7] 0

Note: GS_MACRO can also occur without a previous GS_OPENMACRO.
In that case msg[3/4] is NULL.

This case should be regarded as a sort of invitation to start recording, 
through which, say, application-independent recording via an external 
record-server is possible. So the application is invited to send all 
actions from now on via GS_WRITE to the record-server (which has sent
the GS_MACRO).

One should note that here too the ID -1 (invalid ID) may not be passed.

If the application can not, or does not want to, record at this time,
then it has to return a GS_CLOSEMACRO.

Summary of the procedure for a forced recording:

    Record-server (e.g. jinnee) announces itself with GS_REQUEST to 
     the application. Application replies with GS_REPLY.
     The record-server establishes via GS_INFO that the application
     knows GS_MACRO, i.e. is capable of recording.

    Record-server forces recording with GS_MACRO (NULL in filename).

    Application replies either with GS_CLOSEMACRO (refusal) or simply
     records the actions with GS_WRITE/GS_ACK.

    Record-server or application terminates recording with 
     GS_CLOSEMACRO.


3.4.3  GS_WRITE
---------------

GS_WRITE
(App->Interpreter)
msg[0] 0x1357 (4951)
msg[1] ap_id
msg[2] 0
msg[3]
    +  pointer to command line (as for GS_COMMAND)
msg[4]
msg[5] ID from GS_MACRO
msg[6] 0
msg[7] 0

The interpreter replies to this message as for GS_COMMAND with GS_ACK, 
without however returning a result in msg[5/6].

If an error is signalled in this GS_ACK, then no further GS_WRITE 
messages should be sent.


3.4.4  GS_CLOSEMACRO
--------------------

GS_CLOSEMACRO
(App->Interpreter / Interpreter->App)
msg[0] 0x1358 (4952)
msg[1] ap_id
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] ID from GS_MACRO
msg[6] 0
msg[7] 0

Terminates the recording of a script.

Note: The recording can be terminated from both ends, both by the 
recording application itself, as well as by the interpreter (record-
server with application-independent recording).



4   Subsequent starting of a GS interpreter
*******************************************

So that applications (e.g. for recording of macros) can find a GS 
interpreter with appl_find() or - if one is not running - start it up 
subsequently, one can set the variable GEMSCRIPT in the environment
with, for example:

  #_ENV GEMSCRIPT=D:\SCRIPTER\SCRIPTER.APP




5  Standard GS commands
***********************


These standard commands are intended as suggestions for implementation in 
applications. They should in no way be seen as compulsory, and if they 
are not implemented then the parameters also are not compulsory. Not 
every program is suitable for certain standard commands, or some 
capabilities of a program may make a different extension of a standard 
command sensible.


5.1  AppGetLongName
===================

Command: AppGetLongName
Parameters: None
Return: String

Returns the 'long' name of the program, because the process name that 
is ascertained via the system is usually limited for historical reasons 
to 8 characters. This longer name can be used by programs that display 
all running programs, for instance, such as MultiStrip or AppLine. The 
return may also be an empty string (but not NULL). This signals that 
the process does not want to let itself be displayed in the above-named 
programs. This is sensible for parallel-running threads, for example. 
The long names should contain no version information or similar, as 
usually this does not aid clarity.


5.2  CheckCommand
=================

Command: CheckCommand
Parameters: Command name
Return: '1' or '0' (or "" or NULL)

This command returns '1' if the application supports the command passed 
as a parameter.

For instance, an application that understands the command 'Open' but not 
the command 'Save' returns for 'CheckCommand\0Save\0\0' the string 
'1\0\0' and for 'CheckCommand\0Save\0\0' the string '0\0\0'.

Attention: Optionally instead of '0' either an empty string "" or even a 
null-pointer (NULL) may be returned!


5.3  Close
==========

Command:  Close
Parameters: File (optional)
Return:  None

Closes the window corresponding to file. If no file was passed then 
the top window will be closed. The command may also be implemented so 
that several file parameters may be passed at a time.


5.4  Copy
=========

Command:  Copy
Parameters: File (optional)
Return:  None

Copies the selected part of the specified file to the clipboard. If no 
file is specified, then the selection in the topped window will be used.


5.5  Cut
========

Command:  Cut
Parameters: File (optional)
Return:  None

Cuts out the selected part of the specified file and writes it to the 
clipboard. If no file is specified, the selection in the topped window 
will be used.


5.6  Delete
===========

Command:  Delete
Parameters: File (optional)
Return:  None

Cuts out the selected part of the specified file. If no file is 
specified, the selection in the topped window will be used.


5.7  GetAllCommands
===================

Command: GetAllCommands
Parameters: None
Return: Strings

Returns all the commands that the application understands. After this 
command one can - but does not have to - specify parameters.

An application that understands the commands 'Open' and 'Close', say, 
could for example return the following result string (in C notation):

"Open\0Close\0\0".

But it could also specify the whole thing more exactly and return the 
following:

"Open [<file>]\0Close [<file>]\0\0".

The purpose of the command is more to provide the Script-programmer with 
an overview of the commands that are understood, rather than to be 
evaluated autmatically.


5.8  GetFront
=============

Command:  GetFront
Parameters: None
Return:  File or File+Path

If the topped window of the application has a name with which it can 
be identified in the GS commands, then this should be returned as a 
reply to this command.


5.9  New
========

Command:  New
Parameters: None
Return:  None

Creates a new document.


5.10  Open
==========

Command:  Open
Parameters: File+Path (optional)
Return:  None

Opens the specified file. If no file has been passed, then the file-
selector or similar should be displayed to the user.

The command may also be implemented so that several file parameters 
may be passed at the same time.


5.11  Paste
===========

Command:  Paste
Parameters: File (optional)
Return:  None

Inserts the contents of the clipboard into the selected part of the 
specified file. If no file has been specified, then the selection in 
the topped window will be used.


5.12  Print
===========

Command:  Print
Parameters: File (optional)
Return:  None

Prints out the specified file. If no file has been specified, then the 
topped window will be printed.

The command may also be implemented so that several file parameters 
may be passed at the same time.


5.13  Quit
==========

Command:  Quit
Parameters: None
Return:  None

Terminates the application.


5.14  Save
==========

Command:  Save
Parameters: File (optional)
Return:  None

Saves the specified file. If no file is passed then the top window will 
be saved.

The command may also be implemented so that several file parameters 
may be passed at the same time.

5.15  SaveAs
============

Command:  SaveAs
Parameters: File, file (optional)
Return:  None

This command has at least one and at most two parameters. The first 
designates the new filename, the second the window to be saved. If the
second parameter is not given then the top window will be saved under 
the filename of the first parameter.


5.16  SelectAll
===============

Command:  SelectAll
Parameters: File (optional)
Return:  None

Marks or selects the whole of the specified file. If no file is
specified then the document in the topped window will be selected.


5.17  ToFront
=============

Command:  ToFront
Parameters: File
Return:  None

Tops the window with the specified file (brings it to the front).


5.18  Undo
==========

Command:  Undo
Parameters: File (optional)
Return:  None

Undoes (revokes) the last action in the specified file. If no file 
is specified, then the last action in the topped window is undone.



6  Further GS commands
**********************

This section describes less important standard commands, which may only 
make sense for certain programs.


6.1  Exec
=========

Command:  Exec
Parameters: <Script> <Parameters>
Return:  None

This command must be supported by every GEMScript interpreter.
It serves to execute script files.

<Script> specifies the script file; for this the interpreter has 
to understand at least a complete path specification complete with 
extension.

<Parameters> (optional) represent further parameters of some kind
that are passed on to the script, if the interpreter permits this.


6.2  CheckApp
=============

Command:  CheckApp
Parameters: File
Return:  None

Attempts to start up the specified file subsequently. Is supported by the 
desktop jinnee, for instance.



7  Parameters
*************

Multiple parameters are separated by ASCII #0, and the end of the 
command line is signalled with ASCII #0#0 (see GS_COMMAND).

Important: Parameters that start with the ASCII character #1 to #6 
inclusive are reserved for special purposes. At present only #1 (empty 
parameters) and #2 (hex coding) are defined. Parameters that start with 
the ASCII characters #3 to #6 must therefore be ignored at the present 
time.

Example:

"command\0parameter 1\0\3this will now be ignored\0parameter 2\0\0"


7.1  Empty parameters
=====================

Due to the null-byte separation of the parameters, an exception has to
be introduced for the special case of 'empty parameters':

Empty parameters are identified by the ASCII character #1, e.g.

"command\0An empty parameter follows immediately\0\1\0Noted?\0\0"

All characters that follow the #1 character (but still belong to the empty 
parameter) are to be ignored, e.g.

"command\0Empty parameter follows\0\1Ignore this\0not this\0\0"


7.2  Hex-coded parameters
=========================

In order to make it possible to pass any desired ASCII characters 
(remember the reserved characters #1 to #6) the following hex coding 
exists:

If the parameter starts with the ASCII character #2, then the following 
characters are to be regarded as hex-coded, i.e. there follow pairs of 
hexadecimal numbers (0 to F) that each describe one byte.

Example:

"command\0\2""010246414C4C4F\0\0"

The first parameter after the command 'command' consist of the two ASCII 
characters #1 and #2 (coded as '0102') at the start followed by the text 
'HALLO' (coded as 48414C4C4F'). So the parameter will be interpreted as 
'\1\2HALLO'.

Note: Don't let the two inserted quote marks worry you: In the C 
programming language this prevents the '0' from being seen as belonging 
to the '2' and so prevents incorrect insertion of ASCII character #20 
into the string.

The additional number 'A' to 'F' can be written either in capitals 
or in lower case!


7.3  File
=========

The file parameter designates a filename (with or without a path 
specification). As individual commands are separated by ASCII #0,
no (!) quoting takes place.

GEMScript-capable applications as a rule establish with this parameter 
which window is affected by a command. If a direct comparison of the 
command filename and the filenames assigned to the window is not 
successful, the application should look for the greatest possible 
agreement of parts of the strings.


7.4  File+Path
==============

This parameter designates a filename with absolute path specification.


7.5  Script
===========

This parameter designates a script file (for the Exec command). We 
are dealing with a file specification where the extension of the 
script file may also be omitted. If the absolute path specification 
is missing, the interpreter must be capable of finding the file 
(because it is in the same directory as the interpreter, for instance).




A  History
**********

 Rev 1.2 (15.11.98)

         'A different session ID please' for GS_REPLY
        
         GSM_HEXCODING
        
         Note that one should always evaluate msgs instead of version in 
          GS_INFO
          
         CheckCommand included as a standard command
        
         GetAllCommands included as a standard command
        
        
 Rev. 1.1 (24.03.98)
 
         Hex coding introduced
        
         Invalid ID introduced for GS_REQUEST
        
         AppGetLongName included as a standard command
        
         Clearer explanation that the standard commands re not 
          obligatory
          
                                                  
 Rev 1.0 (14.11.97)

         First published version



B  Contacts
***********


Thomas Much, Gerwigstrae 46, D-76131 Karlsruhe, Germany

Fax:       +49 / (0)721 / 62 28 21

EMail:     Thomas Much @ KA2                 (MausNet)
           Thomas_Much@ka2.maus.de
           Thomas.Much@stud.uni-karlsruhe.de (Internet)


Holger Weets, Damm 25, D-26135 Oldenburg, Germany

EMail:     Holger Weets @ OL       (MausNet)
           Holger_Weets@ol.maus.de (Internet)


Manfred Lippert, Rennweg 46, D-90489 Nrnberg, Germany

EMail:     Manfred Lippert @ N       (MausNet)
           Manfred_Lippert@n.maus.de
           mani@mani.de              (Internet)



English translation
===================

Peter West, 38 Woodfield Avenue, London W5 1PA, England

EMail:     xlator@cix.co.uk


