home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / amiga_lib.doc next >
Text File  |  1992-09-01  |  52KB  |  1,781 lines
  1. TABLE OF CONTENTS
  2.  
  3. amiga.lib/AddTOF
  4. amiga.lib/afp
  5. amiga.lib/ArgArrayDone
  6. amiga.lib/ArgArrayInit
  7. amiga.lib/ArgInt
  8. amiga.lib/ArgString
  9. amiga.lib/arnd
  10. amiga.lib/BeginIO
  11. amiga.lib/CallHook
  12. amiga.lib/CallHookA
  13. amiga.lib/CheckRexxMsg
  14. amiga.lib/CoerceMethod
  15. amiga.lib/CoerceMethodA
  16. amiga.lib/CreateExtIO
  17. amiga.lib/CreatePort
  18. amiga.lib/CreateStdIO
  19. amiga.lib/CreateTask
  20. amiga.lib/CxCustom
  21. amiga.lib/CxDebug
  22. amiga.lib/CxFilter
  23. amiga.lib/CxSender
  24. amiga.lib/CxSignal
  25. amiga.lib/CxTranslate
  26. amiga.lib/dbf
  27. amiga.lib/DeleteExtIO
  28. amiga.lib/DeletePort
  29. amiga.lib/DeleteStdIO
  30. amiga.lib/DeleteTask
  31. amiga.lib/DoMethod
  32. amiga.lib/DoMethodA
  33. amiga.lib/DoSuperMethod
  34. amiga.lib/DoSuperMethodA
  35. amiga.lib/FastRand
  36. amiga.lib/fpa
  37. amiga.lib/FreeIEvents
  38. amiga.lib/GetRexxVar
  39. amiga.lib/HookEntry
  40. amiga.lib/HotKey
  41. amiga.lib/InvertString
  42. amiga.lib/NewList
  43. amiga.lib/printf
  44. amiga.lib/RangeRand
  45. amiga.lib/RemTOF
  46. amiga.lib/SetRexxVar
  47. amiga.lib/SetSuperAttrs
  48. amiga.lib/sprintf
  49. amiga.lib/stdio
  50. amiga.lib/TimeDelay
  51. amiga.lib/AddTOF                                             amiga.lib/AddTOF
  52.  
  53.    NAME
  54.     AddTOF - add a task to the VBlank interrupt server chain.
  55.  
  56.    SYNOPSIS
  57.     AddTOF(i,p,a);
  58.  
  59.     VOID AddTOF(struct Isrvstr *, APTR, APTR);
  60.  
  61.    FUNCTION
  62.     Adds a task to the vertical-blanking interval interrupt server
  63.     chain. This prevents C programmers from needing to write an
  64.     assembly language stub to do this function.
  65.  
  66.    INPUTS
  67.     i - pointer to an initialized Isrvstr structure
  68.     p - pointer to the C-code routine that this server is to call each
  69.         time TOF happens
  70.     a - pointer to the first longword in an array of longwords that
  71.         is to be used as the arguments passed to your routine
  72.         pointed to by p.
  73.  
  74.    SEE ALSO
  75.     RemTOF(), <graphics/graphint.h>
  76.  
  77. amiga.lib/afp                                                   amiga.lib/afp
  78.  
  79.    NAME
  80.     afp - Convert ASCII string variable into fast floating point
  81.  
  82.    SYNOPSIS
  83.     ffp_value = afp(string);
  84.  
  85.     FUNCTION
  86.     Accepts the address of the ASCII string in C format that is
  87.     converted into an FFP floating point number.
  88.  
  89.     The string is expected in this Format:
  90.     {S}{digits}{'.'}{digits}{'E'}{S}{digits}
  91.     <*******MANTISSA*******><***EXPONENT***>
  92.  
  93.  
  94.     Syntax rules:
  95.     Both signs are optional and are '+' or '-'. The mantissa must be
  96.     present. The exponent need not be present. The mantissa may lead
  97.     with a decimal point. The mantissa need not have a decimal point.
  98.     Examples: All of these values represent the number fourty-two.
  99.              42        .042e3
  100.              42.      +.042e+03
  101.             +42.      0.000042e6
  102.         0000042.00     420000e-4
  103.                  420000.00e-0004
  104.  
  105.     Floating point range:
  106.     Fast floating point supports the value zero and non-zero values
  107.     within the following bounds -
  108.             18                   20
  109.      9.22337177 x 10   > +number >    5.42101070 x 10
  110.             18                   -20
  111.     -9.22337177 x 10   > -number > -2.71050535 x 10
  112.  
  113.     Precision:
  114.     This conversion results in a 24 bit precision with guaranteed
  115.     error less than or equal to one-half least significant bit.
  116.  
  117.     INPUTS
  118.     string - Pointer to the ASCII string to be converted.
  119.  
  120.  
  121.     OUTPUTS
  122.     string - points to the character which terminated the scan
  123.     equ - fast floating point equivalent
  124. amiga.lib/ArgArrayDone                                 amiga.lib/ArgArrayDone
  125.  
  126.    NAME
  127.     ArgArrayDone -- release the memory allocated by a previous call
  128.             to ArgArrayInit(). (V36)
  129.  
  130.    SYNOPSIS
  131.     ArgArrayDone();
  132.  
  133.     VOID ArgArrayDone(VOID);
  134.  
  135.    FUNCTION
  136.     This function frees memory and does cleanup required after a
  137.     call to ArgArrayInit(). Don't call this until you are done using
  138.     the ToolTypes argument strings.
  139.  
  140.    SEE ALSO
  141.     ArgArrayInit()
  142.  
  143. amiga.lib/ArgArrayInit                                 amiga.lib/ArgArrayInit
  144.  
  145.    NAME
  146.     ArgArrayInit -- allocate and initialize a tooltype array. (V36)
  147.  
  148.    SYNOPSIS
  149.     ttypes = ArgArrayInit(argc,argv);
  150.  
  151.     UBYTE **ArgArrayInit(LONG,UBYTE **);
  152.  
  153.    FUNCTION
  154.     This function returns a null-terminated array of strings
  155.     suitable for sending to icon.library/FindToolType(). This array will
  156.     be the ToolTypes array of the program's icon, if it was started from
  157.     Workbench. It will just be 'argv' if the program was started from
  158.     a shell.
  159.  
  160.     Pass ArgArrayInit() your startup arguments received by main().
  161.  
  162.     ArgArrayInit() requires that icon.library be open (even if the caller
  163.     was started from a shell, so that the function FindToolType() can be
  164.     used) and may call GetDiskObject(), so clean up is necessary when
  165.     the strings are no longer needed. The function ArgArrayDone() does
  166.     just that.
  167.  
  168.    INPUTS
  169.     argc - the number of arguments in argv, 0 when started from Workbench
  170.     argv - an array of pointers to the program's arguments, or the
  171.            Workbench startup message when started from WB.
  172.  
  173.    RESULTS
  174.     ttypes - the initialized argument array or NULL if it could not be
  175.              allocated
  176.  
  177.    EXAMPLE
  178.     Use of these routines facilitates the use of ToolTypes or command-
  179.     line arguments to control end-user parameters in Commodities
  180.     applications. For example, a filter used to trap a keystroke for
  181.     popping up a window might be created by something like this:
  182.  
  183.             char   *ttypes  = ArgArrayInit(argc, argv);
  184.             CxObj   *filter = UserFilter(ttypes, "POPWINDOW", "alt f1");
  185.  
  186.                ... with ...
  187.  
  188.                CxObj *UserFilter(char **tt, char *action_name,
  189.                   char *default_descr)
  190.         {
  191.         char *desc;
  192.  
  193.             desc = FindToolType(tt,action_name);
  194.  
  195.             return(CxFilter((ULONG)(desc? desc: default_descr)));
  196.         }
  197.  
  198.     In this way the user can assign "alt f2" to the action by
  199.     entering a tooltype in the program's icon of the form:
  200.  
  201.         POPWINDOW=alt f2
  202.  
  203.     or by starting the program from the CLI like so:
  204.  
  205.         myprogram "POPWINDOW=alt f2"
  206.  
  207.    NOTE
  208.     Your program must open icon.library and set up IconBase before calling
  209.     this routine. In addition IconBase must remain valid until after
  210.     ArgArrayDone() has been called!
  211.  
  212.    SEE ALSO
  213.     ArgArrayDone(), ArgString(), ArgInt(), icon.library/FindToolType()
  214.  
  215. amiga.lib/ArgInt                                             amiga.lib/ArgInt
  216.  
  217.    NAME
  218.     ArgInt -- return an integer value from a ToolTypes array. (V36)
  219.  
  220.    SYNOPSIS
  221.     value = ArgInt(tt,entry,defaultval)
  222.  
  223.     LONG ArgInt(UBYTE **,STRPTR,LONG);
  224.  
  225.    FUNCTION
  226.     This function looks in the ToolTypes array 'tt' returned
  227.     by ArgArrayInit() for 'entry' and returns the value associated
  228.     with it. 'tt' is in standard ToolTypes format such as:
  229.  
  230.         ENTRY=Value
  231.  
  232.     The Value string is passed to atoi() and the result is returned by
  233.     this function.
  234.  
  235.     If 'entry' is not found, the integer 'defaultval' is returned.
  236.  
  237.    INPUTS
  238.     tt - a ToolTypes array as returned by ArgArrayInit()
  239.     entry - the entry in the ToolTypes array to search for
  240.     defaultval - the value to return in case 'entry' is not found within
  241.              the ToolTypes array
  242.  
  243.    RESULTS
  244.     value - the value associated with 'entry', or defaultval if 'entry'
  245.         is not in the ToolTypes array
  246.  
  247.    NOTES
  248.     This function requires that dos.library V36 or higher be opened.
  249.  
  250.    SEE ALSO
  251.     ArgArrayInit()
  252.  
  253. amiga.lib/ArgString                                       amiga.lib/ArgString
  254.  
  255.    NAME
  256.     ArgString -- return a string pointer from a ToolTypes array. (V36)
  257.  
  258.    SYNOPSIS
  259.     string = ArgString(tt,entry,defaultstring)
  260.  
  261.     STRPTR ArgString(UBYTE **,STRPTR,STRPTR);
  262.  
  263.    FUNCTION
  264.     This function looks in the ToolTypes array 'tt' returned
  265.     by ArgArrayInit() for 'entry' and returns the value associated
  266.     with it. 'tt' is in standard ToolTypes format such as:
  267.  
  268.         ENTRY=Value
  269.  
  270.     This function returns a pointer to the Value string.
  271.  
  272.     If 'entry' is not found, 'defaultstring' is returned.
  273.  
  274.    INPUTS
  275.     tt - a ToolTypes array as returned by ArgArrayInit()
  276.     entry - the entry in the ToolTypes array to search for
  277.     defaultstring - the value to return in case 'entry' is not found within
  278.                 the ToolTypes array
  279.  
  280.    RESULTS
  281.     value - the value associated with 'entry', or defaultstring if 'entry'
  282.         is not in the ToolTypes array
  283.  
  284.    SEE ALSO
  285.     ArgArrayInit()
  286.  
  287. amiga.lib/arnd                                                 amiga.lib/arnd
  288.  
  289.   NAME
  290.     arnd - ASCII round of the provided floating point string
  291.  
  292.    SYNOPSIS
  293.     arnd(place, exp, &string[0]);
  294.  
  295.    FUNCTION
  296.     Accepts an ASCII string representing an FFP floating point
  297.     number, the binary representation of the exponent of said
  298.     floating point number and the number of places to round to.
  299.     A rounding process is initiated, either to the left or right
  300.     of the decimal place and the result placed back at the
  301.     input address defined by &string[0].
  302.  
  303.    INPUTS
  304.     place - integer representing number of decimal places to round to
  305.     exp - integer representing exponent value of the ASCII string
  306.     &string[0] - address where rounded ASCII string is to be placed
  307.              (16 bytes)
  308.  
  309.    RESULT
  310.     &string[0] - rounded ASCII string
  311.  
  312.    BUGS
  313.     None
  314. amiga.lib/BeginIO                                           amiga.lib/BeginIO
  315.  
  316.    NAME
  317.     BeginIO -- initiate asynchronous device I/O
  318.  
  319.    SYNOPSIS
  320.     BeginIO(ioReq)
  321.  
  322.     VOID BeginIO(struct IORequest *);
  323.  
  324.    FUNCTION
  325.     This function takes an IORequest, and passes it directly to the
  326.     "BeginIO" vector of the proper device.  This is equivalent to
  327.     SendIO(), except that io_Flags is not cleared. A good understanding
  328.     of Exec device I/O is required to properly use this function.
  329.  
  330.     This function does not wait for the I/O to complete.
  331.  
  332.    INPUTS
  333.     ioReq - an initialized and opened IORequest structure with the
  334.             io_Flags field set to a reasonable value (set to 0 if you do
  335.         not require io_Flags).
  336.  
  337.    SEE ALSO
  338.     exec.library/DoIO(), exec.library/SendIO(), exec.library/WaitIO()
  339.  
  340. amiga.lib/CallHook                                         amiga.lib/CallHook
  341.  
  342.    NAME
  343.     CallHook -- Invoke a hook given a message on the stack.  (V36)
  344.  
  345.    SYNOPSIS
  346.     result = CallHook( hookPtr, obj, ... )
  347.  
  348.     ULONG CallHook( struct Hook *, Object *, ... );
  349.  
  350.    FUNCTION
  351.     Like CallHookA(), CallHook() invoke a hook on the supplied
  352.     hook-specific data (an "object") and a parameter packet ("message").
  353.     However, CallHook() allows you to build the message on your stack.
  354.  
  355.    INPUTS
  356.     hookPtr - A system-standard hook
  357.     obj - hook-specific data object
  358.     ... - The hook-specific message you wish to send.  The hook is
  359.         expecting a pointer to the message, so a pointer into your
  360.         stack will be sent.
  361.  
  362.    RESULT
  363.     result - a hook-specific result.
  364.  
  365.    NOTES
  366.     While this function requires V36 or higher intuition.library,
  367.     it first appeared in V37 amiga.lib.
  368.  
  369.    EXAMPLE
  370.     If your hook's message was
  371.  
  372.         struct myMessage
  373.         {
  374.         ULONG mm_FirstGuy;
  375.         ULONG mm_SecondGuy;
  376.         ULONG mm_ThirdGuy;
  377.         };
  378.  
  379.     You could write:
  380.  
  381.         result = CallHook( hook, obj, firstguy, secondguy, thirdguy );
  382.  
  383.     as a shorthand for:
  384.  
  385.         struct myMessage msg;
  386.  
  387.         msg.mm_FirstGuy = firstguy;
  388.         msg.mm_SecondGuy = secondguy;
  389.         msg.mm_ThirdGuy = thirdguy;
  390.  
  391.         result = CallHookA( hook, obj, &msg );
  392.  
  393.    SEE ALSO
  394.     CallHookA(), utility.library/CallHookPkt(), <utility/hooks.h>
  395.  
  396. amiga.lib/CallHookA                                       amiga.lib/CallHookA
  397.  
  398.    NAME
  399.     CallHookA -- Invoke a hook given a pointer to a message.  (V36)
  400.  
  401.    SYNOPSIS
  402.     result = CallHookA( hookPtr, obj, message )
  403.  
  404.     ULONG CallHook( struct Hook *, Object *, APTR );
  405.  
  406.    FUNCTION
  407.     Invoke a hook on the supplied hook-specific data (an "object")
  408.     and a parameter packet ("message").  This function is equivalent
  409.     to utility.library/CallHookPkt().
  410.  
  411.    INPUTS
  412.     hookPtr - A system-standard hook
  413.     obj - hook-specific data object
  414.     message - The hook-specific message you wish to send
  415.  
  416.    RESULT
  417.     result - a hook-specific result.
  418.  
  419.    NOTES
  420.     While this function requires V36 or higher intuition.library,
  421.     it first appeared in V37 amiga.lib.
  422.  
  423.    SEE ALSO
  424.     CallHook(), utility.library/CallHookPkt(), <utility/hooks.h>
  425.  
  426. amiga.lib/CheckRexxMsg                                 amiga.lib/CheckRexxMsg
  427.  
  428.    NAME
  429.     CheckRexxMsg - Check if a RexxMsg is from ARexx
  430.  
  431.    SYNOPSIS
  432.     result = CheckRexxMsg(message)
  433.     D0                    A0
  434.  
  435.     BOOL CheckRexxMsg(struct RexxMsg *);
  436.  
  437.    FUNCTION
  438.     This function checks to make sure that the message is from ARexx
  439.     directly.  It is required when using the Rexx Variable Interface
  440.     routines (RVI) that the message be from ARexx.
  441.  
  442.     While this function is new in the V37 amiga.lib, it is safe to
  443.     call it in all versions of the operating system.  It is also
  444.     PURE code, thus usable in resident/pure executables.
  445.  
  446.    NOTE
  447.     This is a stub in amiga.lib.  It is only available via amiga.lib.
  448.     The stub has two labels.  One, _CheckRexxMsg, takes the arguments
  449.     from the stack.  The other, CheckRexxMsg, takes the arguments in
  450.     registers.
  451.  
  452.    EXAMPLE
  453.     if (CheckRexxMsg(rxmsg))
  454.     {
  455.         /* Message is one from ARexx */
  456.     }
  457.  
  458.    INPUTS
  459.     message        A pointer to the RexxMsg in question
  460.  
  461.    RESULTS
  462.     result        A boolean - TRUE if message is from ARexx.
  463.  
  464.    SEE ALSO
  465.     GetRexxVar(), SetRexxVar()
  466.  
  467. amiga.lib/CoerceMethod                                 amiga.lib/CoerceMethod
  468.  
  469.    NAME
  470.     CoerceMethod -- Perform method on coerced object.  (V36)
  471.  
  472.    SYNOPSIS
  473.     result = CoerceMethod( cl, obj, MethodID, ... )
  474.  
  475.     ULONG CoerceMethod( struct IClass *, Object *, ULONG, ... );
  476.  
  477.    FUNCTION
  478.     Boopsi support function that invokes the supplied message
  479.     on the specified object, as though it were the specified
  480.     class.  Equivalent to CoerceMethodA(), but allows you to
  481.     build the message on the stack.
  482.  
  483.    INPUTS
  484.     cl - pointer to boopsi class to receive the message
  485.     obj - pointer to boopsi object
  486.     ... - method-specific message built on the stack
  487.  
  488.    RESULT
  489.     result - class and message-specific result.
  490.  
  491.    NOTES
  492.     While this function requires V36 or higher intuition.library,
  493.     it first appeared in V37 amiga.lib.
  494.  
  495.    SEE ALSO
  496.     CoerceMethodA(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  497.     ROM Kernel Manual boopsi section
  498.  
  499. amiga.lib/CoerceMethodA                               amiga.lib/CoerceMethodA
  500.  
  501.    NAME
  502.     CoerceMethodA -- Perform method on coerced object.  (V36)
  503.  
  504.    SYNOPSIS
  505.     result = CoerceMethodA( cl, obj, msg )
  506.  
  507.     ULONG CoerceMethodA( struct IClass *, Object *, Msg * );
  508.  
  509.    FUNCTION
  510.     Boopsi support function that invokes the supplied message
  511.     on the specified object, as though it were the specified
  512.     class.
  513.  
  514.    INPUTS
  515.     cl - pointer to boopsi class to receive the message
  516.     obj - pointer to boopsi object
  517.     msg - pointer to method-specific message to send
  518.  
  519.    RESULT
  520.     result - class and message-specific result.
  521.  
  522.    NOTES
  523.     While this function requires V36 or higher intuition.library,
  524.     it first appeared in V37 amiga.lib.
  525.     Some early example code may refer to this function as CM().
  526.  
  527.    SEE ALSO
  528.     CoerceMethod(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  529.     ROM Kernel Manual boopsi section
  530.  
  531. amiga.lib/CreateExtIO                                   amiga.lib/CreateExtIO
  532.  
  533.    NAME
  534.     CreateExtIO -- create an IORequest structure
  535.  
  536.    SYNOPSIS
  537.     ioReq = CreateExtIO(port,ioSize);
  538.  
  539.     struct IORequest *CreateExtIO(struct MsgPort *, ULONG);
  540.  
  541.    FUNCTION
  542.     Allocates memory for and initializes a new IO request block
  543.     of a user-specified number of bytes. The number of bytes
  544.     MUST be the size of a legal IORequest (or extended IORequest)
  545.     or very nasty things will happen.
  546.  
  547.    INPUTS
  548.     port - an already initialized message port to be used for this IO
  549.            request's reply port. If this is NULL this function fails.
  550.     ioSize - the size of the IO request to be created.
  551.  
  552.    RESULT
  553.     ioReq - a new IO Request block, or NULL if there was not enough memory
  554.  
  555.    EXAMPLE
  556.     if (ioReq = CreateExtIO(CreatePort(NULL,0),sizeof(struct IOExtTD)))
  557.  
  558.    SEE ALSO
  559.     DeleteExtIO(), CreatePort(), exec.library/CreateMsgPort()
  560.  
  561. amiga.lib/CreatePort                                     amiga.lib/CreatePort
  562.  
  563.    NAME
  564.     CreatePort - Allocate and initialize a new message port
  565.  
  566.    SYNOPSIS
  567.     port = CreatePort(name,pri)
  568.  
  569.     struct MsgPort *CreatePort(STRPTR,LONG);
  570.  
  571.    FUNCTION
  572.     Allocates and initializes a new message port. The message list
  573.     of the new port will be prepared for use (via NewList).  A signal
  574.     bit will be allocated, and the port will be set to signal your
  575.     task when a message arrives (PA_SIGNAL).
  576.  
  577.     You *must* use DeletePort() to delete ports created with
  578.     CreatePort()!
  579.  
  580.    INPUTS
  581.     name - public name of the port, or NULL if the port is not named.
  582.            The name string is not copied. Most ports do not need names,
  583.            see notes below on this.
  584.     pri  - Priority used for insertion into the public port list,
  585.            normally 0.
  586.  
  587.    RESULT
  588.     port - a new MsgPort structure ready for use, or NULL if the port
  589.            could not be created due to not enough memory or no available
  590.            signal bit.
  591.  
  592.    NOTE
  593.     In most cases, ports should not be named. Named ports are used for
  594.     rendez-vous between tasks. Everytime a named port needs to be located,
  595.     the list of all named ports must be traversed. The more named
  596.     ports there are, the longer this list traversal takes. Thus, unless
  597.     you really need to, do not name your ports, which will keep them off
  598.     of the named port list and improve system performance.
  599.  
  600.    BUGS
  601.     With versions of amiga.lib prior to V37.14, this function would
  602.     not fail even though it couldn't allocate a signal bit. The port
  603.     would be returned with no signal allocated.
  604.  
  605.    SEE ALSO
  606.     DeletePort(), exec.library/FindPort(), <exec/ports.h>,
  607.     exec.library/CreateMsgPort()
  608.  
  609. amiga.lib/CreateStdIO                                   amiga.lib/CreateStdIO
  610.  
  611.    NAME
  612.     CreateStdIO -- create an IOStdReq structure
  613.  
  614.    SYNOPSIS
  615.     ioReq = CreateStdIO(port);
  616.  
  617.     struct IOStdReq *CreateStdIO(struct MsgPort *)
  618.  
  619.    FUNCTION
  620.     Allocates memory for and initializes a new IOStdReq structure.
  621.  
  622.    INPUTS
  623.     port - an already initialized message port to be used for this IO
  624.            request's reply port. If this is NULL this function fails.
  625.  
  626.    RESULT
  627.     ioReq - a new IOStdReq structure, or NULL if there was not enough
  628.         memory
  629.  
  630.    SEE ALSO
  631.     DeleteStdIO(), CreateExtIO(), exec.library/CreateIORequest()
  632.  
  633. amiga.lib/CreateTask                                     amiga.lib/CreateTask
  634.  
  635.    NAME
  636.     CreateTask -- Create task with given name, priority, stacksize
  637.  
  638.    SYNOPSIS
  639.     task = CreateTask(name,pri,initPC,stackSize)
  640.  
  641.     struct Task *CreateTask(STRPTR,LONG,funcEntry,ULONG);
  642.  
  643.    FUNCTION
  644.     This function simplifies program creation of sub-tasks by
  645.     dynamically allocating and initializing required structures
  646.     and stack space, and adding the task to Exec's task list
  647.     with the given name and priority. A tc_MemEntry list is provided
  648.     so that all stack and structure memory allocated by CreateTask()
  649.     is automatically deallocated when the task is removed.
  650.  
  651.     An Exec task may not call dos.library functions or any function
  652.     which might cause the loading of a disk-resident library, device,
  653.     or file (since such functions are indirectly calls to dos.library).
  654.     Only AmigaDOS Processes may call AmigaDOS; see the
  655.     dos.library/CreateProc() or the dos.library/CreateNewProc()
  656.     functions for more information.
  657.  
  658.     If other tasks or processes will need to find this task by name,
  659.     provide a complex and unique name to avoid conflicts.
  660.  
  661.     If your compiler provides automatic insertion of stack-checking
  662.     code, you may need to disable this feature when compiling sub-task
  663.     code since the stack for the subtask is at a dynamically allocated
  664.     location.  If your compiler requires 68000 registers to contain
  665.     particular values for base relative addressing, you may need to
  666.     save these registers from your main process, and restore them
  667.     in your initial subtask code.
  668.  
  669.     The function entry initPC is generally provided as follows:
  670.  
  671.     In C:
  672.     extern void functionName();
  673.     char *tname = "unique name";
  674.     task = CreateTask(tname, 0L, functionName, 4000L);
  675.  
  676.     In assembler:
  677.         PEA    startLabel
  678.  
  679.    INPUTS
  680.     name - a null-terminated name string
  681.     pri - an Exec task priority between -128 and 127, normally 0
  682.     funcEntry - the address of the first executable instruction
  683.             of the subtask code
  684.     stackSize - size in bytes of stack for the subtask. Don't cut it
  685.             too close - system function stack usage may change.
  686.  
  687.    RESULT
  688.     task - a pointer to the newly created task, or NULL if there was not
  689.            enough memory.
  690.  
  691.    BUGS
  692.     Under exec.library V37 or beyond, the AddTask() function used
  693.     internally by CreateTask() can fail whereas it couldn't fail in
  694.     previous versions of Exec. Prior to amiga.lib V37.14, this function
  695.     did not check for failure of AddTask() and thus might return a
  696.     pointer to a task structure even though the task was not actually
  697.     added to the system.
  698.  
  699.    SEE ALSO
  700.     DeleteTask(), exec/FindTask()
  701.  
  702. amiga.lib/CxCustom                                         amiga.lib/CxCustom
  703.  
  704.    NAME
  705.     CxCustom -- create a custom commodity object. (V36)
  706.  
  707.    SYNOPSIS
  708.     customObj = CxCustom(action,id);
  709.  
  710.     CxObj *CxCustom(LONG(*)(),LONG);
  711.  
  712.    FUNCTION
  713.     This function creates a custom commodity object. The action
  714.     of this object on receiving a commodity message is to call a
  715.     function of the application programmer's choice.
  716.  
  717.     The function provided ('action') will be passed a pointer to
  718.     the actual commodities message (in commodities private data
  719.     space), and will actually execute as part of the input handler
  720.     system task. Among other things, the value of 'id' can be
  721.     recovered from the message by using the function CxMsgID().
  722.  
  723.     The purpose of this function is two-fold. First, it allows
  724.     programmers to create Commodities Exchange objects with
  725.     functionality that was not imagined or chosen for inclusion
  726.     by the designers. Secondly, this is the only way to act
  727.     synchronously with Commodities.
  728.  
  729.     This function is a C-language macro for CreateCxObj(), defined
  730.     in <libraries/commodities.h>.
  731.  
  732.    INPUTS
  733.     action - a function to call whenever a message reaches the object
  734.     id - a message id to assign to the object
  735.  
  736.    RESULTS
  737.     customObj - a pointer to the new custom object, or NULL if it could
  738.             not be created.
  739.  
  740.   SEE ALSO
  741.     commodities.library/CreateCxObj(), commodities.library/CxMsgID()
  742.  
  743. amiga.lib/CxDebug                                           amiga.lib/CxDebug
  744.  
  745.    NAME
  746.     CxDebug -- create a commodity debug object. (V36)
  747.  
  748.    SYNOPSIS
  749.     debugObj = CxDebug(id);
  750.  
  751.     CxObj *CxDebug(LONG);
  752.  
  753.    FUNCTION
  754.     This function creates a Commodities debug object. The action of this
  755.     object on receiving a Commodities message is to print out information
  756.     about the Commodities message through the serial port (using the
  757.     kprintf() routine). The value of 'id' will also be displayed.
  758.  
  759.     Note that this is a synchronous occurence (the printing is done by
  760.     the input device task). If screen or file output is desired, using a
  761.     sender object instead of a debug object is necessary, since such
  762.     output is best done by your application process.
  763.  
  764.     This function is a C-language macro for CreateCxObj(), defined
  765.     in <libraries/commodities.h>.
  766.  
  767.    INPUTS
  768.     id - the id to assign to the debug object, this value is output
  769.          whenever the debug object sends data to the serial port.
  770.  
  771.    RESULTS
  772.     debugObj - a pointer to the debug object, or NULL if it could
  773.            not be created.
  774.  
  775.    SEE ALSO
  776.     commodities.library/CreateCxObj(), CxSender(), debug.lib/kprintf()
  777.  
  778. amiga.lib/CxFilter                                         amiga.lib/CxFilter
  779.  
  780.    NAME
  781.     CxFilter -- create a commodity filter object. (V36)
  782.  
  783.    SYNOPSIS
  784.     filterObj = CxFilter(description);
  785.  
  786.     CxObj *CxFilter(STRPTR)
  787.  
  788.    FUNCTION
  789.     Creates an input event filter object that matches the
  790.     'description' string. If 'description' is NULL, the filter will not
  791.     match any messages.
  792.  
  793.     A filter may be modified by the functions SetFilter(), using
  794.     a description string, and SetFilterIX(), which takes a
  795.     binary Input Expression as a parameter.
  796.  
  797.     This function is a C-language macro for CreateCxObj(), defined
  798.     in <libraries/commodities.h>.
  799.  
  800.    INPUTS
  801.     description - the description string in the same format as strings
  802.               expected by commodities.library/SetFilter()
  803.  
  804.    RESULTS
  805.     filterObj - a pointer to the filter object, or NULL if there
  806.             was not enough memory. If there is a problem in the
  807.             description string, the internal error code of the filter
  808.             object will be set to so indicate. This error code may be
  809.             interrogated using the function CxObjError().
  810.  
  811.    SEE ALSO
  812.     commodities.library/CreateCxObj(), commodities.library/SetFilter(),
  813.     commodities.library/SetFilterIX(), commodities.library/CxObjError()
  814.  
  815. amiga.lib/CxSender                                         amiga.lib/CxSender
  816.  
  817.    NAME
  818.     CxSender -- create a commodity sender object. (V36)
  819.  
  820.    SYNOPSIS
  821.     senderObj = CxSender(port,id)
  822.  
  823.     CxObj *CxSender(struct MsgPort *,LONG);
  824.  
  825.    FUNCTION
  826.     This function creates a Commodities sender object. The action
  827.     of this object on receiving a Commodities message is to copy the
  828.     Commodities message into a standard Exec Message, to put the value
  829.     'id' in the message as well, and to send the message off to the
  830.     message port 'port'.
  831.  
  832.     The value 'id' is used so that an application can monitor
  833.     messages from several senders at a single port. It can be retrieved
  834.     from the Exec message by using the function CxMsgID(). The value can
  835.     be a simple integer ID, or a pointer to some application data
  836.     structure.
  837.  
  838.     Note that Exec messages sent by sender objects arrive
  839.     asynchronously at the destination port. Do not assume anything about
  840.     the status of the Commodities message which was copied into the Exec
  841.     message you received.
  842.  
  843.     All Exec messages sent to your ports must be replied. Messages may be
  844.     replied after the sender object has been deleted.
  845.  
  846.     This function is a C-language macro for CreateCxObj(), defined
  847.     in <libraries/commodities.h>.
  848.  
  849.    INPUTS
  850.     port - the port for the sender to send messages to
  851.     id - the id of the messages sent by the sender
  852.  
  853.    RESULTS
  854.     semderObj - a pointer to the sender object, or NULL if it could
  855.             not be created.
  856.  
  857.    SEE ALSO
  858.     commodities.library/CreateCxObj(), commodities.library/CxMsgID(),
  859.     exec.library/PutMsg(), exec.library/ReplyMsg()
  860.  
  861. amiga.lib/CxSignal                                         amiga.lib/CxSignal
  862.  
  863.    NAME
  864.     CxSignal -- create a commodity signaller object. (V36)
  865.  
  866.    SYNOPSIS
  867.     signalerObj = CxSignal(task,signal);
  868.  
  869.     CxObj *CxSignal(struct Task *,LONG);
  870.  
  871.    FUNCTION
  872.     This function creates a Commodities signal object. The action
  873.     of this object on receiving a Commodities message is to
  874.     send the 'signal' to the 'task'. The caller is responsible
  875.     for allocating the signal and determining the proper task ID.
  876.  
  877.     Note that 'signal' is the signal value as returned by AllocSignal(),
  878.     not the mask made from that value.
  879.  
  880.     This function is a C-language macro for CreateCxObj(), defined
  881.     in <libraries/commodities.h>.
  882.  
  883.    INPUTS
  884.     task - the task for the signaller to signal
  885.     signal - the signal bit number for the signaller to send
  886.  
  887.    RESULTS
  888.     signallerObj - a pointer to the signaller object, or NULL if it could
  889.                not be created.
  890.  
  891.    SEE ALSO
  892.     commodities.library/CreateCxObj(), exec.library/FindTask()
  893.     exec.library/Signal(), exec.library/AllocSignal(),
  894.  
  895. amiga.lib/CxTranslate                                   amiga.lib/CxTranslate
  896.  
  897.    NAME
  898.     CxTranslate -- create a commodity translator object. (V36)
  899.  
  900.    SYNOPSIS
  901.     translatorObj = CxTranslate(ie);
  902.  
  903.     CxObj *CxTranslate(struct InputEvent *);
  904.  
  905.    FUNCTION
  906.     This function creates a Commodities 'translator' object.
  907.     The action of this object on receiving a Commodities message is to
  908.     replace that message in the commodities network with a chain of
  909.     Commodities input messages.
  910.  
  911.     There is one new Commodities input message generated for each input
  912.     event in the linked list starting at 'ie' (and NULL terminated). The
  913.     routing information of the new input messages is copied from the input
  914.     message they replace.
  915.  
  916.     The linked list of input events associated with a translator object
  917.     can be changed using the SetTranslate() function.
  918.  
  919.     If 'ie' is NULL, the null translation occurs: that is, the original
  920.     commodities input message is disposed, and no others are created to
  921.     take its place.
  922.  
  923.     This function is a C-language macro for CreateCxObj(), defined
  924.     in <libraries/commodities.h>.
  925.  
  926.    INPUTS
  927.     ie - the input event list used as replacement by the translator
  928.  
  929.    RESULTS
  930.     translatorObj - a pointer to the translator object, or NULL if it could
  931.                 not be created.
  932.  
  933.    SEE ALSO
  934.     commodities.library/CreateCxObj(), commodities.library/SetTranslate()
  935.  
  936. amiga.lib/dbf                                                   amiga.lib/dbf
  937.  
  938.    NAME
  939.     dbf - convert FFP dual-binary number to FFP format
  940.  
  941.    SYNOPSIS
  942.     fnum = dbf(exp, mant);
  943.  
  944.    FUNCTION
  945.     Accepts a dual-binary format (described below) floating point
  946.     number and converts it to an FFP format floating point number.
  947.     The dual-binary format is defined as:
  948.  
  949.         exp bit  16    = sign (0=>positive, 1=>negative)
  950.         exp bits 15-0    = binary integer representing the base
  951.                       ten (10) exponent
  952.         man        = binary integer mantissa
  953.  
  954.    INPUTS
  955.     exp - binary integer representing sign and exponent
  956.     mant - binary integer representing the mantissa
  957.  
  958.    RESULT
  959.     fnum - converted FFP floating point format number
  960.  
  961.    BUGS
  962.     None
  963. amiga.lib/DeleteExtIO                                   amiga.lib/DeleteExtIO
  964.  
  965.    NAME
  966.     DeleteExtIO - return memory allocated for extended IO request
  967.  
  968.    SYNOPSIS
  969.     DeleteExtIO(ioReq);
  970.  
  971.     VOID DeleteExtIO(struct IORequest *);
  972.  
  973.    FUNCTION
  974.     Frees up an IO request as allocated by CreateExtIO().
  975.  
  976.    INPUTS
  977.     ioReq - the IORequest block to be freed, or NULL.
  978.  
  979.    SEE ALSO
  980.     CreateExtIO()
  981.  
  982. amiga.lib/DeletePort                                     amiga.lib/DeletePort
  983.  
  984.    NAME
  985.     DeletePort - free a message port created by CreatePort()
  986.  
  987.    SYNOPSIS
  988.     DeletePort(port)
  989.  
  990.     VOID DeletePort(struct MsgPort *);
  991.  
  992.    FUNCTION
  993.     Frees a message port created by CreatePort. All messages that
  994.     may have been attached to this port must have already been
  995.     replied before this function is called.
  996.  
  997.    INPUTS
  998.     port - message port to delete
  999.  
  1000.    SEE ALSO
  1001.     CreatePort()
  1002.  
  1003. amiga.lib/DeleteStdIO                                   amiga.lib/DeleteStdIO
  1004.  
  1005.    NAME
  1006.     DeleteStdIO - return memory allocated for IOStdReq
  1007.  
  1008.    SYNOPSIS
  1009.     DeleteStdIO(ioReq);
  1010.  
  1011.     VOID DeleteStdIO(struct IOStdReq *);
  1012.  
  1013.    FUNCTION
  1014.     Frees up an IOStdReq as allocated by CreateStdIO().
  1015.  
  1016.    INPUTS
  1017.     ioReq - the IORequest block to be freed, or NULL.
  1018.  
  1019.    SEE ALSO
  1020.     CreateStdIO(), DeleteExtIO(), exec.library/CreateIORequest()
  1021.  
  1022. amiga.lib/DeleteTask                                     amiga.lib/DeleteTask
  1023.  
  1024.    NAME
  1025.     DeleteTask -- delete a task created with CreateTask()
  1026.  
  1027.    SYNOPSIS
  1028.     DeleteTask(task)
  1029.  
  1030.     VOID DeleteTask(struct Task *);
  1031.  
  1032.    FUNCTION
  1033.     This function simply calls exec.library/RemTask(), deleting a task
  1034.     from the Exec task lists and automatically freeing any stack and
  1035.     structure memory allocated for it by CreateTask().
  1036.  
  1037.     Before deleting a task, you must first make sure that the task is
  1038.     not currently executing any system code which might try to signal
  1039.     the task after it is gone.
  1040.  
  1041.     This can be accomplished by stopping all sources that might reference
  1042.     the doomed task, then causing the subtask to execute a Wait(0L).
  1043.     Another option is to have the task call DeleteTask()/RemTask() on
  1044.     itself.
  1045.  
  1046.    INPUTS
  1047.     task - task to remove from the system
  1048.  
  1049.    NOTE
  1050.     This function simply calls exec.library/RemTask(), so you can call
  1051.     RemTask() directly instead of calling this function.
  1052.  
  1053.    SEE ALSO
  1054.     CreateTask(), exec.library/RemTask()
  1055.  
  1056. amiga.lib/DoMethod                                         amiga.lib/DoMethod
  1057.  
  1058.    NAME
  1059.     DoMethod -- Perform method on object.  (V36)
  1060.  
  1061.    SYNOPSIS
  1062.     result = DoMethod( obj, MethodID, ... )
  1063.  
  1064.     ULONG DoMethod( Object *, ULONG, ... );
  1065.  
  1066.    FUNCTION
  1067.     Boopsi support function that invokes the supplied message
  1068.     on the specified object.  The message is invoked on the
  1069.     object's true class.  Equivalent to DoMethodA(), but allows
  1070.     you to build the message on the stack.
  1071.  
  1072.    INPUTS
  1073.     obj - pointer to boopsi object
  1074.     MethodID - which method to send (see <intuition/classusr.h>)
  1075.     ... - method-specific message built on the stack
  1076.  
  1077.    RESULT
  1078.     result - specific to the message and the object's class.
  1079.  
  1080.    NOTES
  1081.     While this function requires V36 or higher intuition.library,
  1082.     it first appeared in V37 amiga.lib.
  1083.  
  1084.    SEE ALSO
  1085.     DoMethodA(), CoerceMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  1086.     ROM Kernel Manual boopsi section
  1087.  
  1088. amiga.lib/DoMethodA                                       amiga.lib/DoMethodA
  1089.  
  1090.    NAME
  1091.     DoMethodA -- Perform method on object.  (V36)
  1092.  
  1093.    SYNOPSIS
  1094.     result = DoMethodA( obj, msg )
  1095.  
  1096.     ULONG DoMethodA( Object *, Msg * );
  1097.  
  1098.    FUNCTION
  1099.     Boopsi support function that invokes the supplied message
  1100.     on the specified object.  The message is invoked on the
  1101.     object's true class.
  1102.  
  1103.    INPUTS
  1104.     obj - pointer to boopsi object
  1105.     msg - pointer to method-specific message to send
  1106.  
  1107.    RESULT
  1108.     result - specific to the message and the object's class.
  1109.  
  1110.    NOTES
  1111.     While this function requires V36 or higher intuition.library,
  1112.     it first appeared in V37 amiga.lib.
  1113.     Some early example code may refer to this function as DM().
  1114.  
  1115.    SEE ALSO
  1116.     DoMethod(), CoerceMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  1117.     ROM Kernel Manual boopsi section
  1118.  
  1119. amiga.lib/DoSuperMethod                               amiga.lib/DoSuperMethod
  1120.  
  1121.    NAME
  1122.     DoSuperMethod -- Perform method on object coerced to superclass. (V36)
  1123.  
  1124.    SYNOPSIS
  1125.     result = DoSuperMethod( cl, obj, MethodID, ... )
  1126.  
  1127.     ULONG DoSuperMethod( struct IClass *, Object *, ULONG, ... );
  1128.  
  1129.    FUNCTION
  1130.     Boopsi support function that invokes the supplied message
  1131.     on the specified object, as though it were the superclass
  1132.     of the specified class.  Equivalent to DoSuperMethodA(),
  1133.     but allows you to build the message on the stack.
  1134.  
  1135.    INPUTS
  1136.     cl - pointer to boopsi class whose superclass is to
  1137.         receive the message
  1138.     obj - pointer to boopsi object
  1139.     ... - method-specific message built on the stack
  1140.  
  1141.    RESULT
  1142.     result - class and message-specific result.
  1143.  
  1144.    NOTES
  1145.     While this function requires V36 or higher intuition.library,
  1146.     it first appeared in V37 amiga.lib.
  1147.  
  1148.    SEE ALSO
  1149.     CoerceMethodA(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  1150.     ROM Kernel Manual boopsi section
  1151.  
  1152. amiga.lib/DoSuperMethodA                             amiga.lib/DoSuperMethodA
  1153.  
  1154.    NAME
  1155.     DoSuperMethodA -- Perform method on object coerced to superclass. (V36)
  1156.  
  1157.    SYNOPSIS
  1158.     result = DoSuperMethodA( cl, obj, msg )
  1159.  
  1160.     ULONG DoSuperMethodA( struct IClass *, Object *, Msg * );
  1161.  
  1162.    FUNCTION
  1163.     Boopsi support function that invokes the supplied message
  1164.     on the specified object, as though it were the superclass
  1165.     of the specified class.
  1166.  
  1167.    INPUTS
  1168.     cl - pointer to boopsi class whose superclass is to
  1169.         receive the message
  1170.     obj - pointer to boopsi object
  1171.     msg - pointer to method-specific message to send
  1172.  
  1173.    RESULT
  1174.     result - class and message-specific result.
  1175.  
  1176.    NOTES
  1177.     While this function requires V36 or higher intuition.library,
  1178.     it first appeared in V37 amiga.lib.
  1179.     Some early example code may refer to this function as DSM().
  1180.  
  1181.    SEE ALSO
  1182.     CoerceMethodA(), DoMethodA(), DoSuperMethod(), <intuition/classusr.h>
  1183.     ROM Kernel Manual boopsi section
  1184.  
  1185. amiga.lib/FastRand                                         amiga.lib/FastRand
  1186.  
  1187.    NAME
  1188.     FastRand - quickly generate a somewhat random integer
  1189.  
  1190.    SYNOPSIS
  1191.     number = FastRand(seed);
  1192.  
  1193.     ULONG FastRand(ULONG);
  1194.  
  1195.    FUNCTION
  1196.     Seed value is taken from stack, shifted left one position,
  1197.     exclusive-or'ed with hex value $1D872B41 and returned.
  1198.  
  1199.    INPUTS
  1200.     seed - a 32-bit integer
  1201.  
  1202.    RESULT
  1203.     number - new random seed, a 32-bit value
  1204.  
  1205.    SEE ALSO
  1206.     RangeRand()
  1207.  
  1208. amiga.lib/fpa                                                   amiga.lib/fpa
  1209.  
  1210.    NAME
  1211.     fpa - convert fast floating point into ASCII string equivalent
  1212.  
  1213.    SYNOPSIS
  1214.     exp = fpa(fnum, &string[0]);
  1215.  
  1216.    FUNCTION
  1217.     Accepts an FFP number and the address of the ASCII string where it's
  1218.     onverted output is to be stored.  The number is converted to a NULL
  1219.     terminated ASCII string in and stored at the address provided.
  1220.     Additionally, the base ten (10) exponent in binary form is returned.
  1221.  
  1222.    INPUTS
  1223.     fnum       - Motorola Fast Floating Point number
  1224.     &string[0] - address for output of converted ASCII character string
  1225.              (16 bytes)
  1226.  
  1227.    RESULT
  1228.     &string[0] - converted ASCII character string
  1229.     exp       - integer exponent value in binary form
  1230.  
  1231.    BUGS
  1232.     None
  1233. amiga.lib/FreeIEvents                                   amiga.lib/FreeIEvents
  1234.  
  1235.    NAME
  1236.     FreeIEvents -- free a chain of input events allocated by
  1237.                InvertString(). (V36)
  1238.  
  1239.    SYNOPSIS
  1240.     FreeIEvents(events)
  1241.  
  1242.     VOID FreeIEvents(struct InputEvent *);
  1243.  
  1244.    FUNCTION
  1245.     This function frees a linked list of input events as obtained from
  1246.     InvertString().
  1247.  
  1248.    INPUTS
  1249.        events - the list of input events to free, may be NULL.
  1250.  
  1251.    SEE ALSO
  1252.     InvertString()
  1253.  
  1254. amiga.lib/GetRexxVar                                     amiga.lib/GetRexxVar
  1255.  
  1256.    NAME
  1257.     GetRexxVar - Gets the value of a variable from a running ARexx program
  1258.  
  1259.    SYNOPSIS
  1260.     error = GetRexxVar(message,varname,bufpointer)
  1261.     D0,A1              A0      A1      (C-only)
  1262.  
  1263.     LONG GetRexxVar(struct RexxMsg *,char *,char **);
  1264.  
  1265.    FUNCTION
  1266.     This function will attempt to extract the value of the symbol
  1267.     varname from the ARexx script that sent the message.  When called
  1268.     from C, a pointer to the extracted value will be placed in the
  1269.     pointer pointed to by bufpointer.  (*bufpointer will be the pointer
  1270.     to the value)
  1271.  
  1272.     When called from assembly, the pointer will be returned in A1.
  1273.  
  1274.     The value string returned *MUST* *NOT* be modified.
  1275.  
  1276.     While this function is new in the V37 amiga.lib, it is safe to
  1277.     call it in all versions of the operating system.  It is also
  1278.     PURE code, thus usable in resident/pure executables.
  1279.  
  1280.    NOTE
  1281.     This is a stub in amiga.lib.  It is only available via amiga.lib.
  1282.     The stub has two labels.  One, _GetRexxVar, takes the arguments
  1283.     from the stack.  The other, GetRexxVar, takes the arguments in
  1284.     registers.
  1285.  
  1286.     This routine does a CheckRexxMsg() on the message.
  1287.  
  1288.    EXAMPLE
  1289.  
  1290.     char    *value;
  1291.  
  1292.     /* Message is one from ARexx */
  1293.     if (!GetRexxVar(rxmsg,"TheVar",&value))
  1294.     {
  1295.         /* The value was gotten and now is pointed to by value */
  1296.         printf("Value of TheVar is %s\n",value);
  1297.     }
  1298.  
  1299.    INPUTS
  1300.     message        A message gotten from an ARexx script
  1301.     varname        The name of the variable to extract
  1302.     bufpointer    (For C only) A pointer to a string pointer.
  1303.  
  1304.    RESULTS
  1305.     error        0 for success, otherwise an error code.
  1306.             (Other codes may exists, these are documented)
  1307.             3  == Insufficient Storage
  1308.             9  == String too long
  1309.             10 == invalid message
  1310.  
  1311.     A1        (Assembly only)  Pointer to the string.
  1312.  
  1313.    SEE ALSO
  1314.     SetRexxVar(), CheckRexxMsg()
  1315.  
  1316. amiga.lib/HookEntry                                       amiga.lib/HookEntry
  1317.  
  1318.    NAME
  1319.     HookEntry -- Assembler to HLL conversion stub for hook entry.  (V36)
  1320.  
  1321.    SYNOPSIS
  1322.     result = HookEntry( struct Hook *, Object *, APTR )
  1323.     D0                  A0             A2        A1
  1324.  
  1325.    FUNCTION
  1326.     By definition, a standard hook entry-point must receive the
  1327.     hook in A0, the object in A2, and the message in A1.  If your
  1328.     hook entry-point is written in a high-level language and is
  1329.     expecting its parameters on the stack, then HookEntry() will
  1330.     put the three parameters on the stack and invoke the function
  1331.     stored in the hook h_SubEntry field.
  1332.  
  1333.     This function is only useful to hook implementers, and is
  1334.     never called from C.
  1335.  
  1336.    INPUTS
  1337.     hook - pointer to hook being invoked
  1338.     object - pointer to hook-specific data
  1339.     msg - pointer to hook-specific message
  1340.  
  1341.    RESULT
  1342.     result - a hook-specific result.
  1343.  
  1344.    NOTES
  1345.     While this function requires V36 or higher intuition.library,
  1346.     it first appeared in V37 amiga.lib.
  1347.  
  1348.    EXAMPLE
  1349.     If your hook dispatcher is this:
  1350.  
  1351.     dispatch( struct Hook *hookPtr, Object *obj, APTR msg )
  1352.     {
  1353.         ...
  1354.     }
  1355.  
  1356.     Then when you initialize your hook, you would say:
  1357.  
  1358.     myhook.h_Entry = HookEntry;    /* amiga.lib stub */
  1359.     myhook.h_SubEntry = dispatch;    /* HLL entry */
  1360.  
  1361.    SEE ALSO
  1362.     CallHook(), CallHookA(), <utility/hooks.h>
  1363.     
  1364. amiga.lib/HotKey                                             amiga.lib/HotKey
  1365.  
  1366.    NAME
  1367.     HotKey -- create a commodity triad. (V36)
  1368.  
  1369.    SYNOPSIS
  1370.     filterObj = Hotkey(description,port,id);
  1371.  
  1372.     CxObj *HotKey(STRPTR,struct MsgPort *,LONG);
  1373.  
  1374.    FUNCTION
  1375.     This function creates a triad of commodity objects to accomplish a
  1376.     high-level function.
  1377.  
  1378.     The three objects are a filter, which is created to match by the call
  1379.     CxFilter(description), a sender created by the call CxSender(port,id),
  1380.     and a translator which is created by CxTranslate(NULL), so that it
  1381.     swallows any commodity input event messages that are passed down by
  1382.     the filter.
  1383.  
  1384.     This is the simple way to get a message sent to your program when the
  1385.     user performs a particular input action.
  1386.  
  1387.     It is strongly recommended that the ToolTypes environment be used to
  1388.     allow the user to specify the input descriptions for your application's
  1389.     hotkeys.
  1390.  
  1391.    INPUTS
  1392.     description - the description string to use for the filter in the same
  1393.               format as accepted by commodities.library/SetFilter()
  1394.     port - port for the sender to send messages to.
  1395.     id - id of the messages sent by the sender
  1396.  
  1397.    RESULTS
  1398.     filterObj - a pointer to a filter object, or NULL if it could
  1399.             not be created.
  1400.  
  1401.    SEE ALSO
  1402.     CxFilter(), CxSender(), CxTranslate(),
  1403.     commodities.library/CxObjError(), commodities.library/SetFilter()
  1404.  
  1405. amiga.lib/InvertString                                 amiga.lib/InvertString
  1406.  
  1407.    NAME
  1408.     InvertString -- produce input events that would generate the
  1409.             given string. (V36)
  1410.  
  1411.    SYNOPSIS
  1412.     events = InvertString(str,km)
  1413.  
  1414.     struct InputEvent *InvertString(STRPTR,struct KeyMap *);
  1415.  
  1416.    FUNCTION
  1417.     This function returns a linked list of input events which would
  1418.     translate into the string using the supplied keymap (or the system
  1419.     default keymap if 'km' is NULL).
  1420.  
  1421.     'str' is null-terminated and may contain:
  1422.        - ANSI character codes
  1423.        - backslash escaped characters:
  1424.         \n   -   CR
  1425.         \r   -   CR
  1426.         \t   -   TAB
  1427.         \0   -   illegal, do not use!
  1428.         \\   -   backslash
  1429.        - a text description of an input event as used by ParseIX(),
  1430.          enclosed in angle brackets.
  1431.  
  1432.     An example is:
  1433.           abc<alt f1>\nhi there.
  1434.  
  1435.    INPUTS
  1436.     str - null-terminated string to convert to input events
  1437.     km - keymap to use for the conversion, or NULL to use the default
  1438.          keymap.
  1439.  
  1440.    RESULTS
  1441.     events - a chain of input events, or NULL if there was a problem. The
  1442.          most likely cause of failure is an illegal description
  1443.          enclosed in angled brackets.
  1444.  
  1445.          This chain should eventually be freed using FreeIEvents().
  1446.  
  1447.    SEE ALSO
  1448.     commodities.library/ParseIX(), FreeIEvents()
  1449.  
  1450. amiga.lib/NewList                                           amiga.lib/NewList
  1451.  
  1452.    NAME
  1453.     NewList -- prepare a list structure for use
  1454.  
  1455.    SYNOPSIS
  1456.     NewList(list)
  1457.  
  1458.     VOID NewList(struct List *);
  1459.     VOID NewList(struct MinList *);
  1460.  
  1461.    FUNCTION
  1462.     Perform the magic needed to prepare a List header structure for
  1463.     use; the list will be empty and ready to use.  (If the list is the
  1464.     full featured type, you may need to initialize lh_Type afterwards)
  1465.  
  1466.     Assembly programmers may want to use the NEWLIST macro instead.
  1467.  
  1468.    INPUTS
  1469.     list - pointer to a List or MinList.
  1470.  
  1471.    SEE ALSO
  1472.     <exec/lists.h>
  1473.  
  1474. amiga.lib/printf                                             amiga.lib/printf
  1475.  
  1476.    NAME
  1477.     printf - print a formatted output line to the standard output.
  1478.  
  1479.    SYNOPSIS
  1480.     printf(formatstring [,value [,values] ] );
  1481.  
  1482.    FUNCTION
  1483.     Format the output in accordance with specifications in the format
  1484.     string.
  1485.  
  1486.    INPUTS
  1487.     formatString - a C-language-like NULL-terminated format string,
  1488.                with the following supported % options:
  1489.  
  1490.       %[flags][width][.limit][length]type
  1491.  
  1492.         $     - must follow the arg_pos value, if specified
  1493.       flags   - only one allowed. '-' specifies left justification.
  1494.       width   - field width. If the first character is a '0', the
  1495.                 field is padded with leading 0s.
  1496.         .     - must precede the field width value, if specified
  1497.       limit   - maximum number of characters to output from a string.
  1498.                 (only valid for %s or %b).
  1499.       length  - size of input data defaults to word (16-bit) for types c,
  1500.             d, u and x, 'l' changes this to long (32-bit).
  1501.       type    - supported types are:
  1502.                       b - BSTR, data is 32-bit BPTR to byte count followed
  1503.                           by a byte string. A NULL BPTR is treated as an
  1504.                   empty string. (V36)
  1505.                       d - signed decimal
  1506.               u - unsigned decimal
  1507.                       x - hexadecimal with hex digits in uppercase
  1508.               X - hexadecimal with hex digits in lowercase
  1509.                       s - string, a 32-bit pointer to a NULL-terminated
  1510.                           byte string. A NULL pointer is treated
  1511.                           as an empty string.
  1512.                       c - character
  1513.  
  1514.     value(s) - numeric variables or addresses of null-terminated strings
  1515.                to be added to the format information.
  1516.  
  1517.    NOTE
  1518.     The global "_stdout" must be defined, and contain a pointer to
  1519.     a legal AmigaDOS file handle. Using the standard Amiga startup
  1520.     module sets this up. In other cases you will need to define
  1521.     stdout, and assign it to some reasonable value (like what the
  1522.     dos.library/Output() call returns). This code would set it up:
  1523.  
  1524.         ULONG stdout;
  1525.         stdout=Output();
  1526.  
  1527.    BUGS
  1528.     This function will crash if the resulting stream after
  1529.     parameter substitution is longer than 140 bytes.
  1530.  
  1531. amiga.lib/RangeRand                                       amiga.lib/RangeRand
  1532.  
  1533.    NAME
  1534.     RangeRand - generate a random number within a specific integer range
  1535.  
  1536.    SYNOPSIS
  1537.     number = RangeRand(maxValue);
  1538.  
  1539.     UWORD RangeRand(UWORD);
  1540.  
  1541.    FUNCTION
  1542.     RangeRand() accepts a value from 0 to 65535, and returns a value
  1543.     within that range.
  1544.  
  1545.     maxValue is passed on stack as a 32-bit integer but used as though
  1546.     it is only a 16-bit integer. Variable named RangeSeed is available
  1547.     beginning with V33 that contains the global seed value passed from
  1548.     call to call and thus can be changed in a program by declaring:
  1549.  
  1550.       extern ULONG RangeSeed;
  1551.  
  1552.    INPUTS
  1553.     maxValue - the returned random number will be in the range
  1554.                [0..maxValue-1]
  1555.  
  1556.    RESULT
  1557.     number - pseudo random number in the range of [0..maxValue-1].
  1558.  
  1559.    SEE ALSO
  1560.     FastRand()
  1561.  
  1562. amiga.lib/RemTOF                                             amiga.lib/RemTOF
  1563.  
  1564.    NAME
  1565.     RemTOF - remove a task from the VBlank interrupt server chain.
  1566.  
  1567.    SYNOPSIS
  1568.     RemTOF(i);
  1569.  
  1570.     VOID RemTOF(struct Isrvstr *);
  1571.  
  1572.    FUNCTION
  1573.     Removes a task from the vertical-blanking interval interrupt server
  1574.     chain.
  1575.  
  1576.    INPUTS
  1577.     i - pointer to an Isrvstr structure
  1578.  
  1579.    SEE ALSO
  1580.     AddTOF(), <graphics/graphint.h>
  1581.  
  1582. amiga.lib/SetRexxVar                                     amiga.lib/SetRexxVar
  1583.  
  1584.    NAME
  1585.     SetRexxVar - Sets the value of a variable of a running ARexx program
  1586.  
  1587.    SYNOPSIS
  1588.     error = SetRexxVar(message,varname,value,length)
  1589.     D0                 A0      A1      D0    D1
  1590.  
  1591.     LONG SetRexxVar(struct RexxMsg *,char *,char *,ULONG);
  1592.  
  1593.    FUNCTION
  1594.     This function will attempt to the the value of the symbol
  1595.     varname in the ARexx script that sent the message.
  1596.  
  1597.     While this function is new in the V37 amiga.lib, it is safe to
  1598.     call it in all versions of the operating system.  It is also
  1599.     PURE code, thus usable in resident/pure executables.
  1600.  
  1601.    NOTE
  1602.     This is a stub in amiga.lib.  It is only available via amiga.lib.
  1603.     The stub has two labels.  One, _SetRexxVar, takes the arguments
  1604.     from the stack.  The other, SetRexxVar, takes the arguments in
  1605.     registers.
  1606.  
  1607.     This routine does a CheckRexxMsg() on the message.
  1608.  
  1609.    EXAMPLE
  1610.  
  1611.     char    *value;
  1612.  
  1613.     /* Message is one from ARexx */
  1614.     if (!SetRexxVar(rxmsg,"TheVar","25 Dollars",10))
  1615.     {
  1616.         /* The value of TheVar will now be "25 Dollars" */
  1617.     }
  1618.  
  1619.    INPUTS
  1620.     message        A message gotten from an ARexx script
  1621.     varname        The name of the variable to set
  1622.     value        A string that will be the new value of the variable
  1623.     length        The length of the value string
  1624.  
  1625.  
  1626.    RESULTS
  1627.     error        0 for success, otherwise an error code.
  1628.             (Other codes may exists, these are documented)
  1629.             3  == Insufficient Storage
  1630.             9  == String too long
  1631.             10 == invalid message
  1632.  
  1633.    SEE ALSO
  1634.     SetRexxVar(), CheckRexxMsg()
  1635.  
  1636. amiga.lib/SetSuperAttrs                               amiga.lib/SetSuperAttrs
  1637.  
  1638.    NAME
  1639.     SetSuperAttrs -- Invoke OM_SET method on superclass with varargs. (V36)
  1640.  
  1641.    SYNOPSIS
  1642.     result = SetSuperAttrs( cl, obj, tag, ... )
  1643.  
  1644.     ULONG SetSuperAttrs( struct IClass *, Object *, ULONG, ... );
  1645.  
  1646.    FUNCTION
  1647.     Boopsi support function which invokes the OM_SET method on the
  1648.     superclass of the supplied class for the supplied object.  Allows
  1649.     the ops_AttrList to be supplied on the stack (i.e. in a varargs
  1650.     way).  The equivalent non-varargs function would simply be
  1651.  
  1652.         DoSuperMethod( cl, obj, OM_SET, taglist, NULL );
  1653.  
  1654.    INPUTS
  1655.     cl - pointer to boopsi class whose superclass is to
  1656.         receive the OM_SET message
  1657.     obj - pointer to boopsi object
  1658.     tag - list of tag-attribute pairs, ending in TAG_DONE
  1659.  
  1660.    RESULT
  1661.     result - class and message-specific result.
  1662.  
  1663.    NOTES
  1664.     While this function requires V36 or higher intuition.library,
  1665.     it first appeared in V37 amiga.lib.
  1666.  
  1667.    SEE ALSO
  1668.     CoerceMethodA(), DoMethodA(), DoSuperMethodA(), <intuition/classusr.h>
  1669.     ROM Kernel Manual boopsi section
  1670.  
  1671. amiga.lib/sprintf                                           amiga.lib/sprintf
  1672.  
  1673.    NAME
  1674.     sprintf - format a C-like string into a string buffer.
  1675.  
  1676.    SYNOPSIS
  1677.     sprintf(destination formatstring [,value [, values] ] );
  1678.  
  1679.    FUNCTION
  1680.     Performs string formatting identical to printf, but directs the output
  1681.     into a specific destination in memory. This uses the ROM version
  1682.     of printf (exec.library/RawDoFmt()), so it is very small.
  1683.  
  1684.     Assembly programmers can call this by placing values on the
  1685.     stack, followed by a pointer to the formatstring, followed
  1686.     by a pointer to the destination string.
  1687.  
  1688.    INPUTS
  1689.     destination - the address of an area in memory into which the
  1690.               formatted output is to be placed.
  1691.     formatstring - pointer to a null terminated string describing the
  1692.                    desired output formatting (see printf() for a
  1693.                description of this string).
  1694.     value(s) - numeric information to be formatted into the output
  1695.            stream.
  1696.  
  1697.    SEE ALSO
  1698.      printf(), exec.library/RawDoFmt()
  1699.  
  1700. amiga.lib/stdio                                               amiga.lib/stdio
  1701.  
  1702.    NAMES
  1703.     fclose    - close a file
  1704.     fgetc    - get a character from a file
  1705.     fprintf    - format data to file (see printf())
  1706.     fputc    - put character to file
  1707.     fputs    - write string to file
  1708.     getchar    - get a character from stdin
  1709.     printf    - put format data to stdout (see exec.library/RawDoFmt)
  1710.     putchar    - put character to stdout
  1711.     puts    - put string to stdout, followed by newline
  1712.  
  1713.    FUNCTION
  1714.     These functions work much like the standard C functions of the same
  1715.     names. The file I/O functions all use non-buffered AmigaDOS
  1716.     files, and must not be mixed with the file I/O of any C
  1717.     compiler. The names of these functions match those found in many
  1718.     standard C libraries, when a name conflict occurs, the function is
  1719.     generally taken from the FIRST library that was specified on the
  1720.     linker's command line.  Thus to use these functions, specify
  1721.     the amiga.lib library first.
  1722.  
  1723.     To get a suitable AmigaDOS FileHandle, the dos.library/Open() or
  1724.     dos.library/Output() functions must be used.
  1725.  
  1726.     All of the functions that write to stdout expect an appropriate
  1727.     FileHandle to have been set up ahead of time. Depending on
  1728.     your C compiler and options, this may have been done by the
  1729.     startup code.  Or it can be done manually
  1730.  
  1731.     From C:
  1732.         extern ULONG stdout;
  1733.         /* Remove the extern if startup code did not define stdout */
  1734.         stdout=Output();
  1735.  
  1736.     From assembly:
  1737.         XDEF    _stdout
  1738.         DC.L    _stdout    ;<- Place result of dos.library/Output() here.
  1739.  
  1740. amiga.lib/TimeDelay                                       amiga.lib/TimeDelay
  1741.  
  1742.    NAME
  1743.     TimeDelay -- Return after a period of time has elapsed.
  1744.  
  1745.    SYNOPSIS
  1746.     Error = TimeDelay( Unit, Seconds, MicroSeconds )
  1747.     D0                 D0    D1       D2
  1748.  
  1749.     LONG TimeDelay( LONG, ULONG, ULONG );
  1750.  
  1751.    FUNCTION
  1752.     Waits for the period of time specified before returning to the
  1753.     the caller.
  1754.  
  1755.    INPUTS
  1756.     Unit -- timer.device unit to open for this command.
  1757.     Seconds -- The seconds field of a timerequest is filled with
  1758.         this value. Check the documentation for what a partucular
  1759.         timer.device unit expects there.
  1760.     MicroSeconds -- The microseconds field of a timerequest is
  1761.         filled with this value. Check the documentation for what
  1762.         a particular timer.device units expects there.
  1763.  
  1764.    RESULTS
  1765.     Error -- will be zero if all went well; otherwise, non-zero.
  1766.  
  1767.    NOTES
  1768.     Two likely reasons for failures are invalid unit numbers or
  1769.     no more free signal bits for this task.
  1770.  
  1771.     While this function first appears in V37 amiga.lib, it works
  1772.     on Kickstart V33 and higher.
  1773.  
  1774.    SEE ALSO
  1775.     timer.device/TR_ADDREQUEST,
  1776.     timer.device/TR_WAITUNTIL,
  1777.     timer.device/WaitUnitl()
  1778.  
  1779.    BUGS
  1780.  
  1781.