home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / misc / tornado / brief005 / Brief < prev    next >
Text File  |  1995-07-13  |  86KB  |  1,812 lines
  1. Tornado developers release 1 brief v0.05 alpha (12-07-1995)
  2.  
  3. This is a brief containing all of the formats and protocols as yet defined
  4. throughly for Tornado. Mistakes may have been made, and the data contained
  5. below is subject to change until release 1 comes out.
  6.  
  7. I strongly suggest you put this this through a printer and get it onto
  8. hardcopy as soon as possible!
  9.  
  10. You will notice how every record is of length 2^x: This is so you can use
  11. MOV Rx,<reg with no of records counted>,LSL #5 to get the logical offset in
  12. bytes into the structure list.
  13.  
  14.  
  15.  
  16.  
  17. At Tornado's private word is stored an OS_Module type block (dynamic area on
  18. a RPC - possibly on lower OS machines too (vectoring OS_ChangeDynamicArea)):
  19.  
  20. +00: ptr to start of the Tornado system heap (currently here + 64 bytes)
  21. +04: reloc ptr to subtask heap, itself a heap+ heap, within the system heap
  22. +08: reloc ptr to the Tornado tasks currently active
  23. +12: reloc ptr to the files currently in tfs:
  24. +16: reloc ptr to the current tfs: directory
  25. +20: fixed ptr to Tornado module task's user stack
  26. +24: reloc ptr to 1K of scratch space
  27. +28: reloc ptr to yeigen>=2 Tornado_SpriteOp style sprite space
  28. +32: reloc ptr to yeigen<=1 Tornado_SpriteOp style sprite space
  29. +36: reloc ptr to query windows open and their status
  30. +40: reloc ptr to list of Tornado applications currently known about through
  31.      declarations by their !Boot files
  32.      (note if this is 0 then this option has been disabled)
  33. +44 to +60: Reserved
  34. +64: start of Tornado system heap
  35. +xxx: end of Tornado system heap
  36.  
  37. ****************************************************************************
  38.  
  39. Files currently in tfs: structure:        (fixed 64 byte records)
  40. +00: reloc ptr to data (0=empty record)
  41. +04: reloc ptr to null terminated filename
  42. +08: load address
  43. +12: exec address
  44. +16: length in bytes
  45. +20: file attributes
  46. +24: OS_Monotonic time when this file was last accessed by Tornado_Getaddr
  47. +28: filetype of file (-64 if plain data)
  48.      Note that on RISC-OS to the current day the filetype is stored in the
  49.      load address, but it is also available here for future readiness.
  50. +32: handle of file fileswitch gave us (=0 if file not open)
  51. +36: sequential ptr of this file
  52. +40: id handle of the owner of this file (duplicated in the stored block)
  53. +44: reloc ptr to list of index's to subfiles
  54. +48: file index that is hotlinked above this (=0 if none)
  55. +52: file index that is hotlinked below this (=0 if none)
  56. +56: reserved
  57. +60: reserved
  58.  
  59. Notes on tfs:
  60. *  Use WimpExt_MemMove to do the memory copying, as it uses an Arm2 (erk!)
  61. optimised memory copying routine. Sorries to Arm3 users!
  62. *  Allocated space for gbpb files is identical to the file length, due to
  63. the quick access nature of RAM :-)
  64. *  FileSwitch buffer size is 1K.
  65. *  Direct unbuffered gbpb is supported.
  66. *  The file handle we pass to fileswitch is the record number of the file
  67. entry ie; the first file gets a handle 0, the second =1. Simply shift the ptr
  68. to the file's record down by six bits.
  69. *  FSEntry Args 8 uses the following code:
  70. \On entry R2=file addr R3=number of zeros to write
  71. MOV R0,R3,ASR #10        ; divide by 1024
  72. ADD R2,R2,#start addr of file in memory after extending it by R3 bytes
  73. ADR R1,zeros             ; address of 32 bytes of zeros
  74. LDMIA R1,{R3-R10}
  75. .loop
  76. {assemble this 1024/32=32 times. Works with a cache as 32*4=128bytes}
  77. STMIA R2!,{R3-R10}
  78. {end assembly loop}
  79. SUBS R0,R0,#1
  80. BNE loop
  81. *  The final note is that we won't adhere to everything specified in the
  82. PRM's, although by right we should, but then again Acorn haven't, so why
  83. should we? Specifically, sod the following:
  84.       No special fields (no one uses them anyway AFAIK)
  85.       Null length filenames
  86.       amassing all OS_Wrch output into a dynamic buffer _before_ printing it!
  87.       fancy *Cat. It will be simple, and give the same output as *Ex would.
  88.       libraries? Dunno, BBC style libraries are rather inefficient nowadays -
  89.    I'd prefer something like TornLib:.
  90.       Booting tfs: :-)
  91.       privilage bytes etc. Privs may be installed for future versions of
  92.    Tornado though.
  93.       
  94.    What we will do is:
  95.       unlimited directory depth and filename length
  96.       use of spaces and topbit chars in filenames
  97.       unlimited number of files in a directory
  98.       unlimited number of files being opened
  99.       buffered i/o whenever possible, as it improves efficiency (eg;
  100.    fileswitch and our module not having to call super-fast copying routines
  101.    just to transfer one byte :-) )
  102.       block gbpb, as well as single byte
  103.       FSEntry_Func 15, as this is used by the Filer to display its windows
  104.       Startup banner: *definately!* :-)
  105.  
  106. ****************************************************************************
  107.  
  108. Active Tornado task list structure:        (fixed 128 byte records)
  109. +00: reloc ptr to task name as passed to Tornado_Initialise (0=empty record)
  110. +04: task handle
  111. +08: task's R1 as passed from Tornado_Poll containing Wimp_Poll blk (fixed)
  112.      is on the subtask heap if this task is a subtask, otherwise in task's
  113.      memory slot
  114. +12: 0, or interval between being preempted in milliseconds
  115.      if this is negative, then preemption is currently paused
  116. +16: time given to wimp during preemption in centiseconds
  117. +20: reloc ptr to last in the list of 17,18,19 preemption poll returns
  118. +24: reloc ptr to last in the list of 1 preemption poll returns
  119. +28: reloc ptr to last in the list of all other preemption poll returns
  120. +32: fixed ptr to 256 bytes of preemption wkspace
  121. +36: reloc ptr to list of 17,18,19 message numbers that should be immediately
  122.      acknowledged.
  123. +40: reloc ptr to list of filetypes the app can load OR
  124.      if a subtask, then this is a reloc ptr to the 256 byte data block on the
  125.      subtask heap
  126. +44: reloc ptr to list of filetypes the app can save OR
  127.      if a subtask, then this is a reloc ptr to a variable length block on the
  128.      subtask heap
  129. +48: flags
  130.      bit 0: this task disabled garbaging on the system heap
  131.      bit 1: this task is a subtask
  132.      bit 2: this task has crashed, and polling has been disabled
  133. +52: more flags
  134. +56: option flags
  135. +60: more option flags
  136. +64: reloc ptr to list of query handles this task has open (=0 if none)
  137. +68: reloc ptr to list of blocks this task has claimed off the system heap
  138.      if a subtask, then is a list of blocks claimed off the subtask heap
  139. +72: reloc ptr to this task's config file
  140.      if a subtask, then this is reserved
  141. +76: reloc ptr to list of files currently loaded in by the app
  142.      if a subtask, then this is reserved
  143. +80: reloc ptr to list of subtasks currently running under this (sub)task
  144. +84 to +124: reserved
  145.  
  146. Notes on Tornado task list:
  147.    Poll return list structure:            (linked list)
  148.    +00: return code
  149.    +04: reloc ptr to next last in chain, or 0 if this is the last
  150.    +08: data as per Wimp_Poll until end of blk
  151.  
  152.    Note: for the poll return 1, data is:
  153.       +08: window handle
  154.       +12,+16,+20,+24:bounding box to be updated/redrawn in that window
  155.  
  156.    Filetype list structure:            (fixed 8 byte records)
  157.    +00: filetype
  158.    +04: flags
  159.         bit 0:don't OLE to this file unless there is no choice
  160.         bit 1:disable automated loading for this filetype
  161.  
  162.    Query window data structure:            (fixed 16 byte records)
  163.    +00: window handle of query window currently open
  164.    +04: 0=this slot empty, 1=query window active, 2=waiting for data
  165.         collection
  166.    +08: result code if applicable.
  167.    +12: reloc ptr to window's indirection space
  168.    
  169.    Currently loaded files list:            (fixed 8 byte records)
  170.    +00: reloc ptr to file data
  171.    +04: reloc ptr to list of subfiles, if any (ie; =0 if none)
  172.  
  173.    Currently running subtasks:            (fixed 16 byte records)
  174.    +00: wimp handle of subtask
  175.    +04: Tornado id slot no of subtask
  176.    +08: reloc ptr to 256 byte block
  177.    +12: reloc ptr to variable length block used for holding returned blocks
  178.  
  179. ****************************************************************************
  180.  
  181. Known Tornado applications list structure:    (fixed 16 byte records)
  182. +00: reloc ptr to task's path
  183. +04: reloc ptr to list of filetypes the app can load
  184. +08: slot number of task (=0 if not loaded right now)
  185. +12: reserved
  186.  
  187. Notes on Tornado task list:
  188.  
  189. ****************************************************************************
  190. ****************************************************************************
  191.  
  192. SWI's not definitively defined:
  193.  
  194. Tornado_IOOp - used to ensure apps don't receive serial data when they
  195. shouldn't, and to buffer output so when routing is switched back here
  196. the data isn't lost. And for general i/o, with Tornado handling the
  197. interfacing.
  198. Tornado_Status
  199. Tornado_Initialise
  200. Tornado_Poll
  201. Tornado_Closedown
  202. Tornado_SpriteOp - Tornado's superior spriteop calls
  203. Tornado_ColourTrans - Tornado's superior colourtrans calls
  204. Tornado_RenderFile - accesses library to render a file stored in system heap
  205. Tornado_StandardEntryToFS - sets what's in tfs: on startup
  206. Tornado_QCopyMem - enters into WimpExt_MoveMem currently
  207. Tornado_CopyMem - enters into WimpExt_CopyMem currently
  208. Tornado_RedrawWindow - allows a redraw of any parts of the window needing
  209. updated, and anything specified by the Tornado script.
  210.  
  211. SWI's defined for sure:
  212.  
  213. Tornado_Initheap                    (SWI &)
  214. On entry:
  215.    R0=flags
  216.       bit 0: This heap is a postslot heap
  217.       bit 1: This heap is a heap within an OS_Module block, and please
  218.              auto-extend
  219.       bit 2: This heap is a heap within a Heap+ block, and please auto-extend
  220.       bit 30: This heap being initialised is the proposed Tornado system heap
  221.    R1=ptr to proposed heap base
  222.    R2=ptr to heap base if bit 2 set
  223.    R3=length of proposed heap
  224. On exit:
  225.    R1=ptr to heap base
  226.    All registers preserved
  227. Interrupts: IRQ's enabled
  228. Processor mode: SVC
  229. Re-entrancy: Full
  230. Use:
  231. Used to initialise a Tornado Heap+ type heap. This heap format is based on
  232. OS_Heap style heaps, and offers complete internal format compatibility. In
  233. other words, you can use OS_Heap with this heap (be very careful though!),
  234. but you won't be able to use any of the extended calls.
  235.    The area of memory you intend to initialise will be verified, and header
  236. and other information written into it. Note minimum size is 128 bytes, and
  237. the base must begin on a word-aligned address. The length must be a multiple
  238. of 4 bytes.
  239.    The format of the information written into the area is not guaranteed to
  240. remain similar during releases of Tornado, but presently is this:
  241.    +00:&70616548 = "Heap", like with OS_Heap    |
  242.    +04:Offset to free list            | Note this is the standard
  243.    +08:Offset to heap base            | OS_Heap header
  244.    +12:Offset to heap end            |
  245.    +16:&18 = the Heap+ identifier - also to OS_Heap indicates a block length
  246.    +20:offset within heap to the list of relocatable blocks
  247.       +0: length of list in bytes (beginning=0)
  248.       +4: offset within heap to an allocated block descriptor
  249.    +24:offset within heap to the list of non-relocatable blocks
  250.       +0: length of list in bytes (beginning=0)
  251.       +4: offset within heap to an allocated block descriptor
  252.    +28:flags
  253.       bit 0: this heap is auto-extending using Wimp_SlotSize
  254.       bit 1: this heap is auto-extending using OS_Module
  255.       bit 2: this heap is auto-extending using Tornado_Extblk
  256.       bit 30:this heap is auto-extending as the Tornado system heap
  257.       bit 31:disable garbage collection if bit 30 set
  258.    +32: base of heap+ heap containing this heap+ heap if bit 2 of +28 is set
  259.  
  260. Also, the format of each allocated blk:
  261.    -32:usually length of block +32 bytes (for OS_Heap - not used by Tornado)
  262.    -28:status word
  263.      -1 if it can't be dumped to disc (guaranteed -1 if non-reloc)
  264.       0 if it is dumpable to disc, but currently isn't
  265.       1 if it is currently on disc, in which case +00 onwards actually
  266.         contains the pathname to the stored block data.
  267.    -24:bit 30 clear means this block is non-reloc, set means reloc
  268.        bit 29 set means this block is one of a linked list
  269.        bits 0 to 28 is the id no (ie; the slot) of the task owning this block
  270.    -20: reloc ptr of linked block before this one (=total length of data if first)
  271.    -16: reloc ptr of linked block after this one (=0 if last)
  272.    -12: reserved
  273.    -08: reserved
  274.    -04:length of data (not including this header). Negative if the data is
  275.        on disc and not in memory, which means that this block is 32+256 bytes
  276.        long, ie; =288 bytes.
  277.    +00:start of data if data is in memory, or start of null terminated
  278.        pathname if the data is on disc.
  279.  
  280. Note that if bit 0 is set then the task's slot is automatically extended by
  281. an appropriate amount and the heap set up at the previous environment end
  282. address. From now on, any extensions to the heap needed will be done
  283. automatically. Bit 1 will extend it using OS_Module; bit 2 will extend it
  284. using Tornado_Extblk.
  285.    Note also that the heap+ structure itself is relocatable - this means all heap+
  286. heaps can also be stored in a Heap+ or otherwise relocatable block.
  287.  
  288. Related calls:
  289.    All tornado heap calls;
  290.  
  291. Tornado_Getblk                        (SWI &)
  292. On entry:
  293.    R0=flags
  294.       bit 0: this block is relocatable
  295.       bit 1: give it a unique filename (used only if R1=0). Can't be used if
  296.              bit 3 is set.
  297.       bit 2: don't do a garbage collection after this call
  298.       bit 3: the data contained within this block is ready-to-save (R1=0). In
  299.              other words, this block contains a saveable file. If this bit is
  300.              clear, the file in tfs: is marked as data (filetype=-64).
  301.       bit 4: If bit 0 is set,the data in this block is to be fragmented into 
  302.              blocks of R6 length. This means special actions must be taken
  303.              when accessing the block's data. See below.
  304.       bit 5: If bit 4 set, automatically set R6 to the best value for speed.
  305.       bit 6: the data in this block also has subfiles. If this is set, then
  306.              R5 comes into play. Bit 3 must be set.
  307.    R1=heap+ ptr, 0 if system heap, -1 if subtask heap
  308.    R2=ptr to description of blk (used if R1=0 and bit 1 is clear)
  309.    R3=size of block wanted (bigger one may be granted)
  310.    R4=filetype of file if R1=0 and bit 3 is set
  311.    R5=reloc ptr to list of reloc ptr's to subfiles if bit 5 and bit 3 is set
  312.    R6=length of fragment if R1=0, bit 4 is set and bit 5 is clear.
  313. On exit:
  314.    R1=updated heap+ ptr if R1<>0 on entry
  315.    R2=flags returned
  316.       bit 0: this block has had fragmentation forced
  317.    R3=handle of block; =0 and C set if allocation failed
  318.    R6=if bit 4 set on entry, =number of fragmented blocks allocated.
  319.    All other registers preserved
  320. Interrupts: IRQ's enabled
  321. Processor mode: SVC
  322. Re-entrancy: Full, if bit 2 is set. Otherwise undefined.
  323. Use:
  324. Used to claim a block from a Heap+ heap. If R1=0 then the block is claimed
  325. from the Tornado system heap, in which case the block will also be given a
  326. filename entry in your task's account.
  327.    If you ask for a relocatable block (by setting bit 0), which is _strongly_
  328. recommended, then you will be given a handle which from hence you can use to
  329. reference the block by. It will always be a negative number, and any data
  330. contained within the block must be able to be relocated at arbitrary times.
  331. You will not know if/when/how/why the block has been moved. To get the
  332. _current_ address of the block, use Tornado_Getaddr. Read its entry for
  333. further details of use.
  334.    If you ask for a non-relocatable block, the handle will be equal to the
  335. start of the block. However, it is good programming practice to also call
  336. Tornado_Getaddr for this handle, just to be sure you are getting the address
  337. of the block (also makes sure if you change it later you won't have to change
  338. too much of your code).
  339.    Unless you specifically ask otherwise, an automatic garbage collection
  340. will be performed after this call, unless it has been disabled (only for
  341. system heap).
  342.    The block will be given a filename entry in your account if you are
  343. claiming from the system heap. This entry currently goes into the Claims
  344. directory in your folder, unless you have set bit 3, in which case it will be
  345. entered in the FileXXX directory. The unique filename given to a block if
  346. requested is currently the hexadecimal equivalent of its handle.
  347.    If bit 4 on entry is set, then the data to be contained within this block
  348. will be split up into blocks of R6 size. This is needed for virtual memory
  349. reasons, as otherwise in order to edit a 24Mb file you'd need 24Mb of RAM to
  350. store it in while it's being accessed. Splitting the 24Mb file into sections
  351. of data, each contained within its own block, means accessing the block can
  352. be done with much less RAM, typically 1Mb.
  353.    If bit 5 is set on entry, then R6 will be set to a multiple of the track
  354. size of the media upon which the blocks are being kept, less a few dozen
  355. bytes. This is because disc drives can load most efficiently when they load
  356. full tracks of data. For example, a floppy E format has 1024 byte sectors, 5
  357. sectors a track. And to load in 5120 bytes takes just as long as 1 byte.
  358. However, loading in 5121 bytes needs access to another track, and takes as
  359. long as loading in 10240 bytes. Determining how many multiples depends on
  360. memory size, and Tornado preferences.
  361.    Note on this point that you should have bit 5 set for speed, but if you
  362. have a routine that needs fixed portions of data (say a sprite plotter), then
  363. set your own R6 value. For example, a sprite plotter plotting a 2560x2048
  364. true colour sprite would use a 10240 byte fragment, as one line of such a
  365. sprite contains just that much data.
  366.    Note that if you have specified auto-extending in Tornado_Initheap call,
  367. then this call will only return an error if the entire heap couldn't be
  368. extended, otherwise it's because the heap is full.
  369.    Note also that recursion is possible here: this heap being extended by
  370. this call may cause the heap it's in to extend which may cause the heap it's
  371. in to also extend. Failure of any one of these will return an error from this
  372. command. Also, this command thus may take a while having to garbage and
  373. extend multiple heaps.
  374.    Finally, note that the block may be fragmented even if you didn't ask for
  375. it. This is because the user may wish to run in a tight-memory situation and
  376. has requested that no blocks requested over x K should be allowed to remain
  377. in memory. If you can't handle this, free the block and give an error to the
  378. user using Tornado_GiveError with message no. 1, and if the user allows the
  379. claim reclaim the failed block and continue with the operation. Make sure the
  380. operation is fully cancelled if the user so chooses though.
  381. Related calls:
  382.    All tornado heap calls;
  383.  
  384. Tornado_Freeblk                        (SWI &)
  385. On entry:
  386.    R0=flags
  387.       bit 2: don't do a garbage collection after this call
  388.    R1=heap+ ptr, 0 if system heap, -1 if subtask heap
  389.    R3=handle of block
  390. On exit:
  391.    R1=updated heap+ ptr if R1<>0 on entry
  392.    All other registers preserved
  393. Interrupts: IRQ's enabled
  394. Processor mode: SVC
  395. Re-entrancy: Full
  396. Use:
  397. Used to free a claimed block.
  398.    Unless you specifically ask otherwise, an automatic garbage collection
  399. will be performed after this call, and if auto-extending is set, then the
  400. heap will be automatically shrunk if possible. This, as above, may lead to
  401. all heaps in the tree above to shrink as well. Thus, this command may take a
  402. while having to garbage and shrink multiple heaps.
  403. Related calls:
  404.    All tornado heap calls;
  405.  
  406. Tornado_Extblk                        (SWI &)
  407. On entry:
  408.    R0=flags
  409.       bit 2: don't do a garbage collection after this call
  410.    R1=heap+ ptr, 0 if system heap, -1 if subtask heap
  411.    R2=signed change in bytes
  412.    R3=handle of block
  413. On exit:
  414.    R1=updated heap+ ptr if R1<>0 on entry
  415.    R2=new size of block
  416.    R3=new handle of block
  417.    All other registers preserved
  418. Interrupts: IRQ's enabled
  419. Processor mode: SVC
  420. Re-entrancy: Full
  421. Use:
  422. Used to change the size of a claimed block. If R1=0, the filename in tfs:
  423. remains unchanged.
  424.    Note that the new size of the block may be larger than you intended. This
  425. is alright: just take care to redo any future resizing decisions (ie; if
  426. storing the size, don't store previous size - amount requested to decrease
  427. by, store the size returned by R2).
  428.    The new handle for the block will be the same if the block was
  429. relocatable, but note it is good programming practice if you restore the
  430. handle anyway, in case you may later have to alter the relocatable nature of
  431. the data.
  432.    Unless you specifically ask otherwise, an automatic garbage collection
  433. will be performed after this call, and the repercussions are as for
  434. Tornado_Getblk and Tornado_Freeblk.
  435. Related calls:
  436.    All tornado heap calls;
  437.  
  438. Tornado_Getsize                        (SWI &)
  439. On entry:
  440.    R1=heap+ ptr, 0 if system heap, -1 if subtask heap
  441.    R3=handle of block
  442. On exit:
  443.    R2=current size of block
  444.    R3=fragment size if the block is fragmented
  445.    All other registers preserved
  446. Interrupts: IRQ's enabled
  447. Processor mode: SVC
  448. Re-entrancy: Full
  449. Use:
  450. Used to determine the current size of a block.
  451. Related calls:
  452.    All tornado heap calls;
  453.  
  454. Tornado_HeapInfo                    (SWI &)
  455. On entry:
  456.    R1=heap+ ptr, 0 if system heap, -1 if subtask heap
  457. On exit:
  458.    R0=size of heap
  459.    R1=heap base, filled in if R1=0 on entry
  460.    R2=largest free block in heap
  461.    R3=amount of free space available
  462.    R4=number of relocatable blocks in heap
  463.    R5=number of non-relocatable blocks in heap
  464.    R6=bytes occupied by relocatable blocks
  465.    R7=bytes occupied by non-relocatable blocks
  466.    All other registers preserved
  467. Interrupts: IRQ's enabled
  468. Processor mode: SVC
  469. Re-entrancy: Full
  470. Use:
  471. Used to determine the current state of a heap+ heap.
  472. Related calls:
  473.    All tornado heap calls;
  474.  
  475. Tornado_ExtHeap                        (SWI &)
  476. On entry:
  477.    R1=heap+ ptr
  478.    R2=signed change in size
  479. On exit:
  480.    R2=new size
  481.    All other registers preserved
  482. Interrupts: IRQ's enabled
  483. Processor mode: SVC
  484. Re-entrancy: Full
  485. Use:
  486. Used to manually change the size of a Heap+ heap. Usually automated. Note
  487. this may cause auto-extending heaps above this to garbage and also change
  488. size.
  489. Related calls:
  490.    All tornado heap calls;
  491.  
  492. Tornado_Getaddr                        (SWI &)
  493. On entry:
  494.    R0=flags
  495.       bit 0: make data loaded contiguous, and load R4 bytes
  496.    R1=heap+ ptr, 0 if system heap, -1 if subtask heap
  497.    R2=offset within block you wish to access (if block fragmented)
  498.    R3=handle of block
  499.    R4=number of bytes to be made contiguous
  500. On exit:
  501.    R2=actual address of block (points to offset given by R2)
  502.    R3=actual address of the start of this block in memory, or reloc handle of
  503.       block if bit 0 was set on entry
  504.    R4=number of bytes from R2 you can access before you must call this SWI
  505.       again
  506.    All other registers preserved
  507. Interrupts: IRQ's enabled
  508. Processor mode: SVC
  509. Re-entrancy: Full
  510. Use:
  511. Used to determine the actual address of a claimed block. If the handle passed
  512. is non-negative, then the same handle is currently returned in R2.
  513.    The offset contained within R2 is the patch of data within the block you
  514. wish to access. This should be given even if the block isn't fragmented, as
  515. the user may have specified that a cap be placed on requests.
  516.    You can work out what memory can be accessed using R3 ie; you won't need
  517. to call this SWI to access as far as this. You can still do anyway, and this
  518. call is quite quick so little difference in speed will be noticed.
  519.    Note you can only access R4 bytes from where you asked for. This is
  520. because only that much data has been loaded within that block.
  521.    Setting bit 0 on entry means that a new reloc block is created of R4
  522. bytes, and one or more fragmented blocks are loaded into it to make it a
  523. contiguous area of data. Make sure that when you're finished with this block
  524. and the data (ie; before calling Tornado_Getaddr again), free the block. Note
  525. finally that setting bit 0 is quite slow in operation, and having blocks
  526. already in memory doesn't matter - they remain in memory - and thus, quite a
  527. lot of memory can be wasted. Use a routine capable of using fixed size data
  528. blocks to manipulate the data if possible.
  529.    This call also resets the time elapsed since last access to this block, or
  530. fragment of a block. This is used for virtual memory, where when the system
  531. heap becomes full the oldest blocks get dumped to disc. Using this call
  532. indicates that you want to use this block. If the block is currently on disc,
  533. it is reloaded into the heap and its address returned to you. Note no garbage
  534. collection occurs when this happens.
  535.    You can be guaranteed that this address will remain the same until the
  536. next specific call to Tornado_<call>, as all the calls done under
  537. interrupts/vectors etc. by Tornado do not garbage collect the heap.
  538.    PLEASE NOTE: When preempting code and referring to the system heap, you
  539. MUST use Tornado_GarbageHeap to force disabling of garbaging. If you do this,
  540. you must be prepared to regularly do a Tornado_GarbageHeap followed with
  541. another Tornado_Getaddr to ensure fragmentation does not become endemic. This
  542. is because other Tornado apps may cause the heap to be garbaged.
  543. Related calls:
  544.    All tornado heap calls;
  545.  
  546. Tornado_GarbageHeap                    (SWI &)
  547. On entry:
  548.    R0=flags
  549.       bit 0:disable auto-garbaging (if R1=0)
  550.       bit 1:reenable auto-garbaging (if R1=0)
  551.       bit 2:do not garbage heap
  552.    R1=0, the system heap
  553. On exit:
  554.    R1=updated heap+ ptr if R1<>0 on entry
  555.    All other registers preserved
  556. Interrupts: IRQ's enabled
  557. Processor mode: SVC
  558. Re-entrancy: Full
  559. Use:
  560. Used to disable auto-garbaging on the system heap, and to force a garbage
  561. collection.
  562.    If bit 0 is set, garbaging on the system heap is disabled and it is stored
  563. that it was your task which requested it.
  564.    Note that this call may not garbage the heap if someone else has disabled
  565. it (R1=0, system heap). Also, if reenabling garbaging and no-one else has
  566. disabled it, an immediate garbage is done.
  567.    This call with flags %000 is performed after every Tornado_Getblk,
  568. Tornado_Freeblk and Tornado_Extblk. If the system heap isn't being referred
  569. to then there is nothing the task can do to stop auto-garbaging ie; you
  570. cannot disable garbaging on private Heap+ heaps.
  571.    Note again treed auto-extending heaps may have to garbage and change size.
  572. Related calls:
  573.    All tornado heap calls;
  574.  
  575. Tornado_DrawHeap                    (SWI &)
  576. On entry:
  577.    R0=flags
  578.       bit 0: render as a OS_Heap style heap (ie; compatible with OS_Heap)
  579.              if set, use R7 as allocated, R8 ignored and preserved
  580.    R1=heap+ ptr, 0 if system heap, or an OS_Heap ptr (if so set bit 0)
  581.    R2=x pos of left (inc)        R3=y pos of bottom (inc)
  582.    R4=x pos of right (inc)        R5=y pos of top (inc)
  583.    R6=&BBGGRR00 of free space
  584.    R7=&BBGGRR00 of reloc blocks, or allocated blocks if bit 0 set
  585.    R8=&BBGGRR00 of non-reloc blocks
  586. On exit:
  587.    All registers preserved
  588. Interrupts: IRQ's enabled
  589. Processor mode: SVC
  590. Re-entrancy: None
  591. Use:
  592. This call renders a graph of the heap pointed to by R1. The graph is squashed
  593. into the bounding box as specified R2,R3,R4,R5, and the Tornado_ColourTrans
  594. call is used to calculate anti-aliasing to display detail not possible with
  595. the available screen resolution. This is why the colours are specified using
  596. the absolute 24 bit method.
  597.    Note this call is provided for the exclusive use of the Tornado graphic
  598. renderer used to render heaps. Do not use otherwise.
  599. Related calls:
  600.    All tornado heap calls; Tornado_ColourTrans
  601.  
  602. Tornado_StartPreemption                    (SWI &)
  603. On entry:
  604.    R0=interval in ms given to Wimp (may be overriden by !Options or by
  605.       general decree)
  606.    R1=reloc ptr to list of 17,18,19 messages that should be acknowledged.
  607. On exit:
  608.    All registers preserved
  609. Interrupts: IRQ's enabled
  610. Processor mode: SVC
  611. Re-entrancy: None
  612. Use:
  613. This call starts premption on the Tornado task calling it, or restarts it if
  614. preemption is paused. Any result codes returned are stored in the Tornado
  615. system heap until they can be collected by the task.
  616.    Note the following restrictions that must be observed while under
  617. preemption:
  618.    1: Any relocatable blocks in the system heap are liable to move due to
  619. another task doing ops on the system heap. Thus, getting the address of a
  620. block using Tornad_Getaddr and using it cannot be done as the address may
  621. change in mid-processing. To get around this, set up a post-slot heap, which
  622. is very easy using Tornado_InitHeap, and allocate all your preemptive code
  623. data requirements from it. If you _must_ access a block in the system heap,
  624. copy the system heap block into your own postslot heap, and do the processing
  625. there, recopying it back after (preemption won't occur during all SWI's
  626. running in SVC mode so you shouldn't need to disable garbaging if you're
  627. using Tornado_QCopyMem).
  628.    However, it may be possible that all the processing must be done on a
  629. block in the system heap, and it must remain there during processing because
  630. something else is relying on the *_absolute_* latest results (this is NOT
  631. encouraged), or perhaps altering data there in response to your alterations
  632. (note then that you should really use Tornado_SendMessage then). If this is
  633. the case, disable garbaging using Tornado_GarbageHeap and do your processing
  634. _as_ _quickly_ _as_ _possible_ in fragments, and in between fragments
  635. reenable garbaging, do your return code enumeration, and return to processing
  636. with another Tornado_Getaddr. This is to prevent fragmentation which happens
  637. alarmingly quickly if garbaging is disabled, especially if virtual memory is
  638. enabled. It is possible two apps are disabling garbaging, and one still has
  639. it disabled when the other reenables it. If this is the case, which is
  640. _extremely_ unlikely, too bad.
  641.    Note that rather than this 'desperate' approach, one can use the quick
  642. memory copying routines of Tornado to copy in and out data more than might be
  643. necessary in order to keep the data very up-to-date.
  644.    2: You should call Tornado_EnumPreemptResults to pick up on any return
  645. codes that have occurred during processing. By right you should enumerate all
  646. the codes until C becomes set, but if you are pushing processing speed to the
  647. limits (unlikely as you are depending on other tasks anyway), you may go as
  648. far as the end of 17,18 & 19. However, if absolutely possible, do process
  649. code 1, as these tend to not only fill up memory rather quickly, but
  650. unprocessed they also leave the display in your windows blank, which is
  651. rather a characteristic of preempted code, and annoying to say the least (it
  652. gives the user a rather false impression of the app being slow).
  653.    Be warned that certain return codes issued by the Wimp and others assume a
  654. reply before the next Wimp_Poll: here you have no such luxury. You can enter
  655. a list of 17,18,19 codes to acknowledge immediately, but this isn't a perfect
  656. solution. TBH, avoid preemption if possible: the Wimp was never designed for
  657. it, and actively inhibits it.
  658.    It may be possible that you have to disable menus etc. during this. Try
  659. not to - grey out menu options etc, and remove changing pointers in the
  660. appropriate places. Tornado has been structured as so as much application
  661. availability is present during preemption as possible: please use it!, and
  662. write your code to accomodate. It's usually not difficult anyway. Note not
  663. having full application presence at any time, unless it's another apps fault,
  664. will mean your program will automatically fail any Tornado standards test it
  665. may be put through.
  666.    3: Finally, ask yourself why you want to preempt this code? Is it /really/
  667. necessary, for example in order to prevent polling becoming uneven during
  668. complex code? Are you doing a specific task or process, like doing an
  669. operation on a file? If you are, you should be using subtasks, not
  670. preemption. Preemption is here for use with places where normal polling is
  671. difficult, or inconvenient, like when loading Templates, although of course
  672. Tornado does that for you; another place is loading in a difficult file
  673. format, although if it is a standard file format (eg; Lotus 123 spreadsheet)
  674. then you should have written a subtask file convertor to change the file into
  675. one you can read easily (Tornado does this for you).
  676.  
  677. Also note that during action on code 1, preemption should be disabled during
  678. the loop between Wimp_UpdateWindow and Wimp_GetRectangle. Using
  679. Tornado_RedrawWindow, which you should do, does this automatically.
  680. Related calls:
  681.    Tornado_EnumPreemptResults; Tornado_PausePreemption;
  682.  
  683. Tornado_EnumPreemptResults                (SWI &)
  684. On entry: Nothing
  685. On exit:
  686.    R0=reason code, 0=preemption now finished
  687.    The data as per Wimp_Poll is filled into the Wimp_Poll R1 as specified to
  688.    Tornado_Initialise, except for reason code 1, where:
  689.    R1+00: window handle to be redrawn
  690.    R1+04,+08,+12,+16: bounding box, all inclusive.
  691.    R1=ptr to return code data, as specified in Tornado_Initialise
  692.    The C bit is set if this is the last entry
  693.    All other registers preserved
  694. Interrupts: IRQ's enabled
  695. Processor mode: SVC
  696. Re-entrancy: None
  697. Use:
  698. This call removes the codes returned during preemption from memory and stores
  699. them in task's memory at R1. The only different one is code 1, which instead
  700. of pointing to Wimp_Poll return block points to a box in a window to be
  701. redrawn using Tornado_RedrawWindow.
  702.    Please read the restrictions and conditions attached to using preemption
  703. in the SWI entry Tornado_StartPreemption.
  704.    When the call returns with C set, then this is the last return code
  705. stored. If you wish to shut down preemption, call the SWI again and R0 should
  706. be 0. However, be prepared for it being non-zero, and possibly with C set
  707. again. Again, do not depend of C being set. Ie; to stop preemption, keep
  708. calling Tornado_EnumPreemptResults and acting on the codes until R0 returns
  709. with zero. Conversely, if you wish to enumerate and act upon all the codes
  710. currently stored, call this SWI until C returns set: then return to
  711. processing.
  712.    Another option, if you wish to quicken processing, is to do say 25 returns
  713. and then return to processing. Again, doing this will fail any Tornado
  714. standards test.
  715.    Finally, if preemption is disabled when this call is made, it is
  716. reenabled.
  717. Related calls:
  718.    Tornado_StartPreemption, Tornado_PausePreemption
  719.  
  720. Tornado_PausePreemption                    (SWI &)
  721. On entry: Nothing
  722. On exit: All registers preserved
  723. Interrupts: IRQ's enabled
  724. Processor mode: SVC
  725. Re-entrancy: Full
  726. Use:
  727. This call pauses preemption. It is needed during code done from replies in
  728. which having a poll would be fatal (eg; redraw code). Tornado_RedrawWindow
  729. does this automatically for you, and by right you should be using this call
  730. anyway.
  731.    Note this does _not_ /stop/ preemption: merely pauses it. It is not a good
  732. idea to not restart preemption and continue on with your code.
  733.    Finally, note that this call merely prevents Wimp_Poll being called, and
  734. user code is still interrupted as usual (actually, interrupts increase as it
  735. is taken the callback has failed (say because of RMA failure) and so the
  736. interrupt is rescheduled for much sooner than usual).
  737. Related calls:
  738.    Tornado_StartPreemption, Tornado_EnumPreemptResults;
  739.  
  740. Tornado_Hourglass                    (SWI &)
  741. On entry: R0=hourglass reason code
  742.           other registers change with reason code, see below.
  743. On exit: returned registers change with reason code, see below.
  744. Interrupts: IRQ's enabled
  745. Processor mode: SVC
  746. Re-entrancy: Probably none
  747. Use:
  748. This command performs operations on the Tornado hourglass. These are the
  749. currently used reason codes:
  750.    0: wake hourglass with 'multitasking process' showing
  751.    1: turn hourglass off
  752.    2: wake hourglass with 'load' showing
  753.    3: wake hourglass with 'save' showing
  754.    4: wake hourglass with 'process' showing
  755.    5: smash hourglass, irrespective of count
  756.    6: wake hourglass with a percentage of task completed.
  757.       takes value 0-100 in R1
  758.    7: wake hourglass with time to go displayed.
  759.       takes value of time to go in cs in R1
  760.    16:specify wait in cs before hourglass should be shown when called above
  761.       takes time in cs in R1, if -1 then suppress hourglass, 0 to desuppress
  762. Related calls:
  763.    *THourglass;
  764.  
  765. Tornado_Query                    (SWI &)
  766. On entry: R0=flags
  767.              bits 0 & 1: type of button default button is
  768.                 %00:press and this goes away
  769.                 %01:press, and an action is done
  770.                 others reserved
  771.              bits 2 & 3: type of button opposite button is
  772.                 same as for bits 0 & 1
  773.              bits 4 & 5: type of button auxillary button is
  774.                 same as for bits 0 & 1
  775.              bit 6: return even if no selection has been made
  776.              bit 7: I am checking current status
  777.           R1=ptr to null terminated title, or a handle (see below)
  778.              title should be one of:
  779.              "Query from <appname>:"
  780.              "Message from <appname>:"
  781.              "Error from <appname>:"
  782.           R2=ptr to null terminated text for default button
  783.           R3=ptr to null terminated text for opposite to default button
  784.           R4=ptr to null terminated text for auxillary button
  785. On exit: R0=reason code
  786.             0:pending result, in which case R1 comes into play
  787.             1:default button selected
  788.             2:opposite button selected
  789.             3:auxillary button selected
  790.          R1=query handle if R0=0,otherwise preserved
  791.          All other registers preserved
  792. Interrupts: IRQ's enabled
  793. Processor mode: USR
  794. Re-entrancy: None
  795. Use:
  796. This call opens a query window to either give information or ask a question.
  797. The flags specified in R0 determine what the pointer changes to over the
  798. button, ie; between a hand and a magic wand. This is so the user knows that
  799. by pressing this button something will happen. With the magic wand ptr, it
  800. means that pressing this button will cause a defined action as given byt the
  801. text within the button, like writing to a disc, whereas the hand ptr
  802. indicates that pressing this will pretty much make this window go away.
  803.    You can ask for control to be returned to you before the user makes a
  804. selection, but note then you must regularly call this SWI with bit 7 set to
  805. determine if the user has made a choice. Note also not to expect the user to
  806. reply at all.
  807.    Note this facility can be automated from flags in Tornado_Initialise, in
  808. which case checking is done automatically and returned if necessary to you
  809. through Tornado_Poll. It is suggested you make use of this.
  810. Related calls:
  811.    *TMess; *TError;
  812.  
  813. Tornado_GiveError                    (SWI &)
  814. On entry: R0=flags
  815.           bit 0: this is a message, not an error. Ie; use 'Message from' in
  816.           the title and provide only the first button.
  817.           R1=number of error message to give. See below.
  818.           R2=%0, R3=%1 ...
  819. On exit: R0=reason code
  820.             1: first button chosen
  821.             2: second button chosen
  822.             3: third button chosen
  823.          All other registers preserved
  824. Interrupts: IRQ's enabled
  825. Processor mode: USR
  826. Re-entrancy: None
  827. Use:
  828. This call calls Tornado_Query for you with a standard error message. The
  829. currently defined error messages are:
  830.    0: "This application recommends having !System, the system resources
  831. folder, present and available during operation. Without its presence the
  832. application may not function correctly. Do you wish to continue anyway?",
  833. "No", "Yes"
  834.    1: "This application recommends having !Scrap, the system scrap file
  835. folder, present and available during operation. Without its presence the
  836. application may not function correctly. Do you wish to continue anyway?",
  837. "No", "Yes"
  838.    2: "This application recommends having the outline font renderer loaded
  839. in, operating correctly and available during operation. Without its presence
  840. the application may not function correctly. Do you wish to continue anyway?",
  841. "No", "Yes"
  842.    3: "This application recommends having !Fonts, the system fonts storage
  843. folder, present and available during operation. Without its presence the
  844. application may not function correctly. Do you wish to continue anyway?",
  845. "No", "Yes"
  846.    4: "Due to the absence of outline fonts, contained in !Fonts, this
  847. application has defaulted to using <%0> font instead. You may show the
  848. !Fonts folder later, and the application will then be able to use them"
  849.    5: "This application needs to have !Fonts, the system fonts storage
  850. folder, present and available during operation. Without its presence the
  851. application will not function correctly. Do you wish to continue anyway?",
  852. "No", "Yes"
  853.    6: "This application needs to have at least v<%0> of <%1>, the <%2> loaded
  854. in and running. Unfortunately, no such module can be found anywhere on your
  855. system, and it is unlikely that without this, this application will function
  856. correctly. Do you wish to continue anyway?", "No", "Yes"
  857.    7: "This application needs to have at least v<%0> of <%1>, the <%2> loaded
  858. in and running. Unfortunately, I cannot find such a copy anywhere in your
  859. system. The currently present version is v<%3>; do you wish to continue
  860. anyway?", "No", "Yes"
  861.    8: "This application needs to have at least v<%0> of <%1>, the <%2> loaded
  862. in and running. After noting the currently loaded copy of that module was
  863. v<%3>, Tornado checked the copy in !System and found it was also too old,
  864. being of v<%4>. What do you wish to do?", "Cancel execution of program",
  865. "Continue with execution", "Load in copy from !System and continue"
  866.    12: "This application was refused a memory request as you have placed a
  867. cap on solid memory claims, and this application needs to claim <%0>K of
  868. solid memory to perform the requested operation. Do you wish to allow this
  869. claim?", "Yes", "No", ""
  870.    256: "Please wait: loading in v<%0> of <%1>, the <%2> from !System ...",
  871. "", "", ""
  872.    257: "Please wait: replacing v<%3> of <%1>, the <%2> with v<%0> from
  873. !System ...", "", "", ""
  874.    258: "Warning: Tornado is about to replace v<%3> of <%1>, the <%2> with
  875. v<%0> from !System. Do you wish to stop this?", "No", "Yes", ""
  876. Related calls:
  877.    *TMess; *TError;
  878.  
  879. Tornado_Initialise                (SWI &)
  880. On entry: R0=latest version of Tornado known by this task * 100
  881.           R1=ptr to 256 byte block in task's slot
  882.           R2=ptr to short description of task (null terminated)
  883.           R3=flags
  884.              bit 0: I don't want to become a wimp task (NOT SUPPORTED YET!)
  885.              bit 30: The task being started is a Tornado subtask (internal)
  886. On exit: R0=current version of Tornado * 100
  887.          R1=task handle given by the Wimp
  888.          R2=current version of the Wimp * 100
  889.          R3=slot number this task has been given
  890.          R4=ptr to environment string (ie; parameters)
  891.          R5=reloc ptr to config file
  892.          All other registers preserved
  893. Interrupts: IRQ's enabled
  894. Processor mode: SVC
  895. Re-entrancy: None
  896. Use:
  897. This call declares the CAO to be a Tornado task, and it wishes to also become
  898. a Wimp task. A new record is entered into Tornado's data records and the task
  899. becomes an official part of Tornado. From now on, this task must comply with
  900. all Tornado regulations and will have many things done for it.
  901.    What happens upon this call:
  902. * Tornado calls Wimp_Initialise with suitable parameters
  903. * Tornado finds a free record and enters this task into it
  904. * Tornado does a OS_GetEnv and reads in the parameters, checking for any
  905. Tornado specific ones, acting if present
  906. * Tornado opens the file "<path from environment string>.TData", and reads in
  907. the data
  908. * Tornado loads in the configuration file, the location of which can be
  909. anywhere really (ie; don't assume it's in !<appname>.!Config).
  910. Related calls:
  911.    *TMess; *TError;
  912.  
  913. Tornado_Closedown                (SWI &)
  914. On entry: R0=0 if simple shutdown,
  915.             =1 if call OS_Exit for me,
  916.             otherwise ptr to exiting error block
  917.           R1=task handle given by Wimp (optional)
  918.           R2=Tornado slot number given in Wimp_Initialise (optional)
  919. On exit: All registers preserved, but never returns if R0=1 on entry
  920. Interrupts: IRQ's enabled
  921. Processor mode: SVC
  922. Re-entrancy: None
  923. Use:
  924. This call closes down the current Tornado task. In addition to removing all
  925. data pointers associated with the task from memory, it also:
  926. * Calls Wimp_CloseDown
  927. * Shuts any open files this CAO has opened during execution
  928. * Shuts down any subtasks belonging to this task currently running, and any
  929. siblings of those subtasks.
  930. * deallocates any blocks claimed by this task during execution from the
  931. system heap
  932. * removes the account for this task from tfs:
  933. Related calls:
  934.    Tornado_Initialise;
  935.  
  936. Tornado_Poll                    (SWI &)
  937. On entry: R0=mask as per Wimp_Poll
  938.           R1=flags
  939.              bit 0: Return in R2 cs if possible (NOT GUARANTEED)
  940.           R2=time given to Wimp in cs
  941. On exit: R0=return code (see below)
  942.          R1=ptr to 256 byte block used to contain data
  943.          All other registers preserved
  944. Interrupts: IRQ's enabled
  945. Processor mode: SVC
  946. Re-entrancy: None
  947. Use:
  948. This call is the Tornado duplicate of Wimp_Poll and should be called as
  949. frequently as possible.
  950.    The reason codes returned are:
  951.      -4: Subtask control messsage
  952.          R1+00: subtask return code, which can be:
  953.             =0: subtask that was run is not a subtask
  954.                R1+04: reason why Tornado thinks this
  955.                     =0: subtask didn't call Tornado_InitialiseSubtask within
  956.                         the first five seconds
  957.             =1: subtask failed to start up
  958.                R1+04: reason why:
  959.                     =0: an error occurred before it called
  960.                         Tornado_InitialiseSubtask
  961.                       R1+08: standard error block
  962.                     =1: an error occurred while the subtask was being loaded
  963.                         in:
  964.                       R1+08: standard error block
  965.                     =2: an error occurred as the subtask was begun as the CAO
  966.                       R1+08: standard error block
  967.             =2: subtask has begun, and has called Tornado_InitialiseSubtask
  968.                R1+04: task handle of subtask
  969.                R1+08: id no of subtask
  970.                R1+12: memory given to subtask
  971.             =3: message from subtask
  972.                R1+04: task handle of subtask
  973.                R1+08: id no of subtask
  974.                R1+12 onwards: message sent
  975.             =4: subtask has ended prior to completion
  976.                R1+04: task handle of subtask
  977.                R1+08: id no of subtask
  978.                R1+12: standard error block
  979.             =5: subtask has ended, having completed processing
  980.                R1+04: task handle of subtask
  981.                R1+08: id no of subtask
  982.      -3: In one form or other, the user has loaded/wants to load a file.
  983.          Note that this should be treated as 'replacing' an existing file,
  984.          even if the file is dragged onto the icon bar (ie; creating a new
  985.          file). So if the user drags a file onto a frame in a DTP page, the
  986.          file within that frame should be replaced if possible, and the data
  987.          previously contained in the frame thrown away.
  988.          If bit 1 in Tornado_Initialise was set then:
  989.            User has just loaded a file:
  990.              R1+0: method used to load file:
  991.                =0: loaded from the filer
  992.                   R1+04: handle of window user dragged to (-2 if icon bar)
  993.                   R1+08: icon handle if any
  994.                   R1+12: x pos of mouse (absolute)
  995.                   R1+16: y pos of mouse (absolute)
  996.                   R1+20: length of file
  997.                   R1+24: filetype of this file
  998.                   R1+28: original filetype of this file (may be same)
  999.                   R1+32: (5 bytes) datestamp of this file
  1000.                   R1+37: (byte) type of this file from OS_File,5
  1001.                   R1+38: (2 single bytes) reserved
  1002.                   R1+40: reloc handle of block containing loaded file
  1003.                   R1+44: handle of task this file came from
  1004.                   R1+48: handle of window this file came from
  1005.                   R1+52 to +255: (string) pathname of file
  1006.                =1: loaded by someone copying into your a/c
  1007.                   R1+04: -2 always ie; create a new file
  1008.                   R1+08: undefined
  1009.                   R1+12: undefined
  1010.                   R1+16: undefined
  1011.                   R1+20: length of file
  1012.                   R1+24: filetype of this file
  1013.                   R1+28: original filetype of this file (may be same)
  1014.                   R1+32: (5 bytes) datestamp of this file
  1015.                   R1+37: (byte) type of this file from OS_File,5
  1016.                   R1+38: (2 single bytes) reserved
  1017.                   R1+40: reloc handle of block containing loaded file
  1018.                   R1+44: undefined
  1019.                   R1+48: undefined
  1020.                   R1+52 to +255: (string) pathname of file in tfs:
  1021.                =2: loaded from another application. Note this happens when
  1022.                    the user drags a file out of another app into this one.
  1023.                   R1+04: handle of window user dragged to (-2 if icon bar)
  1024.                   R1+08: icon handle if any
  1025.                   R1+12: x pos of mouse (absolute)
  1026.                   R1+16: y pos of mouse (absolute)
  1027.                   R1+20: length of file
  1028.                   R1+24: filetype of this file
  1029.                   R1+28: original filetype of this file (may be same)
  1030.                   R1+32: (5 bytes) datestamp of this file
  1031.                   R1+37: (byte) type of this file from OS_File,5 (usually 1)
  1032.                   R1+38: (2 single bytes) reserved
  1033.                   R1+40: reloc handle of block containing loaded file
  1034.                   R1+44: handle of task this file came from
  1035.                   R1+48: handle of window this file came from
  1036.                   R1+52 to +255: (string) pathname of file
  1037.                =3: loaded by Tornado OLE. Note that this call is also issued
  1038.                    to an OLE client ie; a task which is already editing an
  1039.                    OLEd file, in order to update zooms, move the editor
  1040.                    window etc. In other words, check words +44 to +52 before
  1041.                    creating a new file. Word +40 will always remain the same
  1042.                    during an OLE operation. Do not rely on other data though.
  1043.                   R1+04: -2 always, ie; create a new file
  1044.                   R1+08: undefined
  1045.                   R1+12: undefined
  1046.                   R1+16: undefined
  1047.                   R1+20: length of file
  1048.                   R1+24: filetype of this file
  1049.                   R1+28: original filetype of this file (may be same)
  1050.                   R1+32: (5 bytes) datestamp of this file
  1051.                   R1+37: (byte) type of this file from OS_File,5 (usually 1)
  1052.                   R1+38: (2 single bytes) reserved
  1053.                   R1+40: reloc handle of block containing loaded file
  1054.                   R1+44: handle of task this file came from
  1055.                   R1+48: handle of window this file came from
  1056.                   R1+52: id to know this file by
  1057.                Note the following coords are absolute and should be scaled
  1058.                before being used if necessary.
  1059.                   R1+56: min x of your editor window (-1 if open normally)
  1060.                   R1+60: min y of your editor window
  1061.                   R1+64: max x of your editor window
  1062.                   R1+68: max y of your editor window
  1063.                   R1+72: x multiplier (seperate from the screen res scaling)
  1064.                   R1+76: y multiplier
  1065.                   R1+80: x divisor
  1066.                   R1+84: y divisor
  1067.                Note that in the title and info boxes concerned with this
  1068.                file, you should show which task the file came/is from
  1069.                =4: loaded from simple OLE. Essentially, when Tornado OLE
  1070.                    fails then a DataOpen is broadcast, and any app picking it
  1071.                    up is given a filename in tfs:$.<appname>.OLE.*, and after
  1072.                    editing the file is saved back, Tornado picks this up and
  1073.                    replies to the original task through this entry.
  1074.                   R1+04: handle of the window the user originally OLEd file
  1075.                          from
  1076.                   R1+08: undefined
  1077.                   R1+12: undefined
  1078.                   R1+16: undefined
  1079.                   R1+20: length of file
  1080.                   R1+24: filetype of this file (will be the same as your
  1081.                          older copy)
  1082.                   R1+28: original filetype of this file (may be same)
  1083.                   R1+32: (5 bytes) datestamp of this file
  1084.                   R1+37: (byte) type of this file from OS_File,5 (usually 1)
  1085.                   R1+38: (2 single bytes) reserved
  1086.                   R1+40: reloc handle of block containing loaded file
  1087.                   R1+44: handle of task this file came from
  1088.                   R1+48: handle of window this file came from
  1089.                   R1+52: pathname of file, usually something like "tfs:<app
  1090.                          name>.OLE.*". See Tornado_InitOLE.
  1091.                =5: loaded by hotlink. This code is returned to replace a file
  1092.                    currently loaded in, as this file is hotlinked to another
  1093.                    file being edited in another application.
  1094.                   R1+04: handle of the window the user originally OLEd file
  1095.                          from
  1096.                   R1+08: undefined
  1097.                   R1+12: undefined
  1098.                   R1+16: undefined
  1099.                   R1+20: length of file
  1100.                   R1+24: filetype of this file (will be the same as your
  1101.                          older copy)
  1102.                   R1+28: original filetype of this file (may be same)
  1103.                   R1+32: (5 bytes) datestamp of this file
  1104.                   R1+37: (byte) type of this file from OS_File,5 (usually 1)
  1105.                   R1+38: (2 single bytes) reserved
  1106.                   R1+40: reloc handle of block containing loaded file
  1107.                   R1+44: handle of task this file came from
  1108.                   R1+48: handle of window this file came from
  1109.                   R1+52: id of file
  1110.      -2: A query window has been answered
  1111.      -1: An i/o operation has terminated
  1112.          R1+0: result code
  1113.            =0: i/o failed
  1114.            =1: i/o succeeded
  1115.          R1+4: handle of i/o task
  1116.          R1+8: error block if applicable     
  1117.      00: Null reason code, no other code applicable
  1118.      01: Redraw window request (call Tornado_RedrawWindow)
  1119.      02: Open window
  1120.      03: Close window
  1121.      04: Pointer leaving window (call Tornado_AlterPointer)
  1122.      05: Pointer entering window (ditto)
  1123.      06: Mouse click has occurred
  1124.      07: User has finished dragging a box
  1125.      08: User has pressed a key
  1126.      09: User has selected a menu option
  1127.      10: User has scrolled a window
  1128.      11: You have lost ownership of the caret
  1129.      12: You have gained ownership of the caret
  1130.      13-16: reserved by Acorn
  1131.      17,18: Wimp message arriving
  1132.      19: Wimp message previously sent has bounced
  1133. Related calls:
  1134.    *TMess; *TError;
  1135.  
  1136. Tornado_InitOLE                    (SWI &)
  1137. On entry: R0=flags
  1138.              bit 0: 
  1139.           R1=reloc ptr to file data          
  1140. On exit: R0=result code
  1141.          All other registers preserved
  1142. Interrupts: IRQ's enabled
  1143. Processor mode: SVC
  1144. Re-entrancy: None
  1145. Use:
  1146. This call initiates an OLE event, whereby a file or subfile loaded into the
  1147. task calling this SWI passes that file to another task (doesn't have to be a
  1148. Tornado task) for editing.
  1149.    The procedure is thus: First, Tornado checks through the tasks currently
  1150. loaded in and sees what filetypes they can edit. If it finds one, it passes
  1151. code -3 out of Tornado_Poll to the task, with R1+0=3. Depending on options
  1152. set in the TManager, the OLE client's (the task getting the OLEd file) editor
  1153. window will either be displayed as normal, or directly over the file in the
  1154. server's window, and essentially becomes a pane of that window (although they
  1155. remain unconnected).
  1156.    If there are no Tornado tasks loaded, things get more complex. Any of the
  1157. following may be executed, in any order:
  1158.    * Tornado looks through the list of tasks it knows about (if enabled), and
  1159. if it finds one that can load this filetype directly it loads it in and then
  1160. starts the whole process again.
  1161.    * Tornado looks through the list of tasks it knows about (if enabled), and
  1162. if it finds one that can load this filetype directly or through a translator
  1163. (after obviously checking for the presence of a suitable translator first!) 
  1164. it loads it in and then starts the whole process again.
  1165.    * Tornado defaults to simple OLE, and broadcasts a DataOpen with a file in
  1166. "tfs:$.<appname>.OLE.*". Any file saved back to this path will be reinserted
  1167. over the file originally OLEd.
  1168.    * Tornado defaults to simple OLE, checks for the option above, and if it
  1169. finds no tasks available it executes the appropriate Alias$@RunType_XXX for
  1170. it, by simply *Filer_Run-ing the file in "tfs:$.<appname>.OLE.*"
  1171.  
  1172. The reason the above processes are so ambiguous is simply that the user may
  1173. have chosen some options but not others, and all options depend on available
  1174. memory/resources so say if there isn't enough memory to do one option another
  1175. may be done instead (again, user configurable).
  1176. Related calls:
  1177.    *TDeclareTypes;
  1178.  
  1179.  
  1180.  
  1181. Tornado_FileOp                    (SWI &)
  1182. On entry: R0=flags
  1183.              
  1184.           R1=ptr to null terminated title, or a handle (see below)
  1185. On exit: R0=reason code
  1186.          All other registers preserved
  1187. Interrupts: IRQ's enabled
  1188. Processor mode: SVC
  1189. Re-entrancy: None
  1190. Use:
  1191. This call allows polling to continue during loads and saves.
  1192. Related calls:
  1193.    *TMess; *TError;
  1194.  
  1195. Tornado_StartSubtask                    (SWI &)
  1196. On entry: R0=flags
  1197.           R1=ptr to null terminated subtask name
  1198.           R2=ptr to parameters
  1199.           R3=signed memory change to the default amount given to subtask
  1200. On exit: R0=return code
  1201.            =0: subtask has been scheduled, please wait.
  1202.            =1: subtask couldn't be found
  1203.          All other registers preserved
  1204. Interrupts: IRQ's enabled
  1205. Processor mode: SVC
  1206. Re-entrancy: None
  1207. Use:
  1208. This call issues a request to begin a subtask. The request is scheduled, and
  1209. almost certainly will return code 0. All subtasks reside in TSubtasks:, and
  1210. this path may point to one of a number of directories.
  1211.    The memory change given is a signed integer, denoting the alteration to
  1212. the default amount of memory allocated to the subtask. The subtask, by
  1213. default, is issued with a slot of its executable size on its storage media
  1214. plus 32k.
  1215.    The ptr to the block containing the parameters has the following format:
  1216.    +00: ptr to list of reloc ptr's in the system heap giving data necessary
  1217.         needed by the subtask.
  1218.    +04 to +256: the parameters needed by the subtask
  1219. Related calls:
  1220.    *TMess; *TError;
  1221.  
  1222. Tornado_KillSubtask                    (SWI &)
  1223. On entry: R0=flags
  1224.           R1=subtask's wimp task handle
  1225.           R2=Tornado id no of subtask
  1226. On exit: R0=return code
  1227.            =0: subtask has been destroyed
  1228.            =1: subtask isn't currently running, or subtask not found
  1229.            =2: subtask couldn't be destroyed. If so, R1 comes into play:
  1230.          R1=ptr to standard error block
  1231.          All other registers preserved
  1232. Interrupts: IRQ's enabled
  1233. Processor mode: SVC
  1234. Re-entrancy: None
  1235. Use:
  1236. This call kills a subtask currently running. It is used internally by Tornado
  1237. when the parent task calls Tornado_Closedown, and by any task wishing to
  1238. cancel a process.
  1239. Related calls:
  1240.    *TMess; *TError;
  1241.  
  1242. Tornado_InitialiseSubtask            (SWI &)
  1243. On entry: R0=latest version of Tornado known by this task * 100
  1244.           R1=ptr to name of subtask
  1245.           R2=flags
  1246. On exit: R0=current version of Tornado * 100
  1247.          R1=task handle given by the Wimp
  1248.          R2=current version of the Wimp * 100
  1249.          R3=slot number this task has been given
  1250.          R4=reloc ptr to parameters passed by the parent of this subtask
  1251.          R5=wimp task handle of the parent of this subtask
  1252.          R6=slot number of the parent of this subtask
  1253.          R7=amount of memory given to this subtask
  1254.          All other registers preserved
  1255. Interrupts: IRQ's enabled
  1256. Processor mode: SVC
  1257. Re-entrancy: None
  1258. Use:
  1259. This call initialises a subtask. Preemption of the subtask's code is started,
  1260. and from now on the subtask can begin processing. Also, it can communicate
  1261. with its parent, and can grab memory etc.
  1262.    All processing must be done to and from the subtask heap, referenced by
  1263. putting -1 in Tornado heap calls. Tornado will handle the copying of data to
  1264. and from the parent task and the subtask.
  1265.    What happens when this call is made:
  1266.    * Tornado_Initialise is called. Two blocks of data are allocated on the
  1267. subtask's heap, and two blocks are allocated on the system heap.
  1268.    * Preemption is started, and the parent task informed this task
  1269. sucessfully started.
  1270.    Remember the contents of R4, as you will need it for later usage. The
  1271. block pointed to by R4 is guaranteed to be at least 256 bytes.
  1272.    The block of parameters on entry has the following format:
  1273.    +00: ptr to list of reloc blocks that have been passed to you
  1274.    +04 onwards: any other relevent data
  1275. Note it is your responsibility to remove the blocks given to you once you've
  1276. finished with them. This is usually not necessary as the data will be needed
  1277. during the duration of the processing, and the blocks will be freed when the
  1278. subtask terminates anyway.
  1279. Related calls:
  1280.    ;
  1281.  
  1282. Tornado_GetSTMessages                (SWI &)
  1283. On entry: None
  1284. On exit: R0=task handle of task sending this message (=0 if no messages)
  1285.          R1=slot number of task sending this message
  1286.          R2=reloc ptr to message, same as R4 from Tornado_InitialiseSubtask
  1287.          R3=number of messages left to be processed
  1288.          All other registers preserved
  1289. Interrupts: IRQ's enabled
  1290. Processor mode: SVC
  1291. Re-entrancy: None
  1292. Use:
  1293. This call checks if there are any messages waiting for the subtask. It also
  1294. replies how many messages are waiting, as the subtask may wish to deal with
  1295. all outstanding messages at once.
  1296.    The message block has the following format:
  1297.    +00: ptr to list of reloc blocks that have been passed to you
  1298.    +04 onwards: any other relevent data
  1299. Note it is your responsibility to remove the blocks once you've finished with
  1300. them.
  1301. Related calls:
  1302.    ;
  1303.  
  1304. Tornado_SendSTMessages                (SWI &)
  1305. On entry: R0=task handle of task to send this message to
  1306.           R1=slot number of task to send this message to
  1307.           R2=reloc ptr to message block, same as R4 from
  1308.              Tornado_InitialiseSubtask
  1309. On exit: All registers preserved
  1310. Interrupts: IRQ's enabled
  1311. Processor mode: SVC
  1312. Re-entrancy: None
  1313. Use:
  1314. This call sends a message to a task. The message block is of the following
  1315. format:
  1316.    +00: ptr to list of reloc blocks being passed to recipient
  1317.    +04: any other relevent data
  1318. Note this message can be used to pass directly small amounts of of data, and
  1319. it is preferable that portions of data are sent ie; don't send an entire file
  1320. as yet uncompleted. This is in an attempt to reduce bandwidth needed to
  1321. transmit the data.
  1322.    Note it's your responsibility to remove the blocks after this call
  1323. returns, if they are of no more use to you.
  1324. Related calls:
  1325.    ;
  1326.  
  1327. Tornado_RenderFile                (SWI &)
  1328. On entry: R0=flags
  1329.           bit 0: What kind of file is this?
  1330.           R1=ptr to heap, 0 if system heap
  1331.           R2=reloc ptr to data
  1332.           R3=filetype of data
  1333.           R4=block containing standard header of data
  1334. On exit: R0=return code
  1335.           =-1: please reschedule this call, by Tornado_ForceRedraw or
  1336.                whatever (Tornado is loading in a renderer)
  1337.            =0: R1 contains type of file
  1338.            =1: file rendered successfuly
  1339.            =2: error occurred during rendering. R1 then points to standard
  1340.                error block
  1341.            =3: file is being rendered (ie; movie or audio)
  1342.          R1=type of file if R0=0
  1343.           =-2: please reschedule this call
  1344.           =-1: unknown, as there was no renderer available to say
  1345.            =0: vduable sequence (Draw, Paint, Euclid, DTP etc)
  1346.            =1: audio (soundtracker, simple sample etc)
  1347.            =2: movie (Replay, MPEG etc)
  1348.          R2=various data
  1349.            If R1=1, then R2=correct replay rate to use (-1 if unknown)
  1350.            If R1=2, then R2=frames per second by default
  1351.          All other registers preserved
  1352. Interrupts: IRQ's enabled
  1353. Processor mode: SVC
  1354. Re-entrancy: None
  1355. Use:
  1356. This call renders a file, of any type. You can determine the type of file by
  1357. setting bit 0 on entry, and bear in mind you may be asked to reschedule while
  1358. Tornado loads in a suitable renderer. The block pointed to by R4 is of the
  1359. following type:
  1360.    For type 0, a vduable sequence:
  1361.      +00: absolute x position of bottom left corner
  1362.      +04: absolute y position of bottom left corner
  1363.      +08: absolute x position of top right corner
  1364.      +12: absolute y position of top right corner
  1365.      For bitmaps, no more standardised information
  1366.      For 2D vectors, no more standardised information
  1367.      For 3D vectors:
  1368.        +16: x sweep in radians shifted up by 16 bits
  1369.        +20: y sweep in radians shifted up by 16 bits
  1370.        +24: z sweep in radians shifted up by 16 bits
  1371.        +28: distance from object
  1372.        +32: no more standardised information
  1373.      For text (note only +00 and +12 are used here):
  1374.        +16: font handle to be used in plotting
  1375.        +20: how to treat control characters
  1376.           =0: standard (I'll fill in the rest here later)
  1377.        +24: tab spacing
  1378.        +28: blah blah (again, I'll fill this in later)
  1379.    For type 1, an audio sequence:
  1380.      +00: time index in cs to start playing from (-1 if stop rendering)
  1381.      +04: speed in Khz to play at (-1 if take default or stored)
  1382.    For type 2, movies:
  1383.      +00: absolute x position of bottom left corner
  1384.      +04: absolute y position of bottom left corner
  1385.      +08: absolute x position of top right corner
  1386.      +12: absolute y position of top right corner
  1387.      +16: time index in cs to start playing from (-1 if stop rendering)
  1388.      +20: flags
  1389.         bit 0: don't play sound if available
  1390.      +24: quality
  1391.         =0: highest possible
  1392.         =1: high (say less anti-aliasing and dithering)
  1393.         =2: medium (66% of high quality)
  1394.         =3: course (33% of high quality)
  1395.         =4: worst possible
  1396.      +28: frames per second to play back at (-1 if use default)
  1397.      +32: no more standardised information
  1398.  
  1399. Related calls:
  1400.    ;
  1401.  
  1402.  
  1403. ****************************************************************************
  1404. Star commands not yet definitively defined:
  1405.  
  1406.  
  1407. Star commands defined for sure:
  1408.     *TCheckSystem
  1409. Use:
  1410. This command checks for the presence of !System, and if it is not present a
  1411. suitable message is displayed. Note that the user may choose to continue
  1412. regardless, but otherwise the current Obey file in progress is terminated.
  1413.    It is to be used in !Run files of Tornado applications.
  1414.  
  1415.     *TCheckScrap
  1416. Use:
  1417. This command checks for the presence of !Scrap or a similar facility, and if
  1418. it is not present a suitable message is displayed. Note that the user may
  1419. choose to continue regardless, but otherwise the current Obey file in
  1420. progress is terminated.
  1421.    It is to be used in !Run files of Tornado applications, but only if the
  1422. presence of <Wimp$Scrap> and <Wimp$ScrapDir> is vital to the correct
  1423. functioning of the program. Ie; checking for <Wimp$Scrap> to be used in the
  1424. data transfer protocol is not vital, especially as Tornado will do its own
  1425. scrap file if absolutely necessary.
  1426.  
  1427.     *TCheckFonts [1|0]
  1428. Use:
  1429. This command firstly checks for the presense of the outline font manager, and
  1430. afterwards the presence of !Fonts, and if they are not present a suitable
  1431. message is displayed. Note that the user may choose to continue regardless,
  1432. but otherwise the current Obey file in progress is terminated.
  1433.    It is to be used in !Run files of Tornado applications, but only if the
  1434. presence of the font manager is of vital importance. Usually, this is not the
  1435. case. Note putting 1 as a parameter makes Tornado far more serious about the
  1436. message, and it denotes that your task /needs/ the _outline_ font manager to
  1437. work correctly. Unless you are an application which bends fonts or something,
  1438. you should never need to use this.
  1439.    Leaving out any parameters assumes the default, a value of 0.
  1440.  
  1441.     *THourglass <On|Off|Load|Save|Process|Kill>
  1442. Use:
  1443. This command starts up the Tornado hourglass, which may be set to display
  1444. current actions through its parameter. Note Tornado hooks itself into Obey,
  1445. so if the obey file is closed suddenly the hourglass is killed.
  1446.    Use SWI Tornado_Hourglass for the same call in code. It also allows
  1447. greater flexibility.
  1448.  
  1449.     *TIconsprites <base pathname>
  1450. Use:
  1451. This command adds the file specified by the base pathname (appendation="") to
  1452. the lo-res Tornado sprite pool, and adds the base + "22" to the hi-res
  1453. Tornado sprite pool. In future there may be a hires mono switch to load these
  1454. into the hires pool instead, but this will be transparent to the task.
  1455.    The current screen mode is then read, and the entire copy of the sprites
  1456. is copied out of the relevent sprite pool into the system sprite pool,
  1457. replacing any sprites already there. This also occurs on mode changes. Note
  1458. the user may override these default actions, so do not assume anything.
  1459.    SWI Tornado_SpriteOp provides much greater flexibility than this command,
  1460. and should be used in code. This command is for !Run and !Boot files.
  1461.  
  1462.     *TRMEnsure <module> <version> <mod lname> [<mod descript>]
  1463. Use:
  1464. This command checks for the presence of the module specified and for the
  1465. version. If it cannot find the module, it checks !System (if defined - it
  1466. will do a TCheckSystem first) for the module entitled <mod lname>, and if
  1467. present loads it. If it isn't there either, it shows a message to the user
  1468. indicating that the module isn't present on the system at all. Note the user
  1469. may still ask for program execution to continue, although he/she will be
  1470. strongly recommended not to do this.
  1471.    If a copy of the module is loaded in, the module version is checked
  1472. against that in the command, and if it is too old then again an attempt is
  1473. made to load in a newer copy from !System. After this, if it is still too old
  1474. or there isn't a copy in !System, a suitable message is shown to the user
  1475. indicating that the module version available is too old. Note the user may
  1476. still ask for program execution to continue.
  1477.  
  1478.     *TRun <name> [<params>]
  1479. Use:
  1480. This command firstly sets <[name]$Dir> to <Obey$Dir>, and then normally looks
  1481. for the !Config file within <[name]$Dir>, but if the application is on a
  1482. read-only media (like CD-ROM) then Tornado may run another config file. This
  1483. config file sets where to find !RunImage, and how to run it, along with other
  1484. preferences set.
  1485.    Note that <name> is used by Tornado to refer to your application
  1486. internally, including setting your quit menu's title to it. In other words,
  1487. make it short, descriptive, and ask the Tornado group if any other
  1488. application has used that handle for itself. If it has, become a Tornado
  1489. programmer, and you will be allocated a unique hexadecimal number to be used
  1490. for every program you write.
  1491.  
  1492. This command reads the size of the pathnamed file, and allocates a suitable
  1493. slot for it (default=code size+32k). This slot may be increased by specifying
  1494. an increase in the first parameter. The file will be loaded multitaskingly
  1495. into its slot, and made into the CAO.
  1496.    Note negative increases are permitted, and actively encouraged. Basic
  1497. programs proabably can do with 16k less, whereas C programs may need an extra
  1498. 8k.
  1499.    A related command to this is Tornado_File, the replacement for OS_File.
  1500.  
  1501.     *TMess <mess>
  1502. Use:
  1503. This command displays a message in a Tornado window. It is given the
  1504. automatic default button of Ok, and is used to inform the user of things. The
  1505. command doesn't return until the user selects Ok.
  1506.    This command actually uses SWI Tornado_Query.
  1507.  
  1508.     *TError <mess>
  1509. Use:
  1510. This command displays an error in a Tornado window. It is given the automatic
  1511. default button of Cancel, and is used to inform the user of an error. The
  1512. command doesn't return, as the CAO is terminated when the user selects
  1513. Cancel.
  1514.    This command actually uses SWI Tornado_Query.
  1515.  
  1516.     *TStdError <mess no>
  1517. Use:
  1518. This command displays a standard error message in a Tornado window, as given
  1519. in Tornado_GiverError. It is given the automatic default button of Cancel,
  1520. and is used to inform the user of an error. The command doesn't return, as
  1521. the CAO is terminated when the user selects Cancel.
  1522.    This command actually uses SWI Tornado_Error.
  1523.  
  1524.     *TDeclareTypes <list of filetypes seperated by spaces>
  1525. Use:
  1526. This command is used from the !Boot file to declare to Tornado that this task
  1527. exists and that it can load directly the filetypes specified. Note that the
  1528. filetypes must be in hexadecimal and in 32bit quantities. Note also that
  1529. <Obey$Dir> should still point into the task's directory, as this path will be
  1530. stored.
  1531.  
  1532. ****************************************************************************
  1533. ****************************************************************************
  1534. Other notes:
  1535.  
  1536. This is the general format of a Tornado task's !Boot file:
  1537. | Boot file for View, the Tornado suite demo app
  1538. | Last updated: 09-06-1995
  1539. |
  1540. RMEnsure Tornado 0.50 Obey
  1541. TDeclareTypes 00000FFF 00000FFD
  1542. TIconsprites <Obey$Dir>.!Sprites
  1543.  
  1544. Simple and sweet eh? Note the direct implication of this is that if Tornado
  1545. fails to initialise, or the Tornado folder hasn't been seen, the icon for the
  1546. application in the filer window remains blank.
  1547.  
  1548.  
  1549. This is the general format of a Tornado task's !Run file:
  1550. | Run file for View, the Tornado demo app
  1551. | Last updated: 09-06-1995
  1552. |
  1553. | Make sure all the necessary system extensions are present
  1554. RMEnsure UtilityModule 2.00 Error 0 This program cannot be used with Arthur. 
  1555. You need RISC-OS 2, or better
  1556. | Checks have already been made for WindowManager,Hourglass,SystemDevices,Fil
  1557. eSwitch & FileCore. Check for others.
  1558. RMEnsure Filer 1.00 Error 0 Please reinstall the Filer module before running 
  1559. this again
  1560. RMEnsure SpriteExtend 0.20 Error 0 Please reinstall the SpriteExtend module b
  1561. efore running this again
  1562. RMEnsure Draw 1.01 Error 0 Please reinstall the Draw module before running th
  1563. is again
  1564. |
  1565. | Check for Tornado resources
  1566. RMEnsure Tornado 0.50 Error 0 You will need to install the Tornado resources 
  1567. on your system before this program will run. You will find a copy of the Torn
  1568. ado resources on any major Acorn archive.
  1569. |
  1570. | Check for !System.
  1571. TCheckSystem
  1572. | Check for !Fonts, and outline font manager
  1573. TCheckFonts
  1574. |
  1575. | Wake up the hourglass, and load in our sprites
  1576. THourglass Load
  1577. Filer_Run <Obey$Dir>.!Boot
  1578. TIconsprites <Obey$Dir>.Sprites
  1579. Set View$Dir <Obey$Dir>
  1580. THourglass Process
  1581. |
  1582. | Load in and ensure all our needed modules
  1583. TRMEnsure ColourTrans 0.52 Colours colour translator module
  1584. TRMEnsure FPEmulator 2.80 FPEmulator floating-point maths chip emulator
  1585. TRMEnsureS FPEmulator 3.00 FPEmulator floating-point maths chip emulator
  1586. |
  1587. | Load in main RunImage, located according to !Config, while multitasking
  1588. TRun View %*0
  1589.  
  1590. See the star command summary above for explanation. Otherwise, note how
  1591. checks are made for system extensions in case they have been removed. You
  1592. _cannot_ assume /anything/ - everything must be checked for. If you want your
  1593. program to work on RO2, it shouldn't obviously be checking for modules that
  1594. don't exist on RO2. However, you can always assume that if Tornado is active,
  1595. the ColourTrans, WimpExt and DragASprite modules will also be present, but
  1596. you will still need to check for the SharedCLibrary. More than likely it will
  1597. be present too, as it is conceived quite a bit of Tornado will be eventually
  1598. written in C.
  1599.    Note the producing of the error explaining why the app won't run and where
  1600. to get the Tornado resources from. This is to aid productivity - Aim 1 - so
  1601. the user doesn't have to ring his 'techie' collegues to get him to work it
  1602. out. He can do it himself/herself, and there will be a short summary of docs
  1603. supplied to say where you get Tornado from and how with every Tornado app.
  1604.    Note the use of Filer_Run - this is added to RO2 by Tornado, as is
  1605. Filer_Boot and a few other misc RO3 commands. This is done by Brian
  1606. Brunswick's Bits module, although I don't have copyright permission to use it
  1607. yet.
  1608.  
  1609. ****************************************************************************
  1610. ****************************************************************************
  1611. Protocols:
  1612.  
  1613. Subtask protocol:
  1614.   * Task calls Tornado_StartSubtask
  1615.   * Tornado broadcasts Message_StartSubtask. If this message is acknowledged,
  1616. then a server is present and from now on it does all the communicating with
  1617. the parent task. Tornado's involvement is over.
  1618.   * If the message isn't acknowledged, then Tornado does the default action,
  1619. which is thus:
  1620.   * It installs handlers, and runs the subtask as the new CAO. The subtask in
  1621. turn should call Tornado_InitialiseSubtask within five seconds, or the CAO is
  1622. killed and it is returned to the app that the subtask run wasn't a subtask.
  1623.   * When the subtask calls Tornado_InitialiseSubtask, Tornado also calls
  1624. Tornado_Initialise and Tornado_StartPreemption, discarding most of the
  1625. results it receives.
  1626.   * From hence, the subtask can communicate with its parent via
  1627. Tornado_GetSTMessages and Tornado_SendSTMessages. It can also communicate
  1628. with any sibling subtasks by this method, taking care to address the message
  1629. appropriately. The subtask must send at least one message to its parent,
  1630. giving all of the processed data.
  1631.   * Upon finishing the processing, the subtask calls
  1632. Tornado_ClosedownSubtask. This also calls Tornado_Closedown, and exits out of
  1633. the CAO.
  1634.  
  1635. Notes on subtasks:
  1636.    You may note subtasks must pass the slot number AND the task handle of the
  1637. recipient of its messages. This is because when a subtask is running on a
  1638. remote processor, the task handle is the local server and the id slot number
  1639. is the process running on the remote server. Complicated? Wait till you see
  1640. the inter-server protocols ... :-)
  1641.    Special subtasks:
  1642.    Inline file translators. These set of subtasks perform the automatic
  1643. conversion of filetypes between each other, say between GIF and Sprite.
  1644.    When the user tries to load a GIF file (say) into a Tornado app than can
  1645. only read Sprites, the GIF file is loaded under multitasking into tfs:, and
  1646. the appropriate convertor called (known by its name: a translator capable of
  1647. reading GIFs and converting them is called by the 32bit hexadecimal of the
  1648. GIF filetype (which I can't remember what it is right now).). When the
  1649. convertor finishes, the file is loaded into the task by Tornado (if the task
  1650. has this enabled).
  1651.    The parameter format is this:
  1652.      +00: ptr to list of reloc blocks that have been passed to you
  1653.         In this list:
  1654.         +00: ptr to reloc blk containing the file data
  1655.      +04: filetype of input
  1656.      +08: desired filetype of output. If the convertor can't translate into
  1657.      this filetype, then the convertor should call another convertor that
  1658.      might be able to (ie; call the convertor called the filetype this
  1659.      convertor is spitting out)
  1660.      +12: size of the block of data you wish to have returned when processing
  1661.           on that block is complete. In other words, when the convertor has
  1662.           output more than !+12 of converted data, return the block of
  1663.           completed data to the parent. This allows the parent to (say)
  1664.           display bits of translated GIF as it is processed. Note the block
  1665.           of converted data returned may be bigger than !+12, and it is
  1666.           possible that the converter doesn't support this, in which case it
  1667.           will return the fully completed data at the end. Put -1 here if you
  1668.           wish all the converted data to be returned at the end, and no
  1669.           prefinishing data to be returned. It is emphasised that this method
  1670.           should be supported as a convertor calling another convertor may be
  1671.           processing its file alongside the constant return of already
  1672.           processed data.
  1673.  
  1674.    Restrictions on code in subtasks:
  1675.    * Subtasks may NOT write to the vdu in any way, including vdu 7. However,
  1676. they may use Tornado_Query to display a message to the user.
  1677.    * Subtasks may NOT get input from the user in any way more complex than
  1678. Tornado_Query, except through their parent.
  1679.    * Subtasks may NOT run in any mode other than baseline USR.
  1680.    * Subtasks may NOT install handlers.
  1681.    * Subtasks may NOT call any code that runs for extended lengths of time
  1682. (ie; >1cs) in a mode other than USR. In other words, don't call a SWI if it's
  1683. going to take a while. Do it some other way.
  1684.    * Subtasks may talk to subtasks not directly related to them, but be
  1685. careful with what you're doing, and make sure the subtask can function on its
  1686. own.
  1687.    * Subtasks may not access memory outside their own domain, unless it's
  1688. been allocated to them by Tornado_Getblk
  1689.    * Subtasks may not access any heap other than their own heap, referenced
  1690. using -1 in heap pointers. Tornado will take care of copying blocks between
  1691. the subtask's heap and the system heap of the parent task.
  1692.  
  1693. ****************************************************************************
  1694.  
  1695. Graphics renderers protocol:
  1696.   * Task calls Tornado_RenderFile.
  1697.   * Tornado issues the service call Service_RenderFileRq. If this is
  1698. acknowledged, then the file has been rendered, and Tornado's involvement is
  1699. over. If this isn't acknowledged, then Tornado proceeds thus:
  1700.     * Tornado_RenderFile returns with code indicating 'Please reschedule this
  1701. call' (ie; exit from the redraw/update handler immediately and issue a
  1702. Tornado_ForceRedraw). Tornado then begins a process which loads in
  1703. TRenderers:XXX (which is a module), where XXX is the 32bit hexadecimal of the
  1704. filetype the renderer is capable of rendering.
  1705.  
  1706. Notes on graphic renderers:
  1707.   * Despite the name, graphic renderers can render anything, whether they be
  1708. bitmap, vector, movie or sound.
  1709.   * Graphic renderers may load in libraries of code to assist them. Do this
  1710. in the Initialise entry, even though polling stops. You do not need to remove
  1711. them in finalise, as Tornado takes care of this for you.
  1712.   * Render the file as quickly as you possibly can. You will not be preempted
  1713. during rendering, and polling is effectively stopped. You may use the
  1714. hourglass if absolutely necessary, but honestly you shouldn't be taking that
  1715. long. To this end, read the current graphics rectangle and use it to clip out
  1716. any unneccessary processing.
  1717.   * Renderers are common resources. Use the standard message blocks, and
  1718. where information isn't given, use appropriate defaults. If necessary read
  1719. current system settings to aid you. Do NOT structure your renderer for one
  1720. application, as any application is entitled to use your renderer, as you are
  1721. entitled to use anyone else's renderer.
  1722.       NOTE: This implies that any renderer you write is freeware. YOU MAY NOT
  1723. CLAIM ANY MONEY FOR WRITING IT, OTHER THAN VOLUNTARY AND UNFORCED PAYMENTS OF
  1724. GRATITUDE. YOUR RENDERER MUST FUNCTION FULLY, IE NOT PUT 'DEMO' ALL OVER IT
  1725. OR WORK TO LESS OF A STANDARD THAN A COMMERCIALLY SUPPLIED VERSION.
  1726.  
  1727. ****************************************************************************
  1728.  
  1729. General OLE and hotlinking protocol:
  1730.  
  1731. OLE protocol:
  1732.   * User starts OLE by standard action (yet to be decided). Task calls
  1733. Tornado_InitOLE.
  1734.   * Tornado checks Tornado preferences to see if there is any preferred task
  1735. to send this filetype to, and if not starts from the start of the list of
  1736. currently loaded Tornado apps, checking to see if any of them can load this
  1737. filetype directly. If this can't, Tornado sees if any of the file converters
  1738. available can translate the file before OLE. If none can, the OLE is faulted.
  1739. If no currently loaded in app can be found to load in the file, then suitable
  1740. candidates are looked for on disc (known because of the TDeclareTypes in the
  1741. !Boot file), after which any non-Tornado apps loaded in are looked at, after
  1742. which a suitable Alias$@RunType_XXX is *Filer_Run-ed.
  1743.   * Either way, one way or another, a suitable Tornado application is found.
  1744. If it is non-Tornado, see later. Depending on user prefs, hotlinking may also
  1745. be started. A message is returned through Tornado_Poll indicating where to
  1746. open the editor window, and with a copy of the file. The file is edited, with
  1747. the altered copy being sent back to the caller of Tornado_InitOLE (note that
  1748. this is recursive, ie; if the OLEd file is OLEd, then it echos back through
  1749. both copies, and any other copies linked to these), not that you'll see it if
  1750. the editor window is a pane of the caller's window. File is edited, editor
  1751. window closed and new file remains in the window.
  1752.   * If Tornado OLE is not possible, the following is done: a DataOpen is
  1753. broadcast, pointing to a copy of the file in tfs:. An editor changes this
  1754. file, and upon saving it back to tfs:, Tornado notices and hotlinks the copy
  1755. back into the caller.
  1756.  
  1757. Hotlinking:
  1758.   * The only essential difference here is that Tornado does this for the
  1759. task. The user saves a file out of the task, having selected the 'Hotlink'
  1760. option. If the user dragged it to disc, then after every edit the file is
  1761. saved to disc. If the user dragged it to another app, then the two files are
  1762. hotlinked: any alteration to one affects the other. It can be considered two
  1763. views of the same document, although both documents are entirely seperate.
  1764.  
  1765. ****************************************************************************
  1766. ****************************************************************************
  1767.  
  1768. Ok, that's about it. Any bug reports, inconsistencies, etc. to my address by
  1769. email.
  1770.  
  1771. Cheers,
  1772. Niall
  1773.  
  1774.  
  1775. Examples:
  1776.  
  1777. Paint and Ovation are two tornado apps. Ovation has a graphics frame. User
  1778. designs a sprite file in Paint, and saves it out as a GIF into Ovation:
  1779. * Tornado receives Dragfinishevent, determines the recipiant, and notices
  1780. that it can only load in sprites.
  1781. * The conversion is quashed (HOW?), and the file is copied into another
  1782. block. Ovation's Tornado_Poll exits out with -3,2. Ovation calls
  1783. Tornado_SubfileOp.
  1784. * Now the user decides they want to edit the file in the frame. Tornado
  1785. checks the list of filetypes that can be loaded by apps currently loaded in,
  1786. and passes -3,3 out of Paint's Tornado_Poll. Paint opens its editor window
  1787. exactly over the frame
  1788.  
  1789.  
  1790. Notes:
  1791. ------
  1792. Add wimp message to indicate new fonts are available.
  1793.  
  1794. Add wimp message to indicate new renderers are available.
  1795.  
  1796. Add wimp message to indicate new filetypes and their owners are available.
  1797.  
  1798. Do seperate multitasker for Tornado apps, allowing memory outside their
  1799. domain to be protected from unauthorised access.
  1800.  
  1801. Hotkey to bring an application and its windows to the foreground, a la
  1802. Windows with Alt-Tab.
  1803.  
  1804. Large virtual desktop, with areas selectable by subject.
  1805.  
  1806. Filefinder.
  1807.  
  1808. Support for undos and undo code
  1809.  
  1810. Allow the RAM transfer of text files into the filename of a file.
  1811.  
  1812.