home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / mag_discs / 14 / prmvol5 / errata310
Text File  |  1994-12-09  |  28KB  |  778 lines
  1. 1. Licence
  2. ==========
  3. This licence permits you to copy the text below. You must reproduce on any
  4. copy of the text this licence and Acorn Computers Limited's copyright notice
  5. which appears below.
  6.  
  7. 2. Restrictions
  8. ===============
  9. You may distribute copies of the text below but you must NOT charge any fee
  10. therefor. You may not modify the text.
  11.  
  12. 3. Limited Warranty and Disclaimer
  13. ==================================
  14. The text is supplied "as is" and Acorn expressly disclaims any warranty,
  15. express or implied, as to the merchantability of the text or it's fitness
  16. for any particular purpose.
  17.  
  18. In no circumstances will Acorn be liable for any direct, indirect,
  19. consequential or incidental damage (including loss of profits, business
  20. interruption and loss of data) arising out of the use or the inability to
  21. use the text.
  22.  
  23. Copyright notice
  24. ================
  25. Copyright (c) 1994 Acorn Computers Limited. All rights reserved.
  26. Published by Acorn Computers Technical Publications Department.
  27.  
  28.  
  29.  
  30.  
  31. ============================================================================
  32.               Appendix: Errata and omissions for RISC OS 3 PRM
  33. ============================================================================
  34.  
  35. This chapter contains a number of errata and omissions for the RISC OS 3
  36. Programmer's Reference Manual, together with clarification of some text.
  37.  
  38. Unless otherwise specified, the comments below for any given operation or
  39. call refer to all versions of RISC OS that support it.
  40.  
  41. Events (page 1-145)
  42. -------------------
  43. Events may not be received in the order in which they are generated.
  44.  
  45. Code offset (page 1-214)
  46. ------------------------
  47. R1 is undefined on entry in the case of a configuration keyword.
  48.  
  49. SWI handler code (page 1-217)
  50. -----------------------------
  51. R9 is corrupted on entry; the SWI handler code is not passed the value of R9
  52. specified by the caller.
  53.  
  54. OS_ReadVarVal (page 1-309)
  55. --------------------------
  56. If you are checking for the existence/length of a variable (ie bit 31 of R2
  57. is set on entry), R0 is corrupted on exit.
  58.  
  59. OS_CheckModeValid (page 1-715)
  60. ------------------------------
  61. For all versions of RISC OS, this call returns -2 to indicate there is
  62. 'insufficient memory' if the currently allocated amount of screen memory is
  63. too little for the specified mode. It does not take into account whether the
  64. area could grow.
  65.  
  66. File operations (page 1-747)
  67. ----------------------------
  68. You may get unpredictable results when using *ScreenLoad to load a sprite
  69. that was not created by *ScreenSave. The same applies to the equivalent
  70. SWIs.
  71.  
  72. Pixel translation table (page 1-752)
  73. ------------------------------------
  74. A number of calls that use a pixel translation table specify it as optional.
  75. You can only omit it if the sprite you are plotting has the same number of
  76. bits per pixel as the current screen mode. We recommend you always supply a
  77. table, and leave it to RISC OS to ignore it if it is unnecessary.
  78.  
  79. Creating sprites (page 1-747)
  80. -----------------------------
  81. If you try to create a sprite with a palette, the palette is incorrect if it
  82. is for a different number of bits per pixel to that used by the current
  83. mode. The best workround is to create the sprite without a palette, and then
  84. to add the palette.
  85.  
  86. OS_SpriteOp (page 1-761)
  87. ------------------------
  88. OS_SpriteOp is not re-entrant.
  89.  
  90. OS_SpriteOp 60 (page 1-811)
  91. ---------------------------
  92. The purpose of the save area is to preserve your own context should anyone
  93. switch output away from you.
  94.  
  95. IIC_Control (page 1-944)
  96. ------------------------
  97. R0 is corrupted on exit.
  98.  
  99. FileSwitch (page 2-9)
  100. ---------------------
  101. All calls that open a file for writing when it cannot be written to (eg
  102. write-protected media, no write access, locked filing system) do not
  103. generate an error. The error is not generated until an attempt is actually
  104. made to write to the file.
  105.  
  106. Filing system numbers (page 2-19)
  107. ---------------------------------
  108. The entry for DOSFS refers to a stand alone filing system called DOSFS,
  109. released with certain versions of the PC Emulator. All image filing systems
  110. (including the DOSFS supplied in RISC OS 3 onwards) use a filing system
  111. number of 0 to distinguish them from ordinary filing systems.
  112.  
  113. Disc formats (page 2-197)
  114. -------------------------
  115. The 'perfect' disc formats referred to in this section may not always be
  116. attainable. For example, the 710/711 controllers cannot achieve a gap1 of
  117. more than 255 bytes, and hence use a good alternative. See also
  118. FileCore_DiscFormat (page 2-234) and ADFS_VetFormat (page 2-287) for a
  119. description of the process used to negotiate an attainable format.
  120.  
  121. FileCore_MiscOp (page 2-238)
  122. ----------------------------
  123. The cross references to the various reason codes should read:
  124.  
  125.         Value           Meaning                 Page
  126.         -----           -------                 ----
  127.         0               Mount                   2-240
  128.         1               Poll changed            2-242
  129.         2               Lock drive              2-243
  130.         3               Unlock drive            2-244
  131.         4               Poll period             2-245
  132.         5               Eject disc              2-246
  133.  
  134. DOSFS (page 2-317)
  135. ------------------
  136. The mapping of DOS attributes to RISC OS attributes is not described in this
  137. chapter. It is as follows:
  138.  
  139. If a DOS file is read only, its RISC OS attributes are LWR; otherwise they
  140. are RW. If a RISC OS file is locked, it is a read only file when transferred
  141. to DOS; otherwise it is a read/write file.
  142.  
  143. Other attributes are preserved where possible, using a mechanism that is
  144. subject to change and so not documented.
  145.  
  146. OS_SerialOp (page 2-459)
  147. ------------------------
  148. Two reason codes were added to OS_SerialOp in RISC OS 3, but were not
  149. documented in the RISC OS 3 Programmers Reference Manual. These are
  150. described later in this chapter:
  151.  
  152. * OS_SerialOp 7 (page 5-300) is for internal use only.
  153.  
  154. * OS_SerialOp 8 (page 5-301) reads/writes the serial input buffer threshold
  155.   value. It is provided as a replacement for OS_Byte 203 (page 2-453), and
  156.   you should use it in preference.
  157.  
  158. FSEntry_Open and ImageEntry_Open (page 2-531)
  159. ---------------------------------------------
  160. The documentation states that - for FSEntry_Open - reason code 1 is only
  161. used by RISC OS 2. It can in fact be called by other versions of RISC OS
  162. under certain very specific conditions.
  163.  
  164. Returning errors (page 2-593)
  165. -----------------------------
  166. The cross reference at the end of this section should be to the section
  167. entitled Returning errors on page 2-590.
  168.  
  169. MiscOp entry (page 2-595)
  170. -------------------------
  171. When this entry point is called, R12 is a pointer to your FileCore module's
  172. private word. All other registers are as documented (ie the same values as
  173. were passed to FileCore_MiscOp). In general, all FileCore_MiscOp calls are
  174. passed straight through to your FileCore module, which should implement
  175. their full functionality; however, FileCore counts lock/unlock calls itself,
  176. and only calls your module when it should actually lock or unlock the drive.
  177.  
  178. Layout of windows (page 3-10)
  179. -----------------------------
  180. The last line of page 3-13 should read:
  181.  
  182. work_area_pixel_at_origin_x = scroll_offset_x - visible_area_min_x
  183. work_area_pixel_at_origin_y = scroll_offset_y - visible_area_max_y
  184.  
  185. Similarly, the 'entire formula' given near the top of the next page should
  186. read:
  187.  
  188. work area x = screen_x + (scroll_offset_x - visible_area_min_x)
  189. work area y = screen_y + (scroll_offset_y - visible_area_max_y)
  190.  
  191. Wimp_Initialise (page 3-87)
  192. ---------------------------
  193. The description of R3 on entry is wrong, and should read:
  194.  
  195. R3 = pointer to a list of message numbers terminated by a 0 word (not if R0
  196.      is less than 300). If Wimp version number is 310 then a null pointer
  197.      indicates that no messages are important to this task, whereas a null
  198.      list indicates that all messages are important; this is the reverse of
  199.      what you might expect.
  200.  
  201. Wimp_CreateIcon (page 3-96)
  202. ---------------------------
  203. If you use 2 icons with the 'S' validation string they must both be the same
  204. size.
  205.  
  206. Wimp_Poll (page 3-115)
  207. ----------------------
  208. From RISC OS 3 onwards, on exit, if R0 is 18 (User_Message_Recorded) then R2
  209. is set to the task handle of the sender.
  210.  
  211. Wimp_DecodeMenu (page 3-161)
  212. ----------------------------
  213. The returned string is terminated.
  214.  
  215. Wimp_ReadPalette (page 3-192)
  216. -----------------------------
  217. From RISC OS 3 onwards, if R2 is 'TRUE' on entry (ie &45555254), then the
  218. returned palette entries are 24 bit rather than 12 bit: ie &bbggrrnn rather
  219. than &b0r0g0nn. This saves having to copy the top nibbles into the bottom
  220. nibbles before making ColourTrans calls.
  221.  
  222. Message_RAMFetch (page 3-256)
  223. -----------------------------
  224. The versions of !Edit supplied before RISC OS 3.5 only respond to this
  225. message if it is sent as a User_Message_Recorded (ie if acknowledgement is
  226. requested).
  227.  
  228. TaskWindow_Input (page 3-266)
  229. -----------------------------
  230. Location R1+24 of the message block holds the input data itself, not a
  231. pointer to it. The data needs no terminator, because its length is held in
  232. R1+20.
  233.  
  234. TaskWindow_Ego (page 3-266)
  235. TaskWindow_Morio (page 3-266)
  236. -----------------------------
  237. The versions of !Edit supplied before RISC OS 3.5 only respond to these
  238. messages if they are sent as a User_Message (ie if no acknowledgement is
  239. requested).
  240.  
  241. TaskWindow_NewTask (page 3-267)
  242. -------------------------------
  243. The versions of !Edit supplied before RISC OS 3.5 only respond to this
  244. message if it is sent as a User_Message (ie if no acknowledgement is
  245. requested).
  246.  
  247. The command passed in this message is only the head of the command that must
  248. be issued via Wimp_StartTask. The full command is:
  249.  
  250. command xxxxxxxx yyyyyyyy                       nb there is a trailing space!
  251.  
  252. where xxxxxxxx and yyyyyyyy are the task and txt parameters passed when
  253. creating the task window (see *TaskWindow on page 3-326).
  254.  
  255. Filter_RegisterPostFilter (page 3-308)
  256. --------------------------------------
  257. Under RISC OS 3, if a filter routine sets R0 to -1 to claim an event and
  258. prevent it being passed to its task, then that event is not passed on to any
  259. further post filters. From RISC OS 3.5 onwards, claiming an event does not
  260. prevent other post filters from being called, but does still prevent the
  261. event being passed to the task.
  262.  
  263. TaskWindow (page 3-321)
  264. -----------------------
  265. Changing screen mode from task windows can have unpredictable results.
  266.  
  267. *TaskWindow (page 3-326)
  268. ------------------------
  269. See TaskWindow_NewTask above for correct information on how to respond to
  270. this message.
  271.  
  272. ColourTrans_SelectTable (page 3-346)
  273. ColourTrans_GenerateTable (page 3-397)
  274. --------------------------------------
  275. If R0 is 256 on entry, it is assumed not to point to a sprite area, but R1
  276. is still assumed to point to a sprite. This special value is useful if you
  277. need to use sprites that are not held in a sprite area. For example, Draw
  278. uses it for sprites that are held in a Draw file without a preceding sprite
  279. area control block.
  280.  
  281. Thus R0 is only assumed to be a pointer if it is greater than 256.
  282.  
  283. PDriver_SelectIllustration (page 3-634)
  284. ---------------------------------------
  285. We now recommend that the user should explicitly choose when a print job is
  286. to be saved to file for use as an illustration in another document. Only if
  287. the user has made that choice should you call this SWI; you should call
  288. PDriver_SelectJob for all other printing.
  289.  
  290. Printer definition files (page 3-697)
  291. -------------------------------------
  292. To aid recovery from aborted jobs, we recommend that form feed strings
  293. always contain a form feed, page end strings a full printer reset, and end
  294. of text job strings both a form feed and full printer reset.
  295.  
  296. General points, and Epson and IBM compatible printers (page 3-699)
  297. ------------------------------------------------------------------
  298. The printer type is used to differentiate between printer definitions. If
  299. you try to overload a printer definition with one having the same printer
  300. type, the old data is retained. This avoids any delays that might occur if
  301. the user tries to load the same file twice.
  302.  
  303. It follows that if you make minor alterations to a definition and wish to
  304. load it in place of or beside the original, you must change the printer
  305. type.
  306.  
  307. Loading and setting the current territory (page 3-787)
  308. ------------------------------------------------------
  309. The description in this section is wrong, and should read:
  310.  
  311. Each computer running RISC OS has a configured value for the current
  312. territory, set using *Configure Territory (see page 3-846), and stored in
  313. its CMOS RAM. On a reset or a power-on, RISC OS will try to load this
  314. territory as follows:
  315.  
  316. 1 It will load any territory modules in ROM. (Typically there is only one,
  317.   for the territory into which the computer has been sold.) If one of these
  318.   is the configured territory, no further action is taken.
  319.  
  320. 2 Otherwise, it will look on the configured device (ie the configured
  321.   filesystem and drive) for the module &.!Territory.Territory, and load it.
  322.  
  323. 3 If successful, it will then search for the directory -!Territory.Messages,
  324.   and load any modules it contains. The directory should exist, even if it
  325.   contains no modules.
  326.  
  327. At the end of this process:
  328.  
  329. * If the configured territory is in ROM, only those territory modules in ROM
  330.   will be loaded
  331.  
  332. * If the configured territory is not in ROM, both those territory modules in
  333.   ROM and another territory module (hopefully the configured one) will be
  334.   loaded.
  335.  
  336. RISC OS then selects as the current territory either the configured
  337. territory, or - if it is not present - a default territory from ROM.
  338.  
  339. Sound_Speaker (page 4-23)
  340. *Speaker (page 4-62)
  341. -------------------------
  342. These commands may not work on all machines, particularly those that use the
  343. headphone socket to mute the loudspeaker.
  344.  
  345. *Obey (page 4-350)
  346. ------------------
  347. Recursive calls of *Obey are only possible to a limited depth (currently 20,
  348. although you should not rely upon this).
  349.  
  350. Font files (page 4-470)
  351. -----------------------
  352. There are some errors in the documentation of font file formats, as follows:
  353.  
  354. * The section entitled Scaffold data on page 4-478 should start:
  355.  
  356.   Size            Description
  357.   ----            -----------
  358.   1 or 2          character code of 'base' scaffold entry (0 => none)
  359.  
  360. * In the section entitled Character data on page 4-480, the lines:
  361.  
  362.                   If character flags bit 3 is set:
  363.                           bit 4 set => composite character
  364.                           bit 5 set => with an accent as well
  365.  
  366.   would be clearer were they to read:
  367.  
  368.                   If character flags bit 3 is set:
  369.                           bit 4 set => composite base character follows
  370.                           bit 5 set => composite accent character follows
  371.  
  372.   On the next page, the line:
  373.  
  374.   if character flags bits 3 or 4 are clear:
  375.  
  376.   should read:
  377.  
  378.   if character flags bit 3 is clear, or bit 3 is set and bits 4 and 5 are clear:
  379.  
  380.   and the final line of the section:
  381.  
  382.   Word-aligned at the end of the character data.
  383.  
  384.   should read:
  385.  
  386.   Word-aligned at the end of the chunk.
  387.  
  388.  
  389.  
  390. =================================
  391. Printer server protocol interface
  392. =================================
  393.  
  394. The printer server protocol interface was omitted from the RISC OS 3
  395. Programmer's Reference Manual. It is as follows.
  396.  
  397.  
  398. NetPrint status protocol
  399. ========================
  400.  
  401. Status enquiry packet
  402. ---------------------
  403. To request the current state of a printer server the client sends an 8 byte
  404. status enquiry packet to port &9F:
  405.  
  406.         Byte    Meaning
  407.         ----    -------
  408.         1 - 6   printer name, padded with spaces
  409.         7       reason code (1 => status request, 6 => name request)
  410.         8       reserved (must be zero)
  411.  
  412. Status request
  413. --------------
  414. If the reason code is 1 (status request) the printer server should check the
  415. printer name. The check should be case insensitive, but with accents
  416. significant, preferably using Territory_Collate (see page 3-834):
  417.  
  418. * If the name matches the name of a printer connected to the server (eg
  419.   'PScrpt'), the server should send its status.
  420.  
  421. * If the name matches the string 'PRINT' or 'SPOOL', the server should send
  422.   the status of the user's default printer. (With Acorn's !Spooler software,
  423.   this is the most recently used printer, or the first listed printer if
  424.   none has yet been used).
  425.  
  426. * If the name matches neither of the above cases, the server should not
  427.   reply.
  428.  
  429. The status reply, if any, must be sent to port &9E:
  430.  
  431.         Byte    Meaning
  432.         ----    -------
  433.         1       status: 0 => Ready, 1 => Busy, 2 => Jammed, 6 => Offline;
  434.                         all other values reserved
  435.         2       station number for Busy status, or 0
  436.         3       net number for Busy status, or 0
  437.  
  438. If the server is Busy, the second and third byte of the status packet are
  439. the station and net number with which it is busy. If the server is Busy with
  440. no particular station, or if the status is not Busy, these bytes should both
  441. be set to zero.
  442.  
  443. Using the name 'PRINT' is deprecated because it makes it difficult for a
  444. printer server that supports multiple logical printers. Wherever possible
  445. you should use the printer's name.
  446.  
  447. Name request
  448. ------------
  449. If the status enquiry reason code is 6 (name request) then the client is asking the
  450. printer server for its name. The name sent by the client is 'PRINT' or 'SPOOL', but it
  451. is not necessary to check this. The server must reply to port &9E:
  452.  
  453.         Byte    Meaning
  454.         ----    -------
  455.         1 - 6   printer name, padded with spaces
  456.  
  457. If the printer server supports multiple logical printers it may send
  458. multiple replies with different names. If the client discards duplicate
  459. replies then it should take account of the name in the packet as well as the
  460. station and net numbers.
  461.  
  462. Flag bytes
  463. ----------
  464. For all status packets the flag byte currently has no meaning. Clients
  465. should send a flag byte of zero, and servers should send back the flag byte
  466. that they received from the client.
  467.  
  468.  
  469. NetPrint printing protocol
  470. ==========================
  471.  
  472. Finding the status before printing
  473. ----------------------------------
  474. Before starting to print, the client should ideally send a status enquiry to
  475. the server to ensure it is ready (see above).
  476.  
  477. Establishing the connection
  478. ---------------------------
  479. The connection is then established using packets where only the flag byte is
  480. relevant. It has this meaning:
  481.  
  482.         Bits    Meaning
  483.         ----    -------
  484.         0       sequence bit
  485.         1, 2    modes
  486.         3 - 6   task id
  487.         7       reserved (must be zero)
  488.  
  489. The client first sends a packet to port &D1 on the server, with either zero
  490. or one byte in it (the contents of which don't matter), and with the flag
  491. byte's sequence bit clear, its mode bits set to 2_01, and its task id bits
  492. set to either 2_0000 or 2_1000 depending upon the version of NetPrint.
  493.  
  494. * If the task id is 2_0000, then the client will only send data in &50 byte
  495.   blocks.
  496.  
  497. * If the task id is 2_1000, then the client code is both asking for the
  498.   allocation of a task id by the server, and trying to establish if the
  499.   server can accept large blocks of data (up to the size returned by SWI
  500.   Econet_PacketSize) or only small ones (up to &50 bytes).
  501.  
  502. If the server is unwilling to accept the print it doesn't send a reply. If
  503. it is willing then it sends back a single byte of any value to port &D1:
  504.  
  505. * If the client's task id was 2_0000 (ie small packets only), the server's
  506.   flag byte is the same as that it received from the client.
  507.  
  508. * If the client's task id was 2_1000 (ie request for large packets and task
  509.   id), the server uses the flag byte to respond to the request.
  510.  
  511. If the server isn't willing to assign task ids - and hence accept more than
  512. one connection from a single client - it sends back the client's (illegal)
  513. task id of 2_1000; otherwise it sends back a task id chosen from the ranges
  514. 2_0001 to 2_0111, or 2_1001 to 2_1111.
  515.  
  516. If the server can accept large blocks of data it sets the mode bits to 2_10,
  517. else it sets them to 2_01.
  518.  
  519. The connection is now established. The final flag byte sent by the server is
  520. the one that will be used when sending the data.
  521.  
  522. Sending the data
  523. ----------------
  524. The client then sends the data in blocks, the size of which can vary from
  525. zero bytes up to the maximum established by the connect protocol. The flag
  526. byte for each block is the same as that negotiated when connecting (see
  527. above), save that the sequence bit is toggled for each block.
  528.  
  529. Each time the server receives a block and is ready to accept another, it
  530. must acknowledge the received block with a one byte packet. The packet's
  531. flag byte must match that received from the client; its byte of data must be
  532. zero.
  533.  
  534. Closing the connection
  535. ----------------------
  536. When the client wants to close the connection, it sends a data packet with
  537. the mode bits set to 2_11. The data for this last packet must be terminated
  538. by an &03.
  539.  
  540.  
  541. Port claiming
  542. =============
  543. NetPrint claims ports &D1 and &9E with Econet_ClaimPort. A printer server
  544. should claim port &9F.
  545.  
  546.  
  547.  
  548. ================
  549. Deprecated calls
  550. ================
  551.  
  552. This section lists calls, often provided for backwards compatibility, that
  553. are now deprecated in favour of other calls. Much of this information is
  554. already in other parts of the PRM, but has been gathered together for
  555. reference.
  556.  
  557.  
  558. VDU calls
  559. =========
  560.  
  561. Many of the VDU calls that are present in RISC OS have been superseded by
  562. either the OS_Plot call or other SWIs. Instead of using the VDU call, you
  563. should call the relevant SWI.
  564.  
  565. Examples
  566. --------
  567. * You should use OS_Plot instead of VDU 25.
  568.  
  569. * You should use the standard printer driver interfaces to direct output to
  570.   the printer, instead of calling VDU 2 and VDU 3.
  571.  
  572. * You should ColourTrans SWIs to set text and graphics colours instead of
  573.   calling VDU 17 and VDU 18.
  574.  
  575. * You should use the font manager instead of calling VDU 23,25-26.
  576.  
  577. * You should use OS_SpriteOp SWIs instead of VDU 23,27
  578.  
  579.  
  580. OS_Byte/OS_Word calls
  581. =====================
  582. Many of the OS_Byte and OS_Word calls are very archaic, and are only present
  583. in RISC OS for backwards compatibility with older 8 bit machines. Many of
  584. these calls have been superseded by RISC OS SWIs which you should use
  585. instead.
  586.  
  587. It is worth noting that many of the OS_Byte calls are either not necessary
  588. or there are SWI equivalents. In future versions of the operating system
  589. OS_Byte may be removed altogether, and the useful calls be coded as proper
  590. RISC OS SWIs. The same applies to OS_Word calls.
  591.  
  592. OS_Byte examples
  593. ----------------
  594. * OS_Byte 7 and 8 are used to specify the serial port's baud rates for
  595.   receiving and sending data. These calls have been superseded by
  596.   OS_SerialOp 5 and 6.
  597.  
  598. * OS_Byte 128 is used for reading the position/state of the mouse. It has
  599.   been superseded by OS_Mouse.
  600.  
  601. * OS_Byte 71 selects the keyboard or alphabet. It has been replaced by the
  602.   concept of territories. You should call the Territory manager for doing
  603.   this sort of operation.
  604.  
  605. * All the OS_Bytes that refer to buffers (such as 15 to flush a buffer) have
  606.   been replaced by the relevant software vectors.
  607.  
  608. * The OS_Byte calls that refer to the escape key (such as 125 to set Escape
  609.   condition) are usually irrelevant, and should not be used on a
  610.   multi-tasking operating system. An exception is OS_Byte 229, which may be
  611.   useful to temporarily alter the Escape key status between successive Wimp
  612.   polls.
  613.  
  614. * OS_Byte 143 should not be used for issuing service calls; OS_ServiceCall
  615.   should be used instead.
  616.  
  617. * OS_Byte 160 reads a VDU variable; it has been superseded by
  618.   OS_ReadVduVariables.
  619.  
  620. OS_Word examples
  621. ----------------
  622. * OS_Word 9 should no longer be used to read the logical colour of a pixel.
  623.   You should use OS_ReadPoint instead.
  624.  
  625. * OS_Word 11 should no longer be used to read the palette. OS_ReadPalette
  626.   should be used instead.
  627.  
  628. * OS_ReadVduVariables should be used instead of OS_Word 13 to read current
  629.   and previous graphics cursor positions.
  630.  
  631. * OS_Word 21,0 should no longer be used for setting the pointer shape etc.
  632.   You should use OS_SpriteOp 36 (set pointer shape) instead.
  633.  
  634.  
  635. FileSwitch
  636. ==========
  637.  
  638. Service_StartUpFS has been removed.
  639.  
  640. As noted before, OS_Byte calls are deprecated. For example:
  641.  
  642. * OS_Byte 127 is deprecated, and you should use OS_Args 5 instead.
  643.  
  644. * You should no longer use OS_Byte 139 to set filing system options. *Opt 1
  645.   is no longer supported anyway. For the *Opt 4 usage you should instead use
  646.   OS_FSControl 48. (This is in preference to OS_FSControl 10 which -
  647.   although it is the direct equivalent - requires some state to be set up
  648.   with the *Dir command before calling it.)
  649.  
  650. * OS_Byte 255 is a removed facility for which there is no direct
  651.   replacement.
  652.  
  653. Many OS_GBPB calls are also deprecated:
  654.  
  655. * You should not use OS_GBPB 5 to read the name and boot option of a disc.
  656.   You should instead use OS_FSControl 37 (canonicalise path) and/or
  657.   OS_FSControl 47 (read boot option),
  658.  
  659. * You should no longer call OS_GBPB 6 or 7 to read a directory name and
  660.   privilege byte. OS_FSControl 37 (canonicalise path) provides an
  661.   alternative for reading directory names; privilege bytes are no longer
  662.   supported.
  663.  
  664. * You should use OS_GBPB 9 in preference to OS_GBPB 8.
  665.  
  666. Finally, as hinted above, you should use OS_FSControl 48 in preference to
  667. OS_FSControl 10.
  668.  
  669.  
  670. System extension/application SWIs
  671. =================================
  672.  
  673. RISC OS implements many SWIs for application and system extension (ie
  674. modules) development. Although theses SWIs are present and usable in the OS,
  675. some of them are archaic and have alternatives that should be used.
  676.  
  677. Econet
  678. ------
  679. With the event of AUN, most of the immediate operations are no longer
  680. supported. The only immediate operation supported under AUN is
  681. Econet_MachinePeek. If an application wishes to be AUN compatible then they
  682. should not attempt to implement the other immediate operations.
  683.  
  684. Time and date
  685. -------------
  686. You should no longer use SWIs such as OS_ConvertDateAndTime and
  687. OS_ConvertStandardDateAndTime. You should instead use the SWIs provided by
  688. the Territory manager.
  689.  
  690. Font Manager
  691. ------------
  692. When scanning a string for information (eg the width of the string or the
  693. caret position) you should call Font_ScanString instead of calls such as
  694. Font_StringWidth, Font_Caret, Font_StringBBox etc. However, Font_ScanString
  695. is a RISC OS 3 only SWI.
  696.  
  697. When setting font colours you should use ColourTrans_SetFontColours instead
  698. of Font_SetFontColours.
  699.  
  700. When calling Font_Paint with control sequences to set the colour, you should
  701. use control sequence 19 instead of 17 and 18. Again, control sequence 19 is
  702. only available with RISC OS 3.
  703.  
  704. You should not normally use the calls Font_SetFontMax (and the equivalent
  705. *Configure FontMax), Font_ReadFontMax, Font_SetScaleFactor,
  706. Font_ReadScaleFactor, and Font_SetThresholds. In doing so, you would be
  707. overriding the values set up by users and/or managed by the Wimp.
  708.  
  709. ColourTrans
  710. -----------
  711. Applications should not use GCOLs; they should instead deal with RGB palette
  712. entries and colour numbers.
  713.  
  714. If you must set a GCOL you should call ColourTrans_SetGCOL, or
  715. ColourTrans_ReturnColourNumber and OS_SetColour; you should not call
  716. ColourTrans_ReturnGCOL and then set the colour.
  717.  
  718.  
  719.  
  720. =========
  721. SWI Calls
  722. =========
  723.  
  724.  
  725. OS_SerialOp 7 (SWI &57)
  726. =======================
  727.  
  728. This reason code is for system use only; you must not use it in your own
  729. code.
  730.  
  731.  
  732. OS_SerialOp 8 (SWI &57)
  733. =======================
  734.  
  735. Read/write serial input buffer threshold value
  736.  
  737. On entry
  738. --------
  739. R0 = 8 (reason code)
  740. R1 = -1 to read or new value to write
  741.  
  742. On exit
  743. -------
  744. R0 preserved
  745. R1 = value before being overwritten
  746.  
  747. Interrupts
  748. ----------
  749. Interrupt status is undefined
  750. Fast interrupts are enabled
  751.  
  752. Processor Mode
  753. --------------
  754. Processor is in SVC mode
  755.  
  756. Re-entrancy
  757. -----------
  758. SWI is not re-entrant
  759.  
  760. Use
  761. ---
  762. The serial input routine attempts to halt input when the amount of free
  763. space left in the input buffer falls below a certain level. This call allows
  764. the value at which input is halted to be read or changed.
  765.  
  766. OS_SerialOp 0 can be used to examine or change the handshaking method.
  767.  
  768. The default value in RISC OS 3.5 is 17 characters, but this is subject to
  769. change and should not be relied upon.
  770.  
  771. Related SWIs
  772. ------------
  773. OS_Byte 203 (page 2-453)
  774.  
  775. Related vectors
  776. ---------------
  777. SerialV
  778.