/*
 * $Id: misc.txt,v 1.1.1.1 2001/12/21 10:48:56 ronpinkas Exp $
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: TONE()
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      OS()
 * $ONELINER$
 *      Return the current operating system.
 *  $SYNTAX$
 *      OS()   --> <cOperatingSystem>
 *  $CATEGORY$
 *      DOS
 *  $RETURNS$
 *     <cOperatinSystem>  -> The Current operating system.
 *  $DESCRIPTION$
 *      This function will return the current operating system.
 *  $EXAMPLES$
 *      ? OS()
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is Ca-Clipper compatible.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      source/rtl/version.c
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      VERSION()
 *  $CATEGORY$
 *      Environment
 *  $ONELINER$
 *      Returns the HARBOUR Version or the Harbour/Compiler Version.
 *  $SYNTAX$
 *      VERSION()  --> <cReturn>
 *  $ARGUMENTS$
 *      None
 *  $RETURNS$
 *      <cReturn>   String containing the Harbour Version
 *  $DESCRIPTION$
 *      This function returns the current Harbour Version.
 *  $EXAMPLES$
 *      ? QOUT(VERSION())
 *      "Harbour Terminal: Standard stream console"
 *
 *  $TESTS$
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      This function is Ca-Clipper compatible.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      source/rtl/version.c
 *      Library is rtl
 *  $SEEALSO$
 *      OS()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      GETENV()
 *  $CATEGORY$
 *      Environment
 *  $ONELINER$
 *      Obtains system environmental settings.
 *  $SYNTAX$
 *      GETENV(<cEnviroment>, <cDefaultValue> )  --> <cReturn>
 *  $ARGUMENTS$
 *      <cEnviroment> Enviromental variable to obtain.
 *
 *      <cDefaultValue> Optional value to return if <cEnvironment> is not found.
 *  $RETURNS$
 *      <cReturn>     Value of the Environment Variable.
 *  $DESCRIPTION$
 *      This function yields a string that is the value of the
 *      environment variable <cEnviroment>, which is stored at the
 *      system level with the Set command. If no environment variable
 *      can be found, the value of the function will be <cDefaultValue>
 *      if it is passed, else an empty string.
 *  $EXAMPLES$
 *      ? QOUT(GETENV('PATH'))
 *      ? QOUT(GETENV('CONFIG'))
 *      ? QOUT(GETENV('HARBOURCMD', '-n -l -es2'))
 *  </fixed>
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This command is Ca-Clipper compliant.
 *      The <cDefaultValue> parameter is a Harbour extension.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *     source/rtl/gete.c
 *      Library is rtl
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __RUN()
 *  $CATEGORY$
 *      DOS
 *  $ONELINER$
 *      Run an external program.
 *  $SYNTAX$
 *      __RUN( <cCommand> )
 *  $ARGUMENTS$
 *      <cCommand> Command to execute.
 *  $DESCRIPTION$
 *      This command runs an external program. Please make sure that
 *      you have enough free memory to be able to run the external
 *      program. Do not use it to run Terminate and Stay Resident programs
 *      (in case of DOS) since that causes several problems.
 *
 *      Note: This function is what the RUN command preprocesses into.
 *            It is considered bad form to use this function directly.
 *            Use the RUN command instead.
 *  $EXAMPLES$
 *      __Run( "edit " + cMyTextFile )    // Runs an external editor
 *      __Run( "command" )                // Gives a DOS shell (DOS only)
 *  </fixed>
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is Ca-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      source/rtl/run.c
 *      Library is rtl
 *  $SEEALSO$
 *      RUN
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      TONE()
 *  $CATEGORY$
 *      Miscellaneous
 *  $ONELINER$
 *      Sound a tone with a specified frequency and duration.
 *  $SYNTAX$
 *      TONE( <nFrequency>, <nDuration> ) --> NIL
 *  $ARGUMENTS$
 *      <nFrequency>  A non-negative numeric value that specifies the
 *      frequency of the tone in hertz.
 *
 *      <nDuration>   A positive numeric value which specifies the duration
 *      of the tone in 1/18 of a second units.
 *  $RETURNS$
 *      TONE() always returns NIL.
 *  $DESCRIPTION$
 *      TONE() is a sound function that could be used to irritate the end
 *      user, his or her dog, and the surrounding neighborhood. The frequency
 *      is clamped to the range 0 to 32767 Hz.
 *  $EXAMPLES$
 *      If lOk   // Good Sound
 *         TONE(  500, 1 )
 *         TONE( 4000, 1 )
 *         TONE( 2500, 1 )
 *      Else     // Bad Sound
 *         TONE(  300, 1 )
 *         TONE(  499, 5 )
 *         TONE(  700, 5 )
 *      EndIf
 *      </fixed>
 *  $TESTS$
 *      TONE( 800, 1 )                         // same as ? CHR(7)
 *      TONE( 32000, 200 )                     // any dogs around yet?
 *      TONE( 130.80, 1 )                      // musical note - C
 *      TONE( 400, 0 )                         // short beep
 *      TONE( 700 )                            // short beep
 *      TONE( 10, 18.2 )                       // 1 second delay
 *      TONE( -1 )                             // 1/18.2 second delay
 *      TONE( )                                // 1/18.2 second delay
 *  </fixed>
 *  $TESTS$
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      TONE() works exactly like CA-Clipper's TONE().
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      CHR(),SET BELL
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      RUN
 *  $CATEGORY$
 *      Command
 *  $ONELINER$
 *      Run an external program.
 *  $SYNTAX$
 *      RUN  <cCommand>
 *  $ARGUMENTS$
 *      <cCommand> Command to execute.
 *  $DESCRIPTION$
 *      This command runs an external program. Please make sure that you have
 *      enough free memory to be able to run the external program.
 *      Do not use it to run Terminate and Stay Resident programs
 *      (in case of DOS) since that causes several problems.
 *  $EXAMPLES$
 *      Run  "edit " + cMyTextFile      // Runs an external editor
 *      Run  "command"                  // Gives a DOS shell (DOS only)
 *  $TESTS$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This command is Ca-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      source/rtl/run.c
 *      Library is rtl
 *  $SEEALSO$
 *      RUN
 *  $END$
 */
