Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileGEMSYS [n]

n: iexp

The commnad GEMSYS calls an AES routine by specifying the routine number n.
The parameters necessary for the operation of the routine must first be placed
in the appropriate AES parameter blocks.

Example:

    REPEAT
      GINTIN(0)=60
      GINTIN(1)=30
      GINTIN(2)=10
      GINTIN(3)=10
      GINTIN(4)=200
      GINTIN(5)=200
      GEMSYS 72
    UNTIL MOUSEK

--> A moving rectangle is drawn on the screen, as function number 72 is
    GRAF_MOVEBOX().

Memo: The parameter n is optional. If parameter n is omitted then the
      necessary parameters for the call must be place in the GCONTRL()
      parameter block. See appl_search() for an example listing. Calling a
      function which does not exist is usually fatal.

      ' example #1: with parameter, GFA fills in the GCONTRL() array itself
      ' method: short form
      FUNCTION graf_mouse(mode&,ptr%)
        GINTIN(0)=mode&
        ADDRIN(0)=ptr%
        GEMSYS 78                      !opcode
        RETURN GINTOUT(0)
      ENDFUNC

      ... versus ...

      ' example #2: with no parameter, GCONTRL() values must be supplied
      ' method: long form
      FUNCTION graf_mouse(mode&,ptr%)
        GCONTRL(0)=78                  !opcode
        GCONTRL(1)=1                   !number of GINTIN() input parameters
        GCONTRL(2)=1                   !number of GINTOUT() output parameters
        GCONTRL(3)=1                   !number of ADDRIN() input paramerers
        GCONTRL(4)=0                   !number of ADDROUT() output parameters
        GINTIN(0)=mode&
        ADDRIN(0)=ptr%
        GEMSYS
        RETURN GINTOUT(0)
      ENDFUNC

      Generates less code: short form
      Faster interpreted: short form
      Faster compiled: short form

      GFA fetches the GCONTRL() values from a built-in table. The table
      entries are null for all AES calls not supported by GFA at the time of
      its release. Thus, if you want to call any newer AES routines, you must
      not pass an opcode via GEMSYS. Example #2 format must be use in this
      case.

      According TOS.HYP, GCONTRL(2) and GCONTRL(4) are not needed. This
      appears to be true for newer AES implementations, like N.AES, but not
      for older TOS versions.

      Opcodes that should not be used with GEMSYS n (with a parameter):
      16
      18
      27 to 29
      36 to 39
      48 to 49
      57 to 69
      82 to 89
      92 to 99
      115 to 119
      127 to 131
      These fill the GCONTRL() entries 1 to 3 with incorrect values.
      GCONTRL(4) is left untouched.

      According to the TOS 4.04 source code (see GEMBIND.S) GCONTRL(4) is not
      actually used. GFA exploits this fact.