home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / cd32 / cd32_support / doc / lowlevel.doc < prev    next >
Text File  |  1993-10-18  |  27KB  |  769 lines
  1. TABLE OF CONTENTS
  2.  
  3. lowlevel.library/AddKBInt
  4. lowlevel.library/AddTimerInt
  5. lowlevel.library/AddVBlankInt
  6. lowlevel.library/ElapsedTime
  7. lowlevel.library/GetKey
  8. lowlevel.library/GetLanguageSelection
  9. lowlevel.library/QueryKeys
  10. lowlevel.library/ReadJoyPort
  11. lowlevel.library/RemKBInt
  12. lowlevel.library/RemTimerInt
  13. lowlevel.library/RemVBlankInt
  14. lowlevel.library/SetJoyPortAttrsA
  15. lowlevel.library/StartTimerInt
  16. lowlevel.library/StopTimerInt
  17. lowlevel.library/SystemControlA
  18. lowlevel.library/AddKBInt                           lowlevel.library/AddKBInt
  19.  
  20.    NAME
  21.     AddKBInt -- adds a routine to the keyboard interrupt. (V40)
  22.  
  23.    SYNOPSIS
  24.     intHandle = AddKBInt(intRoutine, intData);
  25.     D0                   A0          A1
  26.  
  27.     APTR AddKBInt(APTR, APTR);
  28.  
  29.    FUNCTION
  30.     This routine extends the functionality of the keyboard interrupt to
  31.     include intRoutine. Since this is an extention of the normal
  32.     keyboard interrupt all of the keyboard handshaking is handled. The
  33.     keyboard error codes are filtered out and not passed to intRoutine.
  34.  
  35.     The routine is called whenever the user enters a key on the
  36.     keyboard.
  37.  
  38.     The routine is called from within an interrupt, so normal
  39.     restrictions apply. The routine must preserve the following
  40.     registers: A2, A3, A4, A7, D2-D7. Other registers are
  41.     scratch, except for D0, which MUST BE SET TO 0 upon
  42.     exit. On entry to the routine, A1 holds 'intData' and A5
  43.     holds 'intRoutine', and D0 contains the rawkey code read
  44.     from the keyboard.
  45.  
  46.     The routine is not called when a reset is received from the
  47.     keyboard.
  48.  
  49.     This is a low level function that does not fit the normal Amiga
  50.     multitasking model. The interrupt installed will have no knowledge
  51.     of which window/screen currently has input focus.
  52.  
  53.     If your program is to exit without reboot, you MUST call RemKBInt()
  54.     before exiting.
  55.  
  56.     Only one interrupt routine may be added to the system.  ALWAYS
  57.     check the return value in case some other task has previously
  58.     used this function.
  59.  
  60.    INPUTS
  61.     intRoutine - the routine to invoke every vblank. This routine should
  62.              be as short as possible to minimize its effect on overall
  63.              system performance.
  64.     intData - data passed to the routine in register A1. If more than one
  65.           long word of data is required this should be a pointer to
  66.           a structure that contains the required data.
  67.  
  68.    RESULT
  69.     intHandle - a handle used to manipulate the interrupt, or NULL
  70.             if it was not possible to attach the routine.
  71.  
  72.    SEE ALSO
  73.     RemKBInt()
  74.  
  75. lowlevel.library/AddTimerInt                     lowlevel.library/AddTimerInt
  76.  
  77.    NAME
  78.     AddTimerInt -- adds an interrupt that is executed at regular
  79.                intervals. (V40)
  80.  
  81.    SYNOPSIS
  82.     intHandle = AddTimerInt(intRoutine, intData);
  83.     D0                      A0          A1
  84.  
  85.     APTR AddTimerInt(APTR, APTR);
  86.  
  87.    FUNCTION
  88.     Calling this routine causes the system to allocate a CIA timer
  89.     and set up 'intRoutine' to service any interrupts caused by the timer.
  90.     Although the timer is allocated it is neither running, nor enabled.
  91.     StartIntTimer() must be called to establish the time interval and
  92.     start the timer.
  93.  
  94.     The routine is called from within an interrupt, so normal
  95.     restrictions apply. The routine must preserve the following
  96.     registers: A2, A3, A4, A7, D2-D7. Other registers are
  97.     scratch, except for D0, which MUST BE SET TO 0 upon
  98.     exit. On entry to the routine, A1 holds 'intData' and A5
  99.     holds 'intRoutine'.
  100.  
  101.     Only a single CIA timer will be allocated by this routine. So this
  102.     routine may only be called once without an intervening call to
  103.     RemTimerInt().
  104.  
  105.     The CIA timer used by this routine is not guaranteed to always be
  106.     the same. This routine utilizes the CIA resource and uses an
  107.     unallocated CIA timer.
  108.  
  109.     If your program is to exit without reboot, you MUST match all
  110.     calls to this function with calls to RemTimerInt() before exiting.
  111.  
  112.     Even if you only use the function once in your program; checking
  113.     the return value will make your program more tolerant for
  114.     mulititasking on the Amiga computer platforms.
  115.  
  116.    INPUTS
  117.     intRoutine - the routine to invoke upon timer interrupts. This routine
  118.              should be as short as possible to minimize its effect on
  119.              overall system performance.
  120.     intData - data passed to the routine in register A1. If more than one
  121.           long word of data is required this should be a pointer to
  122.           a structure that contains the required data.
  123.  
  124.    RESULT
  125.     intHandle - a handle used to manipulate the interrupt, or NULL
  126.             if it was not possible to attach the routine.
  127.  
  128.    SEE ALSO
  129.     RemTimerInt(), StopTimerInt(), StartTimerInt()
  130.  
  131. lowlevel.library/AddVBlankInt                   lowlevel.library/AddVBlankInt
  132.  
  133.    NAME
  134.     AddVBlankInt -- adds a routine executed every vertical blank. (V40)
  135.  
  136.    SYNOPSIS
  137.     intHandle = AddVBlankInt(intRoutine, intData);
  138.     D0                 a0      a1
  139.  
  140.     APTR AddVBlankInt(APTR, APTR);
  141.  
  142.    FUNCTION
  143.     Lets you attach a routine to the system which will get called
  144.     everytime a vertical blanking interrupt occurs.
  145.  
  146.     The routine is called from within an interrupt, so normal
  147.     restrictions apply. The routine must preserve the following
  148.     registers: A2, A3, A4, A7, D2-D7. Other registers are
  149.     scratch, except for D0, which MUST BE SET TO 0 upon
  150.     exit. On entry to the routine, A1 holds 'intData' and A5
  151.     holds 'intRoutine'.
  152.  
  153.     If your program is to exit without reboot, you MUST call
  154.     RemVBlankInt() before exiting.
  155.  
  156.     Only one interrupt routine may be added to the system.  ALWAYS check
  157.     the return value in case some other task has previously used this
  158.     function.
  159.  
  160.    INPUTS
  161.     intRoutine - the routine to invoke every vblank. This routine should
  162.              be as short as possible to minimize its effect on overall
  163.              system performance.
  164.     intData - data passed to the routine in register A1. If more than one
  165.           long word of data is required this should be a pointer to
  166.           a structure that contains the required data.
  167.  
  168.    RESULT
  169.     intHandle - a handle used to manipulate the interrupt, or NULL
  170.             if it was not possible to attach the routine.
  171.  
  172.    SEE ALSO
  173.     RemVBlankInt()
  174.  
  175. lowlevel.library/ElapsedTime                     lowlevel.library/ElapsedTime
  176.  
  177.    NAME
  178.     ElapsedTime -- returns the time elapsed since it was last called. (V40)
  179.  
  180.    SYNOPSIS
  181.     fractionalSeconds = ElapsedTime(context);
  182.     D0                              A0
  183.  
  184.     ULONG ElapsedTime(struct EClockVal *);
  185.  
  186.    FUNCTION
  187.     This function utilizes the timer.device/ReadEClock() function to get
  188.     an accurate elapsed time value. Since the context needs to be
  189.     established the first call to this routine will return a nonsense
  190.     value.
  191.  
  192.     The return value for this function only allows for sixteen bits
  193.     worth for the integer number of seconds and sixteen bits for the
  194.     factional number of seconds.
  195.  
  196.     With sixteen bits worth of integer seconds this function can be
  197.     used to timer an interval up to about 16 hours. If the actual time
  198.     interval is larger this function will return this maximum value.
  199.  
  200.     The sixteen bits for fractional seconds gives a resolution of
  201.     approximately 20 microseconds. However, it is not recomended
  202.     to expect this function to be accurate for a time interval of
  203.     less than 200 microseconds.
  204.  
  205.    INPUTS
  206.     context - pointer to an EClockVal structure. The first time you
  207.           call this function, you should initialize the structure
  208.           to 0s. You should then reuse the same structure for
  209.           subsequent calls to this function, as this is how the
  210.           elapsed time is calculated.
  211.  
  212.    RESULT
  213.     fractionalSeconds - The elapsed time as a fixed point 32-bit
  214.                         number with the point fixed in the middle.
  215.                         That is, the upper order sixteen bits represent
  216.                         the number of seconds elapsed. The low order
  217.                         sixteen bit represent the fractional number of
  218.                         seconds elapsed. This value is limited to about
  219.                         sixteen hours. Although this value is precise
  220.                         to nearly 20 microseconds it is only accurate to
  221.                         within 200 microseconds.
  222.  
  223.    WARNING
  224.     The first call to this function will return a non-sense value. Only
  225.     rely on its result starting with the second call.
  226.  
  227.    SEE ALSO
  228.     timer.device/ReadEClock()
  229.  
  230. lowlevel.library/GetKey                               lowlevel.library/GetKey
  231.  
  232.    NAME
  233.     GetKey -- returns the currently pressed rawkey code and qualifiers.
  234.           (V40)
  235.  
  236.    SYNOPSIS
  237.     key = GetKey();
  238.     D0
  239.  
  240.     ULONG GetKey(VOID);
  241.  
  242.    FUNCTION
  243.     This function returns the currently pressed non-qualifier key and
  244.     all pressed qualifiers.
  245.  
  246.     This function is safe within an interrupt.
  247.  
  248.     This is a low level function that does not fit the normal Amiga
  249.     multitasking model. The values returned by this function are
  250.     not modified by which window/screen currently has input focus.
  251.  
  252.    RESULT
  253.     key - key code for the last non-qualifier key pressed in the low
  254.           order word. If no key is pressed this word will be FF. The
  255.           upper order word contains the qualifiers which can be found
  256.           within the long word as follows:
  257.                     Qualifier               Key
  258.                     LLKB_LSHIFT             Left Shift
  259.                     LLKB_RSHIFT             Rigt Shift
  260.                     LLKB_CAPSLOCK           Caps Lock
  261.                     LLKB_CONTROL            Control
  262.                     LLKB_LALT               Left Alt
  263.                     LLKB_RALT               Right Alt
  264.                     LLKB_LAMIGA             Left Amiga
  265.                     LLKB_RAMIGA             Right Amiga
  266.  
  267.    SEE ALSO
  268.     <libraries/lowlevel.h>
  269.  
  270. lowlevel.library/GetLanguageSelection   lowlevel.library/GetLanguageSelection
  271.  
  272.    NAME
  273.     GetLanguageSelection -- returns the current language selection. (V40)
  274.  
  275.    SYNOPSIS
  276.     language = GetLanguageSelection();
  277.     D0
  278.  
  279.     ULONG GetLanguageSelection (VOID);
  280.  
  281.    FUNCTION
  282.     Determine what the user has specified as a language.
  283.  
  284.    RESULT
  285.     language - user specified language, or zero if none has yet been
  286.            specified. See <libraries/lowlevel.h> for a definition
  287.            of the currently supported language.
  288.  
  289.    SEE ALSO
  290.     <libraries/lowlevel.h>, locale.doc
  291.  
  292. lowlevel.library/QueryKeys                         lowlevel.library/QueryKeys
  293.  
  294.    NAME
  295.     QueryKeys -- return the states for a set of keys. (V40)
  296.  
  297.    SYNOPSIS
  298.     QueryKeys(queryArray, arraySize);
  299.               A0          D1
  300.  
  301.     VOID QueryKeys(struct KeyQuery *, UBYTE);
  302.  
  303.    FUNCTION
  304.     Scans the keyboard to determine which of the rawkey codes
  305.     listed in the QueryArray are currently pressed. The state for each
  306.     key is returned in the array.
  307.  
  308.     This function may be invoked from within an interrupt, but the size
  309.     of QueryArray should be kept as small as possible.
  310.  
  311.     This is a low level function that does not fit the normal Amiga
  312.     multitasking model. The values returned have no knowledge
  313.     of which window/screen currently has input focus.
  314.  
  315.    INPUTS
  316.     queryArray - an array of KeyQuery structures. The kq_KeyCode fields
  317.              of these structures should be filled with the rawkey
  318.              codes you wish to query about. Upon return from this
  319.              function, the kq_Pressed field of these structures
  320.              will be set to TRUE if the associated key is down,
  321.                  and FALSE if not.
  322.     arraySize - number of key code entries in queryArray
  323.  
  324.    SEE ALSO
  325.     <libraries/lowlevel.h>
  326.  
  327. lowlevel.library/ReadJoyPort                     lowlevel.library/ReadJoyPort
  328.  
  329.    NAME
  330.     ReadJoyPort -- return the state of the selected joy/mouse port. (V40)
  331.  
  332.    SYNOPSIS
  333.     portState = ReadJoyPort(portNumber);
  334.     D0                      D0
  335.  
  336.     ULONG ReadJoyPort(ULONG);
  337.  
  338.    FUNCTION
  339.     This function is used to determine what device is attached to the
  340.     joy port and the current position/button state. The user may attach
  341.     a mouse, game controller, or joystick to the port and this function
  342.     will dynamically detect which device is attached and return the
  343.     appropriatly formatted portState.
  344.  
  345.     To determine the type of controller that is attached, this function
  346.     clocks the game controller and/or interprets changes in the joy
  347.     port data. Valid clocked data from the game controller is immediately
  348.     detected. However, to accuratly determine if a mouse or joystick is
  349.     attached, several calls to this function are required along with some
  350.     movement at the joy port by the user.
  351.  
  352.     This function always executes immediatly.
  353.  
  354.     This is a low level single threaded function that does not fit the
  355.     normal Amiga multitasking model. Only one task can be executing
  356.     this routine at any time. All others will return immediately with
  357.     JP_TYPE_NOTAVAIL.
  358.  
  359.     The nature of this routine is not meant to encourage non-multitasking
  360.     friendly programming practices like polling loops. If your task
  361.     is waiting for a transition to be returned use a WaitTOF() between
  362.     calls to minimize the total system impact.
  363.  
  364.     When called the first time, for each port, this function attempts to
  365.     acquire certain system resources. In order to aquire these resources
  366.     this function MUST be called from a task, or a DOS process. If this
  367.     function fails to aquire the necessary resources, it will
  368.     return with JP_TYPE_NOTAVAIL. Once the resources are aquired (return
  369.     value other than JP_TYPE_NOTAVAIL) this function may be used in
  370.     interrupts.
  371.  
  372.    INPUTS
  373.     portNumber - port to read, in the range 0 to 3.
  374.  
  375.    RESULT
  376.     portState - bit map that identifies the device and the current
  377.                 state of that device. The format of the bit map is
  378.                 dependant on the type of device attached.
  379.  
  380.                 The following constants from <libraries/lowlevel.h>
  381.                 are used to determine which device is attached and
  382.                 the state of that device.
  383.  
  384.                 The type of device can be determined by applying
  385.                 the mask JP_TYPE_MASK to the return value and comparing
  386.                 the resultant value with the following:
  387.  
  388.                     JP_TYPE_NOTAVAIL        port data unavailable
  389.                     JP_TYPE_GAMECTLR        game controller
  390.                     JP_TYPE_MOUSE           mouse
  391.                     JP_TYPE_JOYSTK          joystick
  392.                     JP_TYPE_UNKNOWN         unknown device
  393.  
  394.                 If type = JP_TYPE_GAMECTLR the bit map of portState is:
  395.                     JPF_BUTTON_BLUE         Blue - Stop
  396.                     JPF_BUTTON_RED          Red - Select
  397.                     JPF_BUTTON_YELLOW       Yellow - Repeat
  398.                     JPF_BUTTON_GREEN        Green - Shuffle
  399.                     JPF_BUTTON_FORWARD      Charcoal - Forward
  400.                     JPF_BUTTON_REVERSE      Charcoal - Reverse
  401.                     JPF_BUTTON_PLAY         Grey - Play/Pause
  402.                     JPF_JOY_UP              Up
  403.                     JPF_JOY_DOWN            Down
  404.                     JPF_JOY_LEFT            Left
  405.                     JPF_JOY_RIGHT           Right
  406.  
  407.                 If type = JP_TYPE_JOYSTK the bit map of portState is:
  408.                     JPF_BUTTON_BLUE         Right
  409.                     JPF_BUTTON_RED          Fire
  410.                     JPF_JOY_UP              Up
  411.                     JPF_JOY_DOWN            Down
  412.                     JPF_JOY_LEFT            Left
  413.                     JPF_JOY_RIGHT           Right
  414.  
  415.                 If type = JP_TYPE_MOUSE the bit map of portState is:
  416.                     JPF_BUTTON_BLUE         Right mouse
  417.                     JPF_BUTTON_RED          Left mouse
  418.                     JPF_BUTTON_PLAY         Middle mouse
  419.                     JP_MVERT_MASK           Mask for vertical counter
  420.                     JP_MHORZ_MASK           Mask for horizontal counter
  421.  
  422.    SEE ALSO
  423.     SetJoyPortAttrs()
  424.  
  425. lowlevel.library/RemKBInt                           lowlevel.library/RemKBInt
  426.  
  427.   NAME
  428.     RemKBInt -- remove a previously installed keyboard interrupt. (V40)
  429.  
  430.   SYNOPSIS
  431.     RemKBInt(intHandle);
  432.              A1
  433.  
  434.     VOID RemKBInt(APTR);
  435.  
  436.   FUNCTION
  437.     Remove a keyboard interrupt routine previously added with AddKBInt().
  438.  
  439.   INPUTS
  440.     intHandle - handle obtained from AddKBInt(). This may be NULL,
  441.             in which case this function does nothing.
  442.  
  443.   SEE ALSO
  444.     AddKBInt()
  445.  
  446. lowlevel.library/RemTimerInt                     lowlevel.library/RemTimerInt
  447.  
  448.    NAME
  449.     RemTimerInt -- remove a previously installed timer interrupt. (V40)
  450.  
  451.    SYNOPSIS
  452.     RemTimerInt(intHandle);
  453.                 A1
  454.  
  455.     VOID RemTimerInt(APTR);
  456.  
  457.    FUNCTION
  458.     Removes a timer interrupt routine previously installed with
  459.     AddTimerInt.
  460.  
  461.    INPUTS
  462.     intHandle - handle obtained from AddTimerInt(). This may be NULL,
  463.             in which case this function does nothing.
  464.  
  465.    SEE ALSO
  466.     AddTimerInt(), StopTimerInt(), StartTimerInt()
  467.  
  468. lowlevel.library/RemVBlankInt                   lowlevel.library/RemVBlankInt
  469.  
  470.    NAME
  471.     RemVBlankInt -- remove a previously installed vertical blank routine.
  472.             (V40)
  473.  
  474.    SYNOPSIS
  475.     RemVBlankInt(intHandle);
  476.              A1
  477.  
  478.     VOID RemVBlankInt(APTR);
  479.  
  480.    FUNCTION
  481.     Removes a vertical blank interrupt routine previously added with
  482.     AddVBlankInt().
  483.  
  484.    INPUTS
  485.     intHandle - handle obtained from AddVBlankInt(). This may be NULL,
  486.             in which case this function does nothing.
  487.  
  488.    SEE ALSO
  489.     AddVBlankInt()
  490.  
  491. lowlevel.library/SetJoyPortAttrsA           lowlevel.library/SetJoyPortAttrsA
  492.  
  493.    NAME
  494.     SetJoyPortAttrsA -- change the attributes of a port.  (V40.27)
  495.     SetJoyPortAttrs -- varargs stub for SetJoyPortAttrsA().  (V40.27)
  496.  
  497.    SYNOPSIS
  498.     success = SetJoyPortAttrsA(portNumber, tagList);
  499.     D0                         D0          A1
  500.  
  501.     BOOL SetJoyPortAttrsA(ULONG, struct TagItem *);
  502.  
  503.     Success = SetJoyPortAttrs(portNumber, firstTag, ...);
  504.  
  505.     BOOL SetJoyPortAttrs(Tag, ...);
  506.  
  507.  
  508.    FUNCTION
  509.     This function allows modification of several attributes held by
  510.     ReadJoyPort() about both it's operation and the type of controller
  511.     currently plugged into the port.
  512.  
  513.     ReadJoyPort()'s default behavior is to attempt to automatically
  514.     sense the type of controller plugged into any given port, when
  515.     asked to read that port. This behavior is beneficial, to allow
  516.     simple detection of the type of controller plugged into the port.
  517.     Unfortunately, rare cases are possible where extremely fine
  518.     mouse movements appear to be real joystick movements. Also, this
  519.     ability to auto-sense the controller type causes most reads to
  520.     take longer than if there were no auto-sensing.
  521.  
  522.     SetJoyPortAttrs() is intended to provide for both of these cases.
  523.     It allows the programmer to notify ReadJoyPort() to stop spending
  524.     time attempting to sense which type of controller is in use -- and,
  525.     optionally, to force ReadJoyPort() into utilizing a certain
  526.     controller type.
  527.  
  528.    INPUTS
  529.     portNumber - the joyport in question (0-3).
  530.     tagList - a pointer to an array of tags providing parameters
  531.               to SetJoyPortAttrs(); if NULL, the function
  532.               will return TRUE, but do nothing.
  533.  
  534.    TAGS
  535.     SJA_Type (ULONG) - Sets the current controller type to the mouse,
  536.             joystick, or game controller. Supply one of
  537.             SJA_TYPE_GAMECTLR, SJA_TYPE_MOUSE, SJA_TYPE_JOYSTK,
  538.             or SJA_TYPE_AUTOSENSE. If SJA_TYPE_AUTOSENSE is used,
  539.             ReadJoyPort() will attempt to determine the type of
  540.             controller plugged into the given port automatically.
  541.             If one of the other types is used, ReadJoyPort() will
  542.             make no attempt to read the given controller as
  543.             anything other than the type specified. The default
  544.             type is SJA_AUTOSENSE.
  545.  
  546.                      Note -- if you set the type to anything other than
  547.                      auto-sense, it's your responsibility to return it
  548.                      to auto-sense mode before exiting.
  549.  
  550.     SJA_Reinitialize (VOID) - Return a given port to it's initial state,
  551.                  forcing a port to deallocate any allocated resources;
  552.                      return the implied type to SJA_TYPE_AUTOSENSE.
  553.  
  554.    RESULT
  555.     success - TRUE if everything went according to plan, or FALSE upon
  556.           failure
  557.  
  558.    SEE ALSO
  559.     ReadJoyPort(), <libraries/lowlevel.h>
  560.  
  561. lowlevel.library/StartTimerInt                 lowlevel.library/StartTimerInt
  562.  
  563.    NAME
  564.     StartTimerInt -- start the timer associated with the timer interrupt.
  565.              (V40)
  566.  
  567.    SYNOPSIS
  568.     StartTimerInt(intHandle, timeInterval, continuous);
  569.                   A1         D0            D1
  570.  
  571.     VOID StartTimerInt(APTR, ULONG, BOOL);
  572.  
  573.    FUNCTION
  574.     This routine starts a stopped timer that is assocatied with a
  575.     timer interrupt created by AddTimerInt().
  576.  
  577.    INPUTS
  578.     intHandle - handle obtained from AddTimerInt().
  579.     timeInterval - number of micoseconds between interrupts. The
  580.                    maximum value allowed is 90,000. If higher values
  581.                    are passed there will be unexpected results.
  582.     continuous - FALSE for a one shot interrupt. TRUE for multiple
  583.                  interrupts.
  584.  
  585.    SEE ALSO
  586.     AddTimerInt(), RemTimerInt(), StopTimerInt()
  587.  
  588. lowlevel.library/StopTimerInt                   lowlevel.library/StopTimerInt
  589.  
  590.    NAME
  591.     StopTimerInt -- stop the timer associated with the timer interrupt.
  592.             (V40)
  593.  
  594.    SYNOPSIS
  595.     StopTimerInt(intHandle);
  596.                  A1
  597.  
  598.     VOID StopTimerInt(APTR);
  599.  
  600.    FUNCTION
  601.     Stops the timer associated with the timer interrupt handle passed.
  602.     This is used to stop a continuous timer started by
  603.     StartTimerInt().
  604.  
  605.    INPUTS
  606.     intHandle - handle obtained from AddTimerInt().
  607.  
  608.    SEE ALSO
  609.     AddTimerInt(), RemTimerInt(), StartTimerInt()
  610.  
  611. lowlevel.library/SystemControlA               lowlevel.library/SystemControlA
  612.  
  613.    NAME
  614.     SystemControlA - Method for selectively disabling OS features. (V40)
  615.     SystemControl - varargs stub for SystemControlA().
  616.  
  617.    SYNOPSIS
  618.     failTag = SystemControlA(tagList);
  619.     D0                       A1
  620.  
  621.     ULONG SystemControlA(struct TagItem *);
  622.  
  623.     failTag = SystemControl(firstTag, ...);
  624.  
  625.     ULONG SystemControl(Tag, ...);
  626.  
  627.    FUNCTION
  628.     This function is used to alter the operation of the system. Some of
  629.     the alterations involve controlling what are normally regarded as
  630.     system resources. In order to minimize confusion only one task is
  631.     allowed to control any part of the system resources. This prevents
  632.     the possiblity of two tasks fighting, each controlling a part of the
  633.     system. If a tag is identified as task exclusive, it means that
  634.     only one task can hold (set to TRUE) that tag. If
  635.     another task attempts to set the same tag to TRUE, the call to
  636.     SystemControl() will fail.
  637.  
  638.     It is important to remember that SystemControl() can fail.
  639.  
  640.     This is a low level function and certain tags do not fit the normal
  641.     Amiga multitasking model.
  642.  
  643.    INPUTS
  644.     tagList - pointer to an array of tags listing the features of the
  645.               system to be enabled/disabled.
  646.  
  647.    TAGS
  648.     SCON_TakeOverSys (BOOL)
  649.         TRUE -    Takes over the CPU to ensure that a program gets every
  650.             ounce of CPU time (with the exception of crucial
  651.             interrupts). When in this mode, the CPU will belong
  652.             completely to the program. Task switching will be
  653.             disabled and the program will get all CPU cycles. This
  654.             means any calls to the OS that involve multitasking in
  655.             some way will not execute correctly. Other tasks will
  656.             not run until this tag is used with FALSE. However,
  657.             during a Wait() on a signal, multitasking will
  658.             automatically be turned back on until the signal is
  659.             received. Once received, multitasking will again be
  660.             disabled and the CPU will be exclusive to the owning
  661.             program.
  662.         FALSE - Relinquishes the CPU and reenables multitasking.
  663.             This tag is task exculsive. This tag nests. A task may
  664.             take over the CPU several times before relinquishing
  665.             it.
  666.  
  667.     SCON_KillReq (BOOL)
  668.            TRUE -     Disables system requesters.  These are the reasons for
  669.             NOT disabling system requesters:
  670.  
  671.                         1- No calls in the program will cause a system
  672.                    requester.
  673.                         2- The only thing that could cause a requester
  674.                    to appear is the lack of a CD in the drive and
  675.                    SCON_CDReboot is set to CDReboot_On, therefore a
  676.                    requester can't appear.
  677.                     3- The only disk I/O is via a CD with SCON_CDReboot
  678.                    set to CDReboot_On and/or nonvolatile.library.
  679.  
  680.                 When requesters should not be disabled.
  681.                 GAME PROGRAMS:
  682.                 No DOS calls are used after loading; or SCON_CDReboot
  683.             is CDReboot_On; and nonvolatile.library is used for
  684.             loading and saving user data.
  685.  
  686.                 This fits the above case since; After loading either
  687.             DOS calls are not used fitting reason 1, or the game
  688.             is accessing the CD and has SCON_CDReboot set to
  689.             CDReboot_On fitting reason 2. The game accesses high
  690.             scores, game position, etc through nonvolatile.library,
  691.             fitting reason 3.
  692.  
  693.         FALSE -    Enables requesters for the program.
  694.  
  695.         This tag nests. Tasks may disable requesters several times before
  696.         enabling them.  However, there must be a matching number of calls.
  697.  
  698.     SCON_CDReboot (ULONG)
  699.         CDReboot_On - Ejecting the CD will cause a reboot of the
  700.             system. Use this only if the program cannot deal with
  701.             error conditions.
  702.         CDReboot_Off - Ejecting the CD will not cause a reboot of the
  703.                 system. Use this if the program needs to insert CDs
  704.             while running.
  705.         CDReboot_Default - Restore the default reboot behavior for this
  706.             system. This should be used upon exit, if this tag had
  707.             been used to change the reboot behaviour. For the CD32
  708.              this value is synonomous with CDReboot_On. For Amiga
  709.             computers this value is synonomous with CDReboot_Off.
  710.  
  711.         Note that the default reboot behavior differs depending on the
  712.         platform. If a program requires a specific behavior it must
  713.         use this function to set the behavior. For example, a CD audio
  714.         mixer would use this tag with the data CDReboot_Off. This will
  715.         allow the changing of audio CDs on the game machine as well as
  716.         Amiga computers.
  717.  
  718.         If, however, there is no error detection code at all this tag
  719.         should be used with the data CDReboot_On.
  720.  
  721.         It is hoped that no program will require CDReboot_On. If all
  722.         programs check for error condition and recover gracefully such a
  723.         call should never be necessary. With the default behavior the
  724.         CD32 will always reset on disk ejects, and programs
  725.         run from Amiga computers will not reset. Thus, leaving the
  726.         default will increase the market for a program to include both
  727.         types of platforms.
  728.  
  729.         This tag does not nest.
  730.  
  731.     SCON_StopInput (BOOL) - When TRUE, stops input.device from using any
  732.         CPU cycles. Also prevents input.device from passing along any
  733.         events from either the keyboard and/or port 0.
  734.  
  735.         This tag is task exclusive. This tag is NOT reversible.
  736.         Attempting to reverse will result in confused/garbled input
  737.         events.
  738.  
  739.     SCON_AddCreateKeys (ULONG) - Starts creating rawkey codes for the
  740.         joystick/game controller on the given unit. The unit value is
  741.         checked for validity and must be either 0 or 1. Each different unit
  742.         used results in some code added to the VBlank interrupt chain.
  743.         This tag nests. The tag SCON_RemCreateKeys is used to undo this
  744.         tag. Tasks may create rawkey codes several times before stopping
  745.         them.
  746.  
  747.         Note that when operating in an Intuition window, the controller's
  748.         blue button is the equivilent of the mouse menu button. Therefore,
  749.         Intuition will be capturing most blue button events. If
  750.         notificiation of these events is important, review the
  751.         documentation for WFLG_RMBTRAP in the
  752.         intuition.library/OpenWindow() autodoc.
  753.  
  754.     SCON_RemCreateKeys (ULONG) - stops rawkey codes for the joystick/game
  755.         controller on the given unit. The unit value is checked for
  756.         validity and must be either 0 or 1.
  757.  
  758.    RESULT
  759.     failTag - zero if all tags succeeded. A non-zero return indicates a
  760.           tag that has failed. It is possible that other tags may
  761.               fail as well.
  762.  
  763.               If any tag fails there will be no change in the system due
  764.               to other tags.
  765.  
  766.    SEE ALSO
  767.     <libraries/lowlevel.h>
  768.  
  769.