home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / oberon-a-1.4ß.lha / Oberon-A / source / amiga / Utility.mod < prev    next >
Text File  |  1994-08-08  |  22KB  |  731 lines
  1. (**************************************************************************
  2.  
  3.      $RCSfile: Utility.mod $
  4.   Description: Interface to utility.library
  5.  
  6.    Created by: fjc (Frank Copeland)
  7.     $Revision: 3.2 $
  8.       $Author: fjc $
  9.         $Date: 1994/08/08 00:45:05 $
  10.  
  11.   Includes Release 40.15
  12.  
  13.   (C) Copyright 1985-1993 Commodore-Amiga, Inc.
  14.       All Rights Reserved
  15.  
  16.   Oberon-A interface Copyright © 1994, Frank Copeland.
  17.   This file is part of the Oberon-A Interface.
  18.   See Oberon-A.doc for conditions of use and distribution.
  19.  
  20. ***************************************************************************)
  21.  
  22. MODULE Utility;
  23.  
  24. (*
  25. ** $C- CaseChk       $I- IndexChk  $L+ LongAdr   $N- NilChk
  26. ** $P- PortableCode  $R- RangeChk  $S- StackChk  $T- TypeChk
  27. ** $V- OvflChk       $Z- ZeroVars
  28. *)
  29.  
  30. IMPORT E := Exec, SYS := SYSTEM;
  31.  
  32.  
  33. (*-- Pointer declarations ---------------------------------------------*)
  34.  
  35. TYPE
  36.  
  37.   ClockDataPtr   * = CPOINTER TO ClockData;
  38.   HookPtr        * = CPOINTER TO Hook;
  39.   TagItemPtr     * = CPOINTER TO TagItem;
  40.   NamedObjectPtr * = CPOINTER TO NamedObject;
  41.  
  42.  
  43. (*-- Library definitions ----------------------------------------------*)
  44.  
  45. (*
  46. **      $VER: date.h 39.1 (20.1.92)
  47. **
  48. **      Date conversion routines ClockData definition.
  49. *)
  50.  
  51.  
  52. TYPE
  53.  
  54.   ClockData* = RECORD
  55.     sec  * : E.UWORD;
  56.     min  * : E.UWORD;
  57.     hour * : E.UWORD;
  58.     mday * : E.UWORD;
  59.     month* : E.UWORD;
  60.     year * : E.UWORD;
  61.     wday * : E.UWORD;
  62.   END; (* ClockData *)
  63.  
  64.  
  65. (*
  66. **      $VER: hooks.h 39.2 (16.6.93)
  67. **
  68. **      callback hooks
  69. *)
  70.  
  71.  
  72. TYPE
  73.  
  74. (* new standard hook structure *)
  75.   HookFunc * =
  76.     PROCEDURE (hook : HookPtr; object : E.APTR; message : E.APTR) : E.APTR;
  77.   AsmHookFunc * = PROCEDURE () : E.APTR;
  78.   (*
  79.     *** Oberon-A Note ***
  80.  
  81.     Oberon-A does not allow register parameters for normal procedures,
  82.     so if you use an AsmHookFunc, you must use SYS.GETREG to access
  83.     the parameters.  e.g:
  84.  
  85.     PROCEDURE MyHookFunc () : E.APTR
  86.       VAR hook : HookPtr; object : E.APTR; message : E.APTR;
  87.     BEGIN
  88.       SYS.GETREG (8, hook);
  89.       SYS.GETREG (10, object);
  90.       SYS.GETREG (9, message);
  91.       ...
  92.     END MyHookFunc;
  93.   *)
  94.  
  95.   Hook* = RECORD (E.MinNode)
  96.     entry   * : AsmHookFunc;   (* assembler entry point        *)
  97.     subEntry* : HookFunc;      (* often HLL entry point        *)
  98.     data    * : E.APTR;        (* owner specific               *)
  99.   END; (* Hook *)
  100.  
  101. (*
  102.  * Hook calling conventions:
  103.  *      A0 - pointer to hook data structure itself
  104.  *      A1 - pointer to parameter structure ("message") typically
  105.  *           beginning with a longword command code, which makes
  106.  *           sense in the context in which the hook is being used.
  107.  *      A2 - Hook specific address data ("object," e.g, GadgetInfo)
  108.  *
  109.  * Control will be passed to the routine hEntry.  For many
  110.  * High-Level Languages (HLL), this will be an assembly language
  111.  * stub which pushes registers on the stack, does other setup,
  112.  * and then calls the function at hSubEntry.
  113.  *
  114.  * The C standard receiving code is:
  115.  * CDispatcher( hook, object, message )
  116.  *     STRUCT Hook     *hook;
  117.  *     APTR             object;
  118.  *     APTR             message;
  119.  *
  120.  * NOTE that register natural order differs from this convention
  121.  * for C parameter order, which is A0,A2,A1.
  122.  *
  123.  * The assembly language stub for "vanilla" C parameter conventions
  124.  * could be:
  125.  
  126.  _hookEntry:
  127.         move.l  a1,-(sp)                ; push message packet pointer
  128.         move.l  a2,-(sp)                ; push object pointer
  129.         move.l  a0,-(sp)                ; push hook pointer
  130.         move.l  h_SubEntry(a0),a0       ; fetch C entry point ...
  131.         jsr     (a0)                    ; ... and call it
  132.         lea     12(sp),sp               ; fix stack
  133.         rts
  134.  
  135.  * with this function as your interface stub, you can write
  136.  * a Hook setup function as:
  137.  
  138.  SetupHook( hook, c_function, userdata )
  139.  STRUCT Hook    *hook;
  140.  ULONG          ( *c_function)();
  141.  VOID           *userdata;
  142.  {
  143.         ULONG   ( *hookEntry)();
  144.  
  145.         hook->h_Entry =         hookEntry;
  146.         hook->h_SubEntry =      c_function;
  147.         hook->h_Data =                  userdata;
  148.  }
  149.  
  150.  * with Lattice C pragmas, you can put the C function in the
  151.  * h_Entry field directly if you declare the function:
  152.  
  153. ULONG __saveds __asm
  154. CDispatcher(    register __a0 STRUCT Hook       *hook,
  155.                 register __a2 VOID              *object,
  156.                 register __a1 ULONG             *message );
  157.  *
  158.  ****)
  159.  
  160.  
  161. (*
  162. **      $VER: tagitem.h 40.1 (19.7.93)
  163. **
  164. **      extended specification mechanism
  165. *)
  166.  
  167. (*****************************************************************************)
  168.  
  169. (* Tags are a general mechanism of extensible data arrays for parameter
  170.  * specification and property inquiry. In practice, tags are used in arrays,
  171.  * or chain of arrays.
  172.  *
  173.  *)
  174.  
  175. TYPE
  176.  
  177.   Tag   * = SYS.LONGWORD;
  178.  
  179.   TagItem* = RECORD
  180.     tag*  : E.ULONG;
  181.     data* : Tag;
  182.   END; (* TagItem *)
  183.  
  184.   TagListPtr     * = CPOINTER TO ARRAY MAX (INTEGER) OF TagItem;
  185.  
  186. CONST
  187.  
  188. (* constants for Tag.tag, control tag values *)
  189.   tagDone  * = 0;    (* terminates array of TagItems. tiData unused *)
  190.   tagEnd   * = tagDone;
  191.   tagIgnore* = 1;    (* ignore this item, not end of array           *)
  192.   tagMore  * = 2;    (* tiData is pointer to another array of TagItems
  193.                       * note that this tag terminates the current array
  194.                       *)
  195.   tagSkip  * = 3;    (* skip this and the next tiData items         *)
  196.  
  197. (* differentiates user tags from control tags *)
  198.   tagUser  * = 80000000H;
  199.  
  200. (* If the tagUser bit is set in a tag number, it tells utility.library that
  201.  * the tag is not a control tag (like tagDone, tagIgnore, tagMore) and is
  202.  * instead an application tag. "USER" means a client of utility.library in
  203.  * general, including system code like Intuition or ASL, it has nothing to do
  204.  * with user code.
  205.  *)
  206.  
  207.  
  208. (*****************************************************************************)
  209.  
  210.  
  211. (* Tag filter logic specifiers for use with FilterTagItems() *)
  212.   tagFilterAND  * = 0;       (* exclude everything but filter hits   *)
  213.   tagFilterNOT  * = 1;       (* exclude only filter hits             *)
  214.  
  215.  
  216. (*****************************************************************************)
  217.  
  218.  
  219. (* Mapping types for use with MapTags() *)
  220.   mapRemoveNotFound * = 0;      (* remove tags that aren't in mapList *)
  221.   mapKeepNotFound * = 1;        (* keep tags that aren't in mapList   *)
  222.  
  223.  
  224. (*****************************************************************************)
  225.  
  226.  
  227. (*
  228. **      $VER: name.h 39.5 (11.8.93)
  229. **
  230. **      Namespace definitions
  231. **)
  232.  
  233. (*****************************************************************************)
  234.  
  235. TYPE
  236.  
  237. (* The named object structure *)
  238.   NamedObject * = RECORD
  239.     object * :  E.APTR; (* Your pointer, for whatever you want *)
  240.   END;
  241.  
  242. CONST
  243.  
  244. (* Tags for AllocNamedObject() *)
  245.   anoNameSpace * = 4000;        (* Tag to define namespace      *)
  246.   anoUserSpace * = 4001;        (* tag to define userspace      *)
  247.   anoPriority * = 4002;         (* tag to define priority       *)
  248.   anoFlags * = 4003;            (* tag to define flags          *)
  249.  
  250. (* Flags for tag anoFlags *)
  251.   nsNodups * = 0;         (* Default allow duplicates *)
  252.   nsCase * = 1;           (* Default to caseless... *)
  253.  
  254.  
  255. (*****************************************************************************)
  256.  
  257. (*
  258. **      $VER: pack.h 39.3 (10.2.93)
  259. **
  260. **      Control attributes for Pack/UnpackStructureTags()
  261. *)
  262.  
  263. (*****************************************************************************)
  264.  
  265. (* PackTable definition:
  266.  *
  267.  * The PackTable is a simple array of LONGWORDS that are evaluated by
  268.  * PackStructureTags() and UnpackStructureTags().
  269.  *
  270.  * The table contains compressed information such as the tag offset from
  271.  * the base tag. The tag offset has a limited range so the base tag is
  272.  * defined in the first longword.
  273.  *
  274.  * After the first longword, the fields look as follows:
  275.  *
  276.  *      +--------- 1 = signed, 0 = unsigned (for bits, 1=inverted boolean)
  277.  *      |
  278.  *      |  +------ 00 = Pack/Unpack, 10 = Pack, 01 = Unpack, 11 = special
  279.  *      | / \
  280.  *      | | |  +-- 00 = Byte, 01 = Word, 10 = Long, 11 = Bit
  281.  *      | | | / \
  282.  *      | | | | | /----- For bit operations