Click above to get retro games delivered to your door ever month!

 PARAMETERS

 The ClipOn library functions are very flexible in handling
 parameters.  Most of the ClipOn functions accept parameters,
 however, many of the functions do not need any parameters to
 operate, such as C_GETRAM() which returns the amount of base ram.
 Of the functions that accept parameters most of them are designed
 to accept variable parameters.  The term variable parameters means
 that some parameters are required to call a function while some
 parameters are optional and can be skipped or excluded from the
 parameter list.  This makes it easier to learn a function since
 only some of the parameters are actually needed to make the
 function operate.  The optional parameters will all default to pre-
 determined values if the parameter is not specified.

 The left and right brackets ([ ]) are used to identify parameters
 which are optional and need not be specified.  The following is an
 example of a function with variable parameters:

 C_FILEREAD(f_handle [,bytes])

 The parameter f_handle does not have brackets and is therefore
 required by the function.  However, the parameter bytes has
 brackets indicating that it is an optional parameter and can be
 specified with a value or does not have to be specified at all.  If
 it is not specified, it will default to it's pre-determined value.

 An additional advantage to the variable parameter design is the
 actual functionality of the routine itself.  Many of the ClipOn
 functions actually perform differently depending on the inclusion
 or exclusion of a parameter.  For example, the C_CAPLOCK() function
 can be used to turn the CAPS LOCK key on, turn it off, and to
 determine the current setting of the key.  The behavior of the
 function depends on whether or not a parameter is passed to the
 function and if it is passed the value of the parameter.  See the
 example below:

 1. Passing true (.T.) turns the Cap Lock key on and returns the
 current status.
      status = C_CAPLOCK(.T.)

 2. Passing false (.F.) turns the Cap Lock key off and returns the
 current status.
      status = C_CAPLOCK(.F.)

 3. Passing nothing just returns the current status of the Cap Lock
 key.
      status = C_CAPLOCK()


 RETURN VALUES

 Most of the ClipOn functions have a return value such as a logical,
 numeric, or character.  There are, however, some functions that do
 not need to return any information so they do not have a return value.

 If a function has a return value, the value returned may be used in
 several different ways or it does not have to be used at all.  For
 example, the C_FILEWRITE() function returns the number of bytes
 written to a file.  The return value from the function can be
 evaluated in several ways, as shown below:

 1. Store the return value to a variable.
      bytes_written = C_FILEWRITE(handle, string)

 2. Evaluate the return value in an IF statement.
      if C_FILEWRITE(handle, string) != 1024

 3. Do nothing with the return value.
      C_FILEWRITE(handle, string)

 The usage of the function will determine the way the return value
 is evaluated.


 PARAMETER CHECKING

 For most ClipOn functions there is no attempt made in the function
 to check the type of parameter passed, the value of it, or a valid
 range (i.e. screen coordinates).  Parameter checking effects the
 speed of the function and adds to the size of the function and the
 executable file.

 Some functions, however, do check that the number of required
 parameters is correct.  If a negative one (-1) is returned from a
 ClipOn function, this indicates a problem with the parameter(s)
 passed to the function.
.