ftp.uni-stuttgart.de/pub/systems/acorn//Acorn.tar/Acorn/riscos/problems/messagedoc

Text File | 1992-02-24 | 12KB | 294 lines

Article 4858 of comp.sys.acorn:
Path: rusmv1!news.belwue.de!ira.uka.de!Sirius.dfn.de!darwin.sura.net!haven.umd.edu!ames!elroy.jpl.nasa.gov!swrinde!mips!mips!munnari.oz.au!comp.vuw.ac.nz!actrix!tornado!khantazi!banksie
From: [e-mail] (Philip R. Banks)
Newsgroups: comp.sys.acorn
Subject: Re: Message Translation Query
Message-ID: <[e-mail]>
Date: 19 Feb 92 05:53:57 GMT
References: <[e-mail]>
Reply-To: [e-mail]
Organization: My Arc.
Lines: 271

[e-mail] (Simon B Proven IE2) writes:

> I'd like to know more about this module if anyone can fill me in,
> and if it's available under R02?

   MessageTrans is available under RO2 and behaves identically (as far as I
am aware) to the RO3 version. The docs for it were released a while ago on
the net so I'll repost em below for you...

---docs begin---
X-NEWS: vuwst1 comp.sys.acorn: 862
Relay-Version: VMS News - V6.0-2 04/02/91 VAX/VMS V5.3; site matai.vuw.ac.nz
Path: matai.vuw.ac.nz!comp.vuw.ac.nz!waikato.ac.nz!decwrl!elroy.jpl.nasa.gov!swrinde!cs.utexas.edu!uunet!mcsun!ukc!acorn!RMokady
Newsgroups: comp.sys.acorn
Subject: Re: MessageTrans
Message-ID: <[e-mail]>
From: [e-mail] (Ran Mokady)
Date: 13 Mar 91 16:31:35 GMT
Sender: [e-mail]
References: <+GG&9-$@warwick.ac.uk>
Distribution: comp
Organization: Acorn Computers Ltd, Cambridge, England
Lines: 243

In article <+GG&9-$@warwick.ac.uk> [e-mail] (Pop Mobility Freak) writes:

>
>P.S.    Perhaps someone in Acorn would like to fill in the blanks and correct
>        any errors I made in the above.


We do read this group here at Acorn you know...

                        Ran.




As requested here is the MessageTrans documentation.


Overview
--------

This document describes the SWI interface to the MessageTrans module, which
provides message translation services, and the format of the message files
that it uses.


SWI MessageTrans_FileInfo
   In   R1 -> filename
   Out  R0 = flag word:
             bit 0 set => file is held in memory (can be accessed directly)
             bits 1..31 reserved (ignore them)
        R2 = size of buffer required to hold file
             if R0 bit 0 set, the buffer is not required for read-only access

SWI MessageTrans_OpenFile
   In   R0 -> 4-word data structure
              must be held in the RMA if R2=0 on entry
        R1 -> filename, held in the RMA if R2=0 on entry
                        (NOTE: FILENAME MUST REMAIN UNCHANGED FOR THE DURATION OG THE FILE BEING OPEN)
        R2 -> buffer to hold file data
              0 => allocate some space in the RMA,
                   or use the file directly if possible
        Error: "Message file already open" if R0 points to a structure
               already known to MessageTrans (ie. already open).

        An application may decide that it would like to buffer the file in
        its own workspace (rather than the RMA) if it needs to be loaded, or
        use the file directly if it is already in memory.  To do this:

            SYS "MessageTrans_FileInfo",,filename$ TO flags%,,size%
            IF flags% AND 1 THEN buffer%=0 ELSE buffer%=FNalloc(size%)
            SYS "OS_Module",6,,,17+LENfilename$ TO ,,filedesc%
            $(filedesc%+16)=filename$
            SYS "MessageTrans_OpenFile",filedesc%,filedesc%+16,buffer%

        where FNalloc() allocates a buffer of a given size, by using the
        Wimp_SlotSize or "END=" command.  Note that in fact the filename and
        file descriptor only need to be in the RMA if R2=0 on entry to
        MessageTrans_OpenFile.

  Note: If R2=0 on entry to this SWI, and the application uses direct
        pointers into the file (rather than copying the messages out) or
        uses MessageTrans_MakeMenus, it should also trap
        Service_MessageFileClosed, in case the file is unloaded.

SWI MessageTrans_Lookup
   In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
        R1 -> token, terminated by any char <= 32, or "," or ")"
              or token:default message terminated by 0 char.
        R2 -> buffer to hold result (0 => don't copy it)
        R3 = buffer size (if R2 non-0)
        R4 -> parameter 0 (0 => don't substitute for "%0")
        R5 -> parameter 1 (0 => don't substitute for "%1")
        R6 -> parameter 2 (0 => don't substitute for "%2")
        R7 -> parameter 3 (0 => don't substitute for "%3")
   Out  R1 -> terminator of token
        R2 -> result string (read-only with no sustitution if R2=0 on entry)
        R3 = size of result before terminator
             (terminator = 10 if R2=0 on entry, else 0)

   This SWI allows a message token to be translated into a string, with
   optional parameter substitution.

   The application must have called MessageTrans_OpenFile beforehand in
   order to use this SWI, although you can still call it if the file has
   been automatically closed by the system, because it will automatically
   re-open it as well.

   If the message token does not match, the error "Message token not found"
   is returned unless the token was followed by ":default value", in which
   case the default value is returned (I.E. either copied to the buffer or
   pointed at).  This error is also given if the value to be returned is on
   the last line of the file, and does not have a terminating CHR$(10).


   See the "File format" section for further details.



SWI MessageTrans_MakeMenus
   In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
        R1 -> menu definition (see below)
        R2 -> RAM buffer to hold menu structure
        R3 = size of RAM buffer
   Out  [R1..] = menu data
        R3 = bytes remaining in buffer (should be 0 if you got it right)
        "Buffer overflow" error if buffer is too small

   Menu structure:
        +0 (n)  Token for menu title, terminated by any char <= 32, or "," or ")"
                null => no more menus, otherwise:
        +n (1)  menu title foreground and frame colour
           (1)  menu title background colour
           (1)  menu work area foreground colour
           (1)  menu work area background colour
           (1)  height of menu items
           (1)  gap between items
        Menu items:
           (n)  Token for menu item, terminated by any char <= 32, or "," or ")"
           Word-align to here (addr := (addr+3) AND (NOT 3))
           (4)  Menu flags (bit 7 set => last item)
           (4)  Offset from RAM menu start to RAM submenu start
                0 => no submenu
           (4)  Icon flags

   This SWI allows a menu structure to be set up from a structure
   containing references to tokens, and sets up menu widths.  Parameter
   substitution is not allowed.

   The application must have called MessageTrans_OpenFile beforehand in
   order to use this SWI, although you can still call it if the file has
   been automatically closed by the system, because it will automatically
   re-open it as well.

   If the icon flags have bit 8 clear (ie. they are not indirected), the
   message text for the icon will be read into the 12-byte block that forms
   the icon data, otherwise the icon data will be set up to point to the
   message text inside the file data.  In the latter case they are
   read-only.

   If the menu item flags bit 2 is set (writeable) and the icon is
   indirected, the 3 words of the icondata in the RAM buffer are assumed to
   have already been set up by the calling program.  The result of looking
   up the message token is copied into the buffer indicated by the first
   word of the icon data (truncated if it gets bigger than the buffer size
   indicated in [icondata,#8]).


SWI MessageTrans_CloseFile
   In   R0 -> 4-word data structure passed to MessageTrans_OpenFile


Service_MessageFileClosed
   In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
   Out  If the application recognises the value of R0 passed in, and it has
        any direct pointers into the message data that it relates to, it
        should re-initialise itself by calling MessageTrans_OpenFile again
        to re-open the file, and recache its pointers.  If it has used
        MessageTrans_MakeMenus, it should call Wimp_GetMenuState to see if
        its menu tree it open, and delete it using Wimp_CreateMenu(-1) if
        so.

   This service call is only ever issued if the file is not held in the
   user's own buffer.  It tells the application that its file data has been
   thrown away, for example if the file is held inside a module which is
   then reloaded.

   It is only necessary to trap this service call if direct pointers into
   the file data are being used.  Otherwise, the MessageTrans module will
   make a note in the file descriptor that the file has been closed, and
   simply re-open it when MessageTrans_Lookup or MessageTrans_MakeMenus is
   next called on that file.

   It is recommended that applications that cannot trap service calls do not
   use direct pointers into the file data (eg. indirected icons with
   MessageTrans_MakeMenus).  They can still use such indirected icons, if
   they provide a buffer pointer in R2 on entry to MessageTrans_OpenFile (so
   that the message file data is copied into the buffer).


Service_Reset

   Since MessageTrans does not close message files on a soft reset,
   applications that do not wish their message files to be open once they
   leave the desktop should call MessageTrans_CloseFile for all their open
   files at this point.  However, it is perfectly legal for message files to
   be left open over soft reset.


File format
-----------

Message files contain a series of one-line token / value pairs, terminated
by character 10 (linefeed).

        <file> ::= { <line> }*
        <line> ::= <tokline> | "#" <comment><nl> | <nl>
     <tokline> ::= <token> { "/"<token> | <nl><token> }* : <value><nl>
       <token> ::= <tokchar> { <tokchar> }*
     <tokchar> ::= <char> | <wildcard>
        <char> ::= any character > " " except ",", ")", ":", "?" or "/"
    <wildcard> ::= "?"      (matches any character)
     <comment> ::= { <anychar> }*
     <anychar> ::= any character except <nl>
          <nl> ::= character code 10
       <value> ::= { <anychar> | "%0" | "%1" | "%2" | "%3" | "%%" }*

Note that the spaces in the above description are purely to improve
readability - in fact spaces are significant inside tokens, so should only
really appear in <comment> and <value>.

Alternative tokens are separated by "/" or <nl>.  If any of the alternative
tokens before the next ":" match the supplied token, the value after the
next ":" up to the following <nl> is returned.  The "?" character in a token
in the file matches any character in the supplied match token.  Case is
significant.

If R2 is not 0 on entry to MessageTrans_Lookup, "%0", "%1", "%2" and "%3"
are subsitituted with the parameters supplied in R4..R7, except where the
relevant register is 0, in which case the text is left alone.  "%%" is
converted to "%" - otherwise if no parameter substitution occurs the text is
left alone.  No other substitution is performed on the string.

For example:

        # This is an example message file

        TOK1:This value is obtained only for "TOK1".
        TOK2
        TOK3/TOK4:This value is obtained for "TOK2","TOK3" or "TOK4"
        TOK?:This value is obtained for "TOK<not 1,2,3 or 4>"

        ANOTHER:Parameter in R4 = %0, parameter in R5 = %1.






-----
"We're children, Needing other children
 And yet letting our grown up pride
 Hide all the need inside
 Acting more like children than children"
---docs end---

   Thanks go to Ran Mokady for posting them in the first place...

    Philip

--
Philip R. Banks                                                         @@@@@/|
Syntax: mail <[e-mail]|[e-mail]> @@@@/#|
                                                                        @@@/##|
What price the crown of a king on his throne,                           @@/---|
When you're chained in the dark all alone?  ---A.P.P.                   @/    |