home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 594a.lha / IOPack_v1.04 / IOPack.doc.pp / IOPack.doc
Text File  |  1991-11-07  |  9KB  |  318 lines
  1.  
  2. The IOPack Library for the Amiga
  3. Copyright © 1991 by Mark Thomas
  4.  
  5. Written by Mark Thomas
  6.  
  7. I can be reached by e-mail addresses:
  8.   Internet - amigamat@ccwf.cc.utexas.edu
  9.   GEnie    - M.THOMAS24
  10.  
  11. or snail mail:
  12.   2005 Willow Creek Dr. #2117
  13.   Austin, TX  78741
  14.  
  15. IOPack for the Amiga is Public Domain software, but the Copyright on the
  16. library code is retained by me.  I do not ask for money for the library.
  17.  
  18.      The IOPack library of routines are a set of routines to be used by
  19. the person first starting out programming in 68000 Assembly Language.  The
  20. routines simplify input and output for this programmer.  This Amiga version
  21. was written for the Amiga Assembler DevPac.  Other versions for CAPE and
  22. ADAPT and maybe even A68k will follow shortly.
  23.  
  24.      In order to use the library there are a few steps one must take:
  25.  
  26. 1. Add the line:
  27.  
  28.             include "IOPackDefs.txt"
  29.  
  30.    to your source code at the top.  IOPackDefs.txt turns off listing so
  31.    you may want to turn it back on after the line if it was on before.
  32.  
  33. 2. Put the label "main" at the start of your code.  With the Mac version
  34.    you have to XDEF main, but the Amiga version does not require this.
  35.  
  36. 3. When you assemble your program with DevPac use the -l command line
  37.    option.  This makes sure you get object code and not executable code.
  38.  
  39. 4. When you link as with blink just add "iopack.o" or "iopack.o.strip" as
  40.    the last object input file.
  41.    Example:  blink from sample.o iopack.o to sample
  42.  
  43.      There are a few labels that are reserved when using IOPack on the
  44. Amiga.  They are:
  45.  
  46. _IntuitionBase
  47. IOPackWindow
  48. Start
  49. startup_ok
  50. exit_iopack
  51. end_exit
  52. IOExit
  53.  
  54. These labels are used in IOPackDefs.txt for startup and exit.  The label
  55. "_IntuitionBase" refers to the library base of Intuition.  Use can use this
  56. to access Intuition functions.  And, for some of the functions you may need
  57. access to the window structure that IOPack opens.  That window pointer is
  58. accessed through the "IOPackWindow" label.
  59.  
  60. IOPack strings on the Amiga are null terminated strings.
  61.  
  62. A sample IOPack application which just opens the window and waits for a
  63. keypress is supplied.  See the file "sample.s"
  64.  
  65. In the file "IOPackDefs.txt" there are some comments on how to open your own
  66. Amiga libraries and how to add extra routines to IOPack.  Also, the complete
  67. and commented source for IOPack is supplied as a tool for learning as well.
  68.  
  69. It should be noted that while normally the first thing you must do in an
  70. IOPack program is to open the window so that input and output has a place to
  71. go, on the Amiga version of IOPack if the window is not open and a routine
  72. that requires the window is called, that routine will open the window for
  73. you will a default title of "Default Window" and then the routine will finish
  74. it's action.  The Mac version does not have this feature.
  75.  
  76. **WARNING**
  77.  
  78. Upon opening the window you may receive an error.  This error condition is
  79. returned in D0.L.  A non-zero D0.L means there is no error.  If D0.L is 0
  80. then there is and error.  If this error condition is found then your program
  81. should do it's necessary cleanup and then JSR Exit.  Because of the feature
  82. described in the above paragraph, auto-window-opening, library routines that
  83. detect they need to open a window and subsequently find an error in trying
  84. this, will not do their intended action, but will just exit safely.  There is
  85. no warning to you of this and no for your program to detect this.  This is
  86. why I must discourage you from using the auto-window-open feature.  Open the
  87. window yourself and check to see if there is an error.  None of this was
  88. apparently an issue on the Mac version of the IOPack.
  89.  
  90. -----------------------------------------------------------------------------
  91.  
  92. Below are the routines for IOPack for the Amiga:
  93.  
  94. Operations on the window:
  95.  
  96.  
  97. *  MakeWindow.......Make the window.
  98.  
  99.    input:
  100.      A0: ptr to title string
  101.  
  102.    output:
  103.      D0: 0L if error, non-zero if no error
  104.  
  105.    NOTE: This routine will open a window the full size of the screen minus
  106.          the screens top border (so that you can drag).  The window can be
  107.          resized, depth arranged, and dragged.  There is no close button
  108.          since there is no way of handling it in the IOPack way of doing
  109.          things.
  110.  
  111.  
  112. *  ClearWindow......Home cursor and clear window.
  113.  
  114.  
  115. *  GetWindowSize....Return the size of the window.
  116.  
  117.    output:
  118.      D0.L: upper word - width of the window
  119.            lower word - height of the window
  120.  
  121.  
  122. *  WindowTitle......Change the title of the window.
  123.  
  124.    input:
  125.      A0: ptr to new title string
  126.  
  127.  
  128. *  SetFont..........Change the style of the font.
  129.  
  130.    input:
  131.      D2.W: font style (-1-Plain, 0-Bold, 1-Italic, 2-Underline)
  132.  
  133.    NOTE: Mac version allows for Font and Size change.  For compatibility
  134.          reasons, the Amiga version does not do this.  In other words, the
  135.          Amiga does not have Chicago, Geneva, or Monaco for standard fonts.
  136.          Likewise, Mac styles 3-6 (Outline, Shadow, Condense, and Extend)
  137.          do nothing and are not implemented.  This routine will just ignore
  138.          what it cannot do.
  139.  
  140.  
  141. Character and String I/O Routines:
  142.  
  143.  
  144. *  GetC.............Get a character from the keyboard.
  145.  
  146.    output:
  147.      D0.B: character read in
  148.  
  149.  
  150. *  CharOut..........Output a character to the window.
  151.  
  152.    input:
  153.      D0.B: character to output
  154.  
  155.  
  156. *  BackSpace........Delete the character to the left of the cursor.
  157.  
  158.  
  159. *  CStrin...........Input a CR delimited string.
  160.  
  161.    input:
  162.      A0.L: address of buffer to store string
  163.      D0.W: size of the buffer
  164.  
  165.    output:
  166.      A0.L: address of string (same as input)
  167.      D0.W: Number of characters actually read in, 0 <= D0.W.out <= D0.W.in-1
  168.  
  169.    NOTE: The string will be null terminated and will not have a CR in it.
  170.          The Mac version uses strings where string[0] = len(string).
  171.  
  172.  
  173. *  CStrout..........Output a C string.
  174.  
  175.    input:
  176.      A0: address of string to output, must be null terminated
  177.  
  178.    NOTE: Mac strings in IOPack have string[0] = len(string).  Amiga
  179.          strings are C or Unix style null terminated strings.
  180.  
  181.  
  182. *  Strin............Input a counted string
  183.  
  184.    input:
  185.      A0.L: address of buffer to store string
  186.      D0.W: Maximum number of characters to read in
  187.  
  188.    output:
  189.      A0.L: address of string buffer (same as input)
  190.      D0.W: number of characters actually read in
  191.  
  192.  
  193. *  Strout...........Output a counted string.
  194.  
  195.    input:
  196.      A0.L: address of string to output
  197.      D0.W: length of the string
  198.  
  199.  
  200. *  NewLine..........Move cursor to beginning of next line.
  201.  
  202.  
  203. *  Spaces...........Output given number of spaces
  204.  
  205.    input:
  206.      D0.W: number of spaces
  207.  
  208.  
  209. Numeric I/O Routines:
  210.  
  211.  
  212. *  DecIn............Input a decimal number (word size).
  213.  
  214.    output:
  215.      D0.W: binary equivalent of decimal number
  216.  
  217.  
  218. *  DecIn_Long.......Input a decimal number (long size)
  219.  
  220.    output:
  221.      D0.L: binary equivalent of decimal number
  222.  
  223.  
  224. *  DecOut...........Output a decimal number (word size).
  225.  
  226.    input:
  227.      D0.W: binary equivalent of decimal number
  228.  
  229.  
  230. *  DecOut_Long......Output a decimal number (long size).
  231.  
  232.    input:
  233.      D0.L: binary equivalent of decimal number
  234.  
  235.  
  236. *  HexIn............Input a hex number (word size).
  237.  
  238.    output:
  239.      D0.W: binary equivalent of hex number
  240.  
  241.  
  242. *  HexIn_Long.......Input a hex number (long size).
  243.  
  244.    output:
  245.      D0.L: binary equivalent of hex number
  246.  
  247.  
  248. *  HexOut...........Output a hex number (word size).
  249.  
  250.    input:
  251.      D0.W: binary equivalent of number
  252.  
  253.  
  254. *  HexOut_Long......Output a hex number (long size).
  255.  
  256.    input:
  257.      D0.W: binary equivalent of number
  258.  
  259.  
  260. Math Routines:
  261.  
  262.  
  263. *  DivuLW...........Divide unsigned longword by word
  264.                    and return quotient and remainder.
  265.  
  266.    input:
  267.      D0.L: dividend
  268.      D1.W: divisor
  269.  
  270.    output:
  271.      D0.L: quotient
  272.      D1.W: remainder
  273.  
  274.    NOTE: Mac version does not return remainder
  275.  
  276.  
  277. *  Rand.............Make a 16 bit random number.
  278.  
  279.    output:
  280.      D0.W: random number
  281.  
  282.  
  283. *  ResetRand........Restart the random number generator.
  284.  
  285.  
  286. *  Seed.............Randomize the random number generator.
  287.  
  288.  
  289. Miscellaneous Routines:
  290.  
  291.  
  292. *  IOExit...........Cleanup and terminate program.
  293.  
  294.    NOTE: You must JSR to this routine in order to stay compatible with the
  295.          Mac version.  I think it's unnecessary and is kinda weird looking.
  296.          It makes you think IOExit comes back!
  297.  
  298.  
  299. *  WaitForEvent.....Wait for a key press.
  300.  
  301.    NOTE: The Mac version also let you hit the mouse button to continue.
  302.          Mine does not.  I will add this later.
  303.  
  304.  
  305. *  AskYesNo.........Autorequest a Yes/No question.
  306.  
  307.    input:
  308.      A0: ptr to question string
  309.  
  310.    output:
  311.      Z bit set if Yes, clear if No
  312.  
  313.    NOTE: I never saw what the Mac version did, but I decided to make mine
  314.          an Amiga standard requester.
  315.  
  316.  
  317. *  WrtIOInfo........Write copyright and ordering info.
  318.