home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / s / swi < prev    next >
Encoding:
Text File  |  1996-11-14  |  6.2 KB  |  131 lines
  1. <TITLE>swi -- Python library reference</TITLE>
  2. Next: <A HREF="../d/drawf" TYPE="Next">drawf</A>  
  3. Prev: <A HREF="../r/riscospath" TYPE="Prev">riscospath</A>  
  4. Up: <A HREF="../r/riscos_only" TYPE="Up">RISCOS ONLY</A>  
  5. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  6. <H1>13.3. Built-in Module <CODE>swi</CODE></H1>
  7. This module provides access to the RiscOS SWI interface. It provides
  8. a function <CODE>swi</CODE> that puts suitable values in the arm registers,
  9. calls the SWI and extracts values from registers.
  10. <P>
  11. As many SWIs manipulate blocks of memory a new object type is provided
  12. for handling blocks of memory and inserting and extracting values from them.
  13. <P>
  14. Errors are reported as exceptions; the usual exceptions are given
  15. for type, index and value errors, while errors reported by X versions of the
  16. system calls raise
  17. <CODE>swi.error</CODE>, described below.
  18. <P>
  19. Module <CODE>swi</CODE> defines the following data item:
  20. <P>
  21. <DL><DT><B>error</B> -- exception of module swi<DD>
  22. This exception is raised when an RiscOS X SWI returns a
  23. RiscOS-related error (e.g., not for illegal argument types).  Its
  24. string value is <CODE>'swi.error'</CODE>.  The accompanying value is a
  25. string returned by the SWI.
  26. </DL>
  27. It defines the following functions:
  28. <P>
  29. <DL><DT><B>swi</B> (<VAR>name</VAR>,<VAR>descriptor</VAR>,...) -- function of module swi<DD>
  30. Calls the swi given by <VAR>name</VAR> with registers given by <VAR>descriptor</VAR>.
  31. <VAR>name</VAR> can either be an integer SWI number, or a string SWI name. 
  32. SWI names are case dependent. To call the X version of the SWI you should
  33. set the X bit in the number, or preceed the name with X.
  34. <P>
  35. <VAR>descriptor</VAR> is a string that determines the registers to be passed 
  36. and returned. Values to pass are taken sequentially from the remaining
  37. arguments, they are assigned to registers starting from r0. Characters 
  38. of <VAR>descriptor</VAR> indicate how to pass values.
  39. <P>
  40. <DL>
  41. <DT><I>Character</I><DD><I>Meaning</I>  ---  <I>Argument Type</I>
  42. <P>
  43. <DT>`<SAMP>i</SAMP>'<DD>pass an integer  ---  int
  44. <DT>`<SAMP>s</SAMP>'<DD>pass a pointer to a string  ---  string
  45. <DT>`<SAMP>b</SAMP>'<DD>pass a pointer to the start of a block  ---  block
  46. <DT>`<SAMP>e</SAMP>'<DD>pass a pointer after the end of a block  ---  block
  47. <DT>`<SAMP>0-9</SAMP>'<DD>insert 0-9 in the register  ---  -
  48. <DT>`<SAMP>-</SAMP>'<DD>insert  in the register  ---  -
  49. <DT>`<SAMP>.</SAMP>'<DD>skip a register  ---  -
  50. </DL>
  51. Note: Strings are read--only. If you want to alter a buffer passed to a SWI you
  52. must use a block.
  53. <P>
  54. If the descriptor contains a semi--colon, characters after this refer
  55. to values returned by registers. A single value is returned as an
  56. object. Several values are returned as a tuple.
  57. <P>
  58. <DL>
  59. <DT><I>Character</I><DD><I>Meaning</I>  ---  <I>Output Type</I>
  60. <P>
  61. <DT>`<SAMP>i</SAMP>'<DD>return an integer  ---  int
  62. <DT>`<SAMP>s</SAMP>'<DD>return a string  ---  string
  63. <DT>`<SAMP>*</SAMP>'<DD>return the carry flag  ---  int
  64. <DT>`<SAMP>.</SAMP>'<DD>skip a register  ---  -
  65. </DL>
  66. Example: wimp_initialise
  67. <P>
  68. <UL COMPACT><CODE>>>> from swi import *<P>
  69. >>> msgs=block(2,[0x600c0,0])<P>
  70. >>> pname="myprog"<P>
  71. >>> wimpver,taskhand=swi(0x600c0,"iisb;ii",310,0x4b534154,pname,msgs)<P>
  72. </CODE></UL>
  73. </DL>
  74. <DL><DT><B>block</B> (<VAR>size</VAR> [, <VAR>initializer</VAR>]) -- function of module swi<DD>
  75. Returns a new block of <VAR>size</VAR> words. The initializer must be a string
  76. or a list of integers. The initializer is truncated to fit the block.
  77. If it is too short it is padded with zeros. If there is no initializer
  78. the content of the block is undefined.
  79. </DL>
  80. The memory of a block is guaranteed not to move unless the block is deleted
  81. or resized.
  82. <P>
  83. Blocks support index and slice operations as for lists of integers, except
  84. that the block cannot change size, so assignments are truncated or padded
  85. as for initialization. Slices beyond the end of the block give index errors.
  86. <P>
  87. <DL><DT><B>register</B> (<VAR>size</VAR>,<VAR>address</VAR>) -- function of module swi<DD>
  88. Registers a prexisting memory block of <VAR>size</VAR> words as a block.
  89. Returns a new block. The memory supplied will not be freed when the block
  90. is deleted, or moved when it is resized.
  91. </DL>
  92. Block items support the following data items and methods.
  93. <P>
  94. <DL><DT><B>length</B> -- data of module swi<DD>
  95. The length of the block in bytes. Equal to <CODE>4*len(<VAR>block</VAR>)</CODE>.
  96. </DL>
  97. <DL><DT><B>start</B> -- data of module swi<DD>
  98. The start address of the memory block.
  99. </DL>
  100. <DL><DT><B>end</B> -- data of module swi<DD>
  101. The address after the end of the memory block.
  102. </DL>
  103. <DL><DT><B>padstring</B> (<VAR>string</VAR>,<VAR>padchar</VAR> [,<VAR>x</VAR>,<VAR>y</VAR>]) -- function of module swi<DD>
  104. The string is copied into the block between bytes <CODE>x</CODE>  and <CODE>y-1</CODE>.
  105. The string is truncated or padded with <VAR>padchar</VAR> as required.
  106. <VAR>x</VAR> and <VAR>y</VAR> default to 0 and <CODE>block.length</CODE>.
  107. </DL>
  108. <DL><DT><B>tostring</B> ([<VAR>x</VAR>,<VAR>y</VAR>]) -- function of module swi<DD>
  109. The bytes between <CODE>x</CODE>  and <CODE>y-1</CODE> are returned as a string.
  110. <VAR>x</VAR> and <VAR>y</VAR> default to 0 and <CODE>block.length</CODE>.
  111. </DL>
  112. <DL><DT><B>nullstring</B> ([<VAR>x</VAR>,<VAR>y</VAR>]) -- function of module swi<DD>
  113. The bytes between <CODE>x</CODE>  and <CODE>y-1</CODE> are returned as a string, the
  114. string is terminated before the first null character if any.
  115. <VAR>x</VAR> and <VAR>y</VAR> default to 0 and <CODE>block.length</CODE>.
  116. </DL>
  117. <DL><DT><B>ctrlstring</B> ([<VAR>x</VAR>,<VAR>y</VAR>]) -- function of module swi<DD>
  118. The bytes between <CODE>x</CODE>  and <CODE>y-1</CODE> are returned as a string, the
  119. string is terminated before the first control character if any.
  120. <VAR>x</VAR> and <VAR>y</VAR> default to 0 and <CODE>block.length</CODE>.
  121. </DL>
  122. <DL><DT><B>bitset</B> (<VAR>i</VAR>,<VAR>x</VAR>,<VAR>y</VAR>) -- function of module swi<DD>
  123. <CODE>b.bitset(x,y)</CODE> is equivalent to @verb{b[i]=(b[i]&y)^x}.
  124. </DL>
  125. <DL><DT><B>resize</B> (<VAR>size</VAR>) -- function of module swi<DD>
  126. Changes the size of the block. The new size is in words. If the block was
  127. created using <CODE>register</CODE> this just changes the recorded end of the
  128. block. Otherwise the block may move, and the data in the block is
  129. truncated or zero padded as neccesary.
  130. </DL>
  131.