harbour-core/harbour/doc/en/hvm.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 1999 Jose Lanin <dezac@corevia.com>
 *    Documentation for: PROCLINE(),PROCFILE(),PROCNAME()
 *
 * Copyright 1999 Eddie Ruina
 *   Documentation for: __DBGVMVARLGET()
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: CLIPINIT(), __SETHELPK()
 *
 * Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
 *    Documentation for: DO()
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      PROCNAME()
 *  $CATEGORY$
 *      Misc
 *  $ONELINER$
 *      Gets the name of the current function on the stack
 *  $SYNTAX$
 *      PROCNAME( <nLevel> ) --> <cProcName>
 *  $ARGUMENTS$
 *      <nLevel> is the function level required.   </par>
 *  $RETURNS$
 *      <cProcName> The name of the function that it is being executed.   </par>
 *  $DESCRIPTION$
 *      This function looks at the top of the stack and gets the current
 *      executed function if no arguments are passed. Otherwise it returns
 *      the name of the function or procedure at <nLevel>.   </par>
 *  $EXAMPLES$
 *      See Test
 *  </fixed>
 *  $TESTS$
 *      This test will show the functions and procedures in stack.
 *      before executing it.
 *      function Test()
 *         LOCAL n := 1
 *         while !Empty( ProcName( n ) )
 *            ? ProcName( n++ )
 *         end do
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      PROCNAME() is fully CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      PROCLINE(),PROCFILE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      PROCLINE()
 *  $CATEGORY$
 *      Misc
 *  $ONELINER$
 *      Gets the line number of the current function on the stack.
 *  $SYNTAX$
 *      PROCLINE( <nLevel> ) --> <nLine>
 *  $ARGUMENTS$
 *      <nLevel> is the function level required.   </par>
 *  $RETURNS$
 *      <nLine> The line number of the function that it is being executed.   </par>
 *  $DESCRIPTION$
 *      This function looks at the top of the stack and gets the current
 *      line number of the executed function if no arguments are passed.
 *      Otherwise it returns the line number of the function or procedure
 *      at <nLevel>.   </par>
 *  $EXAMPLES$
 *      See Test
 *  </fixed>
 *  $TESTS$
 *      function Test()
 *         ? ProcLine( 0 )
 *         ? ProcName( 2 )
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      PROCLINE() is fully CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      PROCNAME(),PROCFILE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      PROCFILE()
 *  $CATEGORY$
 *      Misc
 *  $ONELINER$
 *      This function allways returns an empty string.
 *  $SYNTAX$
 *      PROCFILE( <xExp> ) --> <cEmptyString>
 *  $ARGUMENTS$
 *      <xExp> is any valid type.   </par>
 *  $RETURNS$
 *      <cEmptyString> Return an empty string   </par>
 *  $DESCRIPTION$
 *      This function is added to the RTL for full compatibility. It
 *      always returns an empty string.   </par>
 *  $EXAMPLES$
 *      ? ProcFile()
 *  </fixed>
 *  $TESTS$
 *      function Test()
 *         ? ProcFile()
 *         ? ProcFile( NIL )
 *         ? ProcFile( 2 )
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      PROCFILE() is fully CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      PROCNAME(),PROCLINE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_PVALUE()
 *  $CATEGORY$
 *      Parameter Checks
 *  $ONELINER$
 *      Retrieves the value of an argument.
 *  $SYNTAX$
 *      HB_PVALUE( <nArg> ) --> <xExp>
 *  $ARGUMENTS$
 *      A number that indicates the argument to check.   </par>
 *  $RETURNS$
 *      <xExp> Returns the value stored by an argument.   </par>
 *  $DESCRIPTION$
 *      This function is useful to check the value stored in an argument.   </par>
 *  $EXAMPLES$
 *      See Test
 *  </fixed>
 *  $TESTS$
 *      function Test( nValue, cString )
 *         if PCount() == 2
 *            ? hb_PValue( 1 ), nValue
 *            ? hb_PValue( 2 ), cString
 *         endif
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      HB_PVALUE() is a new function and hence not CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      PCOUNT()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      PCOUNT()
 *  $CATEGORY$
 *      Parameter Checks
 *  $ONELINER$
 *      Retrieves the number of arguments passed to a function.
 *  $SYNTAX$
 *      PCOUNT() --> <nArgs>
 *  $ARGUMENTS$
 *      None   </par>
 *  $RETURNS$
 *      <nArgs> A number that indicates the number of arguments
 *      passed to a function or procedure.   </par>
 *  $DESCRIPTION$
 *      This function is useful to check if a function or procedure
 *      has received the required number of arguments.   </par>
 *  $EXAMPLES$
 *      See Test
 *  </fixed>
 *  $TESTS$
 *      function Test( xExp )
 *         if PCount() == 0
 *            ? "This function needs a parameter"
 *         else
 *            ? xExp
 *         endif
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      PCOUNT() is fully CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      HB_PVALUE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __QUIT()
 *  $CATEGORY$
 *      Events
 *  $ONELINER$
 *      Terminates an application.
 *  $SYNTAX$
 *      __QUIT() --> NIL
 *  $ARGUMENTS$
 *      None   </par>
 *  $RETURNS$
 *      NIL   </par>
 *  $DESCRIPTION$
 *      This function terminates the current application and returns
 *      to the system.   </par>
 *  $EXAMPLES$
 *      See Test
 *  </fixed>
 *  $TESTS$
 *      function EndApp( lYesNo )
 *         if lYesNo
 *            __Quit()
 *         endif
 *      return nil
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __QUIT() is fully CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      QUIT
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      CLIPINIT()
 *  $CATEGORY$
 *      Internal
 *  $ONELINER$
 *      Initialize various Harbour sub-systems
 *  $SYNTAX$
 *      CLIPINIT() --> NIL
 *  $ARGUMENTS$
 *      none.   </par>
 *  $RETURNS$
 *      CLIPINIT() always return NIL.   </par>
 *  $DESCRIPTION$
 *      CLIPINIT() is one of the pre-defined INIT PROCEDURE and is executed
 *      at program startup. It declare an empty MEMVAR PUBLIC array called
 *      GetList that is going to be used by the Get system. It activates the
 *      default error handler, and (at least for the moment) calls the
 *      function that sets the default help key.   </par>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      It is said that CLIPINIT() should not call the function that sets
 *      the default help key since CA-Cl*pper does it in some other place.   </par>
 *  $PLATFORMS$
 *      All   </par>
 *  $SEEALSO$
 *       INIT PROCEDURE
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __SetHelpK()
 *  $CATEGORY$
 *      Internal
 *  $ONELINER$
 *      Set F1 as the default help key
 *  $SYNTAX$
 *      __SetHelpK() --> NIL
 *  $ARGUMENTS$
 *      None.   </par>
 *  $RETURNS$
 *      __SetHelpK() always return NIL.   </par>
 *  $DESCRIPTION$
 *      Set F1 to execute a function called HELP if such a function is
 *      linked into the program.   </par>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      __SetHelpK() works exactly like CA-Cl*pper's __SetHelpK()   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      __XHelp(),SET KEY,SETKEY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      BREAK()
 *  $CATEGORY$
 *      Error recovery
 *  $ONELINER$
 *      Exits from a BEGIN SEQUENCE block
 *  $SYNTAX$
 *      BREAK( <xExp> ) --> NIL
 *  $ARGUMENTS$
 *      <xExp> is any valid expression. It is always required.
 *      If do not want to pass any argument, just use NIL.   </par>
 *  $RETURNS$
 *      NIL   </par>
 *  $DESCRIPTION$
 *      This function passes control to the RECOVER statement in a
 *      BEGIN SEQUENCE block.   </par>
 *  $EXAMPLES$
 *      Break( NIL )
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      BREAK() is fully CA-Cl*pper compliant.   </par>
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      BEGIN SEQUENCE
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      DO()
 *  $CATEGORY$
 *      Utility
 *  $ONELINER$
 *      Calls a procedure or a function
 *  $SYNTAX$
 *      DO( <xFuncProc> [, <xArguments...>] )
 *  $ARGUMENTS$
 *      <xFuncProc> = Either a string with a function/procedure name to be called
 *      or a codeblock to evaluate.   </par>
 *      <xArguments> = arguments passed to a called function/procedure or to
 *      a codeblock.   </par>
 *  $RETURNS$
 *      A value that was returned from called function.   </par>
 *  $DESCRIPTION$
 *      This function can be called either by the harbour compiler or by user.
 *      The compiler always passes the item of IT_SYMBOL type that stores the
 *      name of procedure specified in DO <proc> WITH ... statement.   </par>
 *      If called procedure/function doesn't exist then a runtime error
 *      is generated.   </par>
 *      This function can be used as replacement of macro operator.
 *      It is also used internally to implement DO <proc> WITH <args...>
 *      In this case <xFuncProc> is of type HB_SYMB.   </par>
 *  $EXAMPLES$
 *      cbCode ={|x| MyFunc( x )}
 *      DO( cbCode, 1 )
 *
 *      cFunction := "MyFunc"
 *      xRetVal :=DO( cFunction, 2 )
 *
 *      Old style (slower):
 *      DO &cFunction WITH 3
 *  </fixed>
 *  $FILES$
 *      Library is rtl
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      __DBGVMVARLGET()
 *  $CATEGORY$
 *      Variable Management
 *  $ONELINER$
 *      Retrive a local variable from a procedure level
 *  $SYNTAX$
 *      __DBGVMVARLGET( <nProcLevel>, <nLocal> )
 *  $ARGUMENTS$
 *      <nProcLevel> Is the procedure level, same as used in ProcName()
 *      and ProcLine(), from which a local variable containts is going to
 *      be retrieved.   </par>
 *      <nLocal> Is the index of the local variable to retrieve.   </par>
 *  $RETURNS$
 *      The containts of a specific local variable   </par>
 *  $DESCRIPTION$
 *      This function is used from the debugger   </par>
 *  $FILES$
 *      Library is vm
 *  $END$
 */