/*
 * $Id$
 */

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

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      OS()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $ONELINER$
      Return the current operating system.
   $SYNTAX$
      OS() --> <cOperatingSystem>
   $RETURNS$
      <cOperatinSystem> The current operating system.
   $DESCRIPTION$
      This function will return the current operating system.
   $EXAMPLES$
      ? OS()
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Version()
   $CATEGORY$
      API
   $SUBCATEGORY$
      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$
      ? Version() // "Harbour Terminal: Standard stream console"
   $STATUS$
      S
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      OS()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      GetEnv()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $ONELINER$
      Obtains a system environmental setting.
   $SYNTAX$
      GetEnv( <cEnviroment> )  --> <cReturn>
   $ARGUMENTS$
      <cEnviroment> Enviromental variable to obtain.
   $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.

      If no environment variable
      is found, an empty string is returned.
   $EXAMPLES$
      ? GetEnv( "PATH" )
      ? GetEnv( "CONFIG" )
      ? GetEnv( "HARBOURCMD", "-n -l -es2" )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      GetE()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      GetE()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $ONELINER$
      Obtains a system environmental setting.
   $SYNTAX$
      GetE( <cEnviroment> )  --> <cReturn>
   $ARGUMENTS$
      <cEnviroment> Enviromental variable to obtain.
   $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.

      If no environment variable
      is found, an empty string is returned.
   $EXAMPLES$
      ? GetE( "PATH" )
      ? GetE( "CONFIG" )
      ? GetE( "HARBOURCMD", "-n -l -es2" )
   $STATUS$
      R
   $COMPLIANCE$
      This is CA-Cl*pper compliant.

      The <cDefaultValue> parameter is a Harbour extension.
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      GetEnv()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_GetEnv()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $ONELINER$
      Obtains a system environmental setting.
   $SYNTAX$
      hb_GetEnv(<cEnviroment>, [<cDefaultValue>], [<lApplyCodepage>] )  --> <cReturn>
   $ARGUMENTS$
      <cEnviroment> Enviromental variable to obtain.

      <cDefaultValue> Optional value to return if <cEnvironment> is not found.

      <lApplyCodepage> optional logical parameter specifing whether to
       apply automatic codepage conversion (to the codepage
       specified by Set( _SET_OSCODEPAGE ) on the obtained value.
       The default is .T.  Note that if the default value is passed and the environment
       value is not found, this codepage conversion is not performed against
       the returned default value
   $RETURNS$
      <cReturn>     Value of the environment variable or <cDefaultValue> or an empty string.
   $DESCRIPTION$
      This function yields a string that is the value of the
      environment variable <cEnviroment>, which is stored at the
      system level.

      If no environment variable
      can be found, the value of the function will be <cDefaultValue>
      if it is passed, else an empty string.
   $EXAMPLES$
      ? hb_GetEnv( "PATH" )
      ? hb_GetEnv( "CONFIG" )
      ? hb_GetEnv( "HARBOURCMD", "-n -l -es2" )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      GetEnv(), GetE()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Procedure
   $NAME$
      __Run()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $ONELINER$
      Run an external program.
   $SYNTAX$
      __Run( <cCommand> )
   $ARGUMENTS$
      <cCommand> Command to execute.
   $DESCRIPTION$
      This command runs an external program. Ensure 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 MS-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 OS shell
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      RUN
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Tone()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $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 limited 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
      //
      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
   $STATUS$
      S
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Chr(),SET BELL
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Command
   $NAME$
      RUN
   $CATEGORY$
      API
   $SUBCATEGORY$
      Environment
   $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 OS shell
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      RUN
   $END$
 */
