 |
1. The command line
Parameter given when launching a module is a Pascal string (1 byte describing the lenght of the
line, the data-caracters, and the null-byte terminator).
Data are structured like this:
- 8 caracters corresponding to the application wihch has called the module. This 8 caracters will
be given with no transformation to APPL_FIND function.
If Joe is the caller, then the 8 caracters are: "JOE "
- The next caracters (to the ending null-byte) describe a filename:
the HTML file the caller is editing.
The module should get the first 8 caracters of the command line, and APPL_FIND. If there's an
error or the caller doesn't exist, the module should not take the rest of the line or consider
the command line does not applies the exchange protocol described below.
2. Monotasking mode
The module, before quitting, saves the tag or whatever data for the caller, in the
clipboard. Joe accepts *.TXT (= *.HTM produced by the module) and *.STG (C string
format, considered as a macro, so you can use "|" and "~") files. Therefore SCRAP.HTM or SCRAP.STG .
When quitting, the module returns a value (QUIT ret& :
- If 0 : the caller loads nothing
- If 1 : the caller loads SCRAP.HTM
- If 2 : the caller loads SCRAP.STG
- If esle : no yet supported
You can return for others callers than Joe others values. Please, tell me about what values you
have added to normalize this.
3. Multitasking mode
NB: this applies also for accessories in monotasling mode.
Joe supports VA_START message and Drag & Drop protocol.
The exchanges with modules use the GEM pipe ("Tube GEM" in French). The
following decribes the calls. X_adr% is a 16 bytes buffer. 16 bytes buffers
are managed by EVNT_MULTI.
- SEND TEXT TO THE CALLER
caller_id&=APPL_FIND("????????")
' "????????" is the 8 caracter string read in the command line.
IF caller_id&>0
INT{module_adr%}=20140
INT{module_adr%+2}=module_id&
INT{module_adr%+4}=0
INT{module_adr%+6}=0
INT{module_adr%+8}=0
INT{module_adr%+10}=format&
' (1=*.HTM or *.TXT, 2=*.STG, 0 or else=Joe reads nothing)
LONG{module_adr%+12}=module_mem%
' (address in the global memory where the module has put the text)
~APPL_WRITE(caller_id&,16,module_adr%)
ENDIF
When reading this in his 16 bytes buffers, the caller wil or will not read the memory, and
respond to the module with:
- CALLER RESPOND TO MODULE, TEXT RETRIEVED
module_id&=INT{caller_adr%+6}
INT{caller_adr%}=20141
INT{caller_adr%+2}=caller_id&
INT{caller_adr%+4}=0
INT{caller_adr%+6}=0
INT{caller_adr%+8}=0
INT{caller_adr%+10}=0
INT{caller_adr%+12}=0
INT{caller_adr%+14}=0
~APPL_WRITE(module_id&,16,caller_adr%)
To facilite the manipulation of the entire file edited by the caller,
the module can ask to the caller an automatic save of the text:
- REQUEST AUTOMATIC SAVE TO CALLER
caller_id&=APPL_FIND("????????")
' "????????" is the 8 caracter string read in the command line.
IF caller_id&>0
INT{module_adr%}=20142
INT{module_adr%+2}=module_id&
INT{module_adr%+4}=0
INT{module_adr%+6}=0
INT{module_adr%+8}=0
INT{module_adr%+10}=0
INT{module_adr%+12}=0
INT{module_adr%+14}=0
~APPL_WRITE(caller_id&,16,module_adr%)
ENDIF
The caller will save its data and tell next the module it's done, give
the address buffer of filename, and the handle of the window if not
iconified and existing:
- CALLER RESPOND TO MODULE, (OWN DATA SAVED) AND INFORMATION
module_id&=INT{caller_adr%+6}
INT{caller_adr%}=20144
INT{caller_adr%+2}=caller_id&
INT{caller_adr%+4}=0
INT{caller_adr%+6}=window_handle_of_caller&
INT{caller_adr%+8}=0
INT{caller_adr%+10}=0
LONG{caller_adr%+12}=caller_mem%
' the caller has put the filename in a 256 bytes buffer, in global memory.
' The filename buffer is permanent, so the module has no need to respond
' to the caller. But the module must ask the caller the address
' filename: the caller may quit, clean his memory and not respond.
~APPL_WRITE(module_id&,16,caller_adr%)
Be carefull with the widow handle: it's given to close, or shadow, the
caller window to avoid caller data manipulation during module computing.
DO NOT WIND_SET or whatever else the caller window directly, use GEM pipe
and fill the 16 bytes buffer as the Screen manager do.
You can freeze and unfreeze the caller if you know how to do it (See MagiC
developpers documention).
In some cases, you don't need the caller data to be saved. You just only
want informations, so:
- REQUEST INORMATION TO CALLER
caller_id&=APPL_FIND("????????")
' "????????" is the 8 caracter string read in the command line.
IF caller_id&>>0
INT{module_adr%}=20143
INT{module_adr%+2}=module_id&
INT{module_adr%+4}=0
INT{module_adr%+6}=0
INT{module_adr%+8}=0
INT{module_adr%+10}=0
INT{module_adr%+12}=0
INT{module_adr%+14}=0
~APPL_WRITE(caller_id&,16,module_adr%)
ENDIF
The caller will respond to the module with the same message if there was an
automatic save. Therefore with the 20144 code, the window handle, and the
data filename in the caller buffer.
|