SYSTEM

Function COMPILEFILE()

 COMPILEFILE(<sFileName>, <sFlags>, <@sError>) 	--> TRUE || FALSE

COMPILEFILE() compiles file <sFileName> with flags <sFlags> and returns TRUE in success, in other returns FALSE and <sError> contents error description.

  sFileName := FILEDIALOG("*.prg")
 err := ""
 lCF := COMPILEFILE(sFileName,,@err)
 if iCF
 qout("Compiller: OK")
 else
 qout("Compiller: error"+ err)
 endif
 

Function COMPILESTRING()

 COMPILESTRING(<sString>, <@sError>) 	--> <CodeBlock>

COMPILESTRING() compiles string <sString> to code block and returns it. If error was created, <sError> kept error description.

Sourse string can contents any CLIP construstions and command with the exlusion not static functions declaration. <sString> must begin with parameters descriptions (if it need) without functions/procedures declaration. See examples.

 /* source string */
 str:="
 parameters p1,p2
 qout(p1,p2)
 localfunc1(p1,p2)
 return p1+p2
 static function localfunc1(fp1,fp2)
 qout('called local function in string compiled block')
 return p1-p2"
 
 /* compile string */
 block:=COMPILESTRING(str,@err)
 if empty(err)
 x:=eval(block,1,2) 	// returns values  p1 and p2
 ? x 			// returns values  p1+p2
 else
 ? err 			// error description
 endif
 

Function DEFPATH()

 DefPath() --> <cPath>

Returns the path defined in SET DEFAULT command with ending PATH_DELIM or ":" symbol. If SET DEFAULT path isn't defined (empty), nothing is added.

 SET DEFAULT TO c:\FOX
 ? Set(_SET_DEFAULT) // 'c:\fox'
 ? DefPath()         // 'c:\fox\'
 
 SET DEFAULT TO D
 ? Set(_SET_DEFAULT) // 'D'
 ? DefPath()         // 'D:'

Function DIRECTORY()

 DIRECTORY(<cDirSpec>, [<cAttributes>]) --> aDirectory

DIRECTORY() is an environment function that returns information about files in the current or specified directory. It is similar to ADIR(), but returns a single array instead of adding values to a series of existing arrays passed by reference.

Use DIRECTORY() to perform actions on groups of files. In combination with AEVAL(), you can define a block that can be applied to all files matching the specified <cDirSpec>.

The header file, Directry.ch, in the \include subdirectory contains #defines for the subarray subscripts, so that the references to each file subarray are more readable.

DIRECTORY() Attributes
------------------------------------------------------------------------
Attribute    Meaning
------------------------------------------------------------------------
H            Include hidden files
S            Include system files
D            Include directories
V            Search for the DOS volume label and exclude all other files
------------------------------------------------------------------------

DIRECTORY() Subarray Structure
 ------------------------------------------------------------------------
 Position     Metasymbol     Directry.ch
 ------------------------------------------------------------------------
 1            cName          F_NAME
 2            cSize          F_SIZE
 3            dDate          F_DATE
 4            cTime          F_TIME
 5            cAttributes    F_ATTR
 ------------------------------------------------------------------------
 

 This example creates an array of information about files in
 the current directory and then lists the names of the files using
 AEVAL() and QOUT():
 
 #include "directry.ch"
 //
 aDirectory := DIRECTORY("*.*", "D")
 AEVAL( aDirectory, {|aFile| QOUT(aFile[F_NAME])} )

Function DOSERROR()

 DOSERROR([<nNewOsCode>]) --> nOsCode

DOSERROR() is an error function that returns the last DOS error code associated with an activation of the runtime error block. When a runtime error occurs, the DOSERROR() function is set to the current DOS error if the operation has an associated DOS error. The function value is retained until another runtime error occurs. If the failed operation has no associated DOS error, the DOSERROR() returns zero. With low- level file functions, FERROR() returns the same value as DOSERROR().

Through use of the optional <nNewOsCode>, you may customize to the reporting activation the returned value for any DOS error.

Function ERRORBLOCK()

 ERRORBLOCK([<bErrorHandler>]) --> bCurrentErrorHandler

ERRORBLOCK() is an error function that defines an error handler to execute whenever a runtime error occurs. Specify the error handler as a code block with the following form,

{ |<oError>| <expression list>,... }

where <oError> is an error object containing information about the error. Within the code block, messages can be sent to the error object to obtain information about the error. Returning true (.T.) from the error handling block retries the failed operation and false (.F.) resumes processing.

The error handling code block can be specified either as a list of expressions or as a call to a user-defined function. A call to a user- defined function is more useful since you can use xClipper control statements instead of expressions. This is particularly the case if there is a BEGIN SEQUENCE pending and you want to BREAK to the nearest RECOVER statement.

As this implies, error handling blocks can be used in combination with BEGIN SEQUENCE...END control structures. Within an error handling block, you handle device, low-level, and common errors that have a general recovery mechanism. If the operation needs specific error handling, define a BEGIN SEQUENCE then BREAK to the RECOVER statement, returning the error object for local processing. See the example below.

If no <bErrorHandler> has been specified using ERRORBLOCK() and a runtime error occurs, the default error handling block is evaluated. This error handler displays a descriptive message to the screen, sets the ERRORLEVEL() to 1, then QUITs the program.

Since ERRORBLOCK() returns the current error handling block, it is possible to specify an error handling block for an operation saving the current error handling block, then restore it after the operation has completed. Also, error handlers specified as code blocks, can be passed to procedures and user-defined functions, and RETURNed as values.

For more information on the structure and operations of error objects, refer to the Error class entry in this chapter and the "Error Handling Strategies" chapter in the Programming and Utilities Guide.

 This code fragment posts, and then calls an error handling
 block when there is an error within a BEGIN SEQUENCE construct:
 
 LOCAL bErrorHandler, bLastHandler, objErr
 bErrorHandler := { |oError| ;
 MyErrorHandler(oError) }
 //
 // Save current handler
 bLastHandler := ERRORBLOCK(bErrorHandler)
 //
 BEGIN SEQUENCE
 .
 . <operation statements>
 .
 // Receive error object from BREAK
 RECOVER USING oErrorInfo
 .
 . <recovery statements>
 .
 END
 ERRORBLOCK(bLastHandler)      // Restore handler
 RETURN
 
 FUNCTION MyErrorHandler( oError )
 //
 BREAK oError      // Return error object to RECOVER
 RETURN NIL

Function ERRORLEVEL()

 ERRORLEVEL([<nNewReturnCode>]) --> nCurrentReturnCode

ERRORLEVEL() is a dual purpose environment function. It returns the current xClipper return code and optionally sets a new return code. The return code is a value set by a child process so the parent process can test the termination state of the child process. Typically, the parent process is OS and the child process is an application program. Retrieve a return code with the OS ERRORLEVEL command or INT 21 Function 4Dh.

When a xClipper program terminates, the return code is set to 1 if the process ends with a fatal error. If the process ends normally, the return code is set to zero, or the last ERRORLEVEL() set in the program.

Typically, you would set a return code with ERRORLEVEL() to indicate an error state to the program that invoked the current xClipper program. In most cases this is the application batch file. Here you would test the return code using the OS ERRORLEVEL command. Refer to your OS manual for more information.

 This example saves the current xClipper return code, then
 sets a new value:
 
 nOldCode := ERRORLEVEL()      // Get current error level
 ERRORLEVEL(1)                 // Set new error level
 
 This example uses ERRORLEVEL() to set a return code that can
 be tested by the parent process:
 
 #define ERR_FILE_MISSING      255
 #define ERR_POST_INCOMPLETE   254
 //
 IF !FILE("Sysfile.dbf")
 @ 0, 0
 @ 1, 0
 @ 0, 0 SAY "Fatal error: System ;
 file is missing...quitting"
 ERRORLEVEL(ERR_FILE_MISSING)
 QUIT
 ENDIF

Function FERROR()

 FERROR() --> nErrorCode

FERROR() is a low-level file function that indicates a DOS error after a file function is used. These functions include FCLOSE(), FCREATE(), FERASE(), FOPEN(), FREAD(), FREADSTR(), and FRENAME(). FERROR() retains its value until the next execution of a file function.

Warning! This function allows low-level access to DOS files and devices. It should be used with extreme care and requires a thorough knowledge of the operating system.

 This example tests FERROR() after the creation of a binary
 file and displays an error message if the create fails:
 
 #include "Fileio.ch"
 //
 nHandle := FCREATE("Temp.txt", FC_NORMAL)
 IF FERROR() != 0
 ? "Cannot create file, DOS error ", FERROR()
 ENDIF

Function GETENV()

 GETENV(<cEnvironmentVariable>) --> cString

GETENV() is an environment function that lets you retrieve information from the OS environment into an application program. Typically, this is configuration information, including path names, that gives the location of files (database, index, label, or reports). This function is particularly useful for network environments.

 This example retrieves the current OS PATH setting, making it
 the current xClipper PATH:
 
 cPath := GETENV("PATH")
 SET PATH TO (cPath)
 
 This example uses environment variables to configure the
 specific locations of files.  When you set up a system, define
 environment variables that contain the location of various file types
 as well as the xCLIPPER environment variable.
 
 C>SET LOC_DBF=<database file path>
 C>SET LOC_NTX=<index file path>
 C>SET LOC_RPT=<report file path>
 
 In the configuration section of your application program, assign the
 contents of the environment variables to variables.  Then when you
 access a file, preface the reference with the path variable as
 follows:
 
 cDdfDirectory := GETENV("LOC_DBF")
 USE (cDdfDirectory + "Invoices")

Function LOAD()

 LOAD(<sFileName>) 	--> <CodeBlock>

LOAD() reades file <sFileName> and returns code block. <sFile> is the byte-code file "filename.po" or dynamic library "filename.so". After loading all not static functions are accessible to use.

  /* test.po */
 local a
 a := "Hello, world!"
 return a
 /////////////////////////
 
 block := LOAD("test.po")
 
 qout( eval(block) )	// --> Hello, world!
 

Function LOADBLOCK()

 LOADBLOCK(<sFileName>) 	--> <CodeBlock>

LOADBLOCK() loades byte-code file <sFileName> and returns code block. Byte-code file can be created:

clip -p filename.prg

The rules and structure of filename.prg must be corresponded are rules for string from function COMPILESTRING().

  block := LOADBLOCK("test.po")
 
 eval(block, "1", 2)
 

Function MEMORY()

 MEMORY(<nExp>) --> nKbytes

MEMORY() is an environment function that reports various states of free pool memory. (Free pool is the dynamic region of memory that stores character strings and executes RUN commands.)

 MEMORY() Argument Values
------------------------------------------------------------------------
Value     Meaning
------------------------------------------------------------------------
0         Estimated total space available for character values
1         Largest contiguous block available for character values
2         Area available for RUN commands
------------------------------------------------------------------------

 This example uses MEMORY() before a RUN command to determine
 if there is enough memory available to execute the external program:
 
 #define MEM_CHAR   0
 #define MEM_BLOCK   1
 #define MEM_RUN      2
 //
 IF MEMORY(MEM_RUN) >= 128
 RUN MYPROG
 ELSE
 ? "Not enough memory to RUN"
 BREAK
 ENDIF

Function NETERR()

 NETERR([<lNewError>]) --> lError

NETERR() is a network function. It is a global flag set by USE, USE...EXCLUSIVE, and APPEND BLANK in a network environment. It is used to test whether any of these commands have failed by returning true (.T.) in the following situations:

 NETERR() Causes
 ------------------------------------------------------------------------
 Command             Cause
 ------------------------------------------------------------------------
 USE                 USE EXCLUSIVE by another process
 USE...EXCLUSIVE     USE EXCLUSIVE or USE by another process
 APPEND BLANK        FLOCK() or RLOCK() of LASTREC() + 1 by another user
 ------------------------------------------------------------------------
 

NETERR() is generally applied in a program by testing it following a USE or APPEND BLANK command. If it returns false (.F.), you can perform the next operation. If the command is USE, you can open index files. If it is APPEND BLANK, you can assign values to the new record with a REPLACE or @...GET command. Otherwise, you must handle the error by either retrying the USE or APPEND BLANK, or terminating the current operation with a BREAK or RETURN.

 This example demonstrates typical usage of NETERR().  If the
 USE succeeds, the index files are opened and processing continues.
 If the USE fails, a message displays and control returns to the
 nearest BEGIN SEQUENCE construct:
 
 USE Customer SHARED NEW
 IF !NETERR()
 SET INDEX TO CustNum, CustOrders, CustZip
 ELSE
 ? "File is in use by another"
 BREAK
 ENDIF

Function NETNAME()

 NETNAME() --> cWorkstationName

 This example demonstrates the NETNAME() result when a
 workstation is started as a network node with a station identifier of
 "STATION 1":
 
 ? NETNAME()               // Result: STATION 1
 
 This example demonstrates the NETNAME() result when a
 workstation is started as a stand-alone unit:
 
 ? NETNAME()               // Result: ""

Function OS()

 OS() --> cOsName

OS() is an environment function that returns the name of the disk operating system under which the current workstation is operating. The name is returned in the form of the operating system name followed by the version number.

 This example uses OS() to report the operating system under
 which the current workstation is running:
 
 ? OS()                  // Result: LINUX

Function PCOUNT()

 PCOUNT() --> nLastArgumentPos

PCOUNT() reports the position of the last argument in the list of arguments passed when a procedure or user-defined function is invoked. This information is useful when determining whether arguments were left off the end of the argument list. Arguments skipped in the middle of the list are still included in the value returned.

To determine if a parameter did not receive a value, test it for NIL. Skipped parameters are uninitialized and, therefore, return NIL when accessed. Another method is to test parameters with the VALTYPE() function. This can establish whether the argument was passed and enforce the correct type at the same time. If a parameter was not supplied, a default value can be assigned.

For more information on passing parameters, refer to the "Basic Concepts" chapter in the Programming and Utilities Guide.

 This example is a user-defined function that opens a database
 file and uses PCOUNT() to determine whether the calling procedure
 passed the name of the database file to be opened.  If the name was
 not passed, OpenFile() asks for the name:
 
 FUNCTION OpenFile( cFile )
 IF PCOUNT() = 0
 ACCEPT "File to use: " TO cFile
 ENDIF
 USE (cFile)
 RETURN (NETERR())

Function PROCLINE()

 PROCLINE([<nActivation>]) --> nSourceLine

PROCLINE() queries the xClipper activation stack to determine the last line executed in a currently executing procedure, user-defined function, or code block. The activation stack is an internal structure that maintains a record of each procedure, function, or code block invocation. A line number is relative to the beginning of the original source file. A line includes a comment, blank line, preprocessor directive, and a continued line. A multistatement line is counted as a single line.

For the current activation, PROCLINE() returns the number of the current line. For a previous activation, PROCLINE() returns the number of the line that invoked the procedure or a user-defined function in which PROCLINE() is invoked.

If the activation being queried is a code block evaluation, PROCLINE() returns the line number of the procedure in which the code block was originally defined.

PROCLINE() is used with PROCNAME() to report debugging information.

 In this example, PROCLINE() returns the line number for the
 current activation, followed by the line number of the previous
 activation:
 
 // First line of source file
 MyFunction()
 RETURN
 
 FUNCTION MyFunction
 ? PROCLINE()      // Result: 6 (current activation)
 ? PROCLINE(1)      // Result: 2 (previous activation)
 RETURN NIL

Function PROCNAME()

 PROCNAME([<nActivation>]) --> cProcedureName

PROCNAME() queries the xClipper activation stack to determine the name of a currently executing procedure, user-defined function, or code block. The activation stack is an internal structure that maintains a record of each procedure, function, or code block invocation.

For the current activation, PROCNAME() returns the name of the current procedure or user-defined function. For a previous activation, PROCNAME() returns the name of the procedure or user-defined function that invoked the current procedure.

If the activation being queried is a code block evaluation, PROCNAME() returns the name of the procedure or user-defined function that defined the code block, preceded by "b". If the activation being queried is a memvar, PROCNAME() returns the name preceded by "M->".

PROCNAME() is used with PROCLINE() to report debugging information.

 This example is a user-defined function you can call during a
 debugging phase of program development in order to display the
 activation stack with line numbers:
 
 FUNCTION ListStack( cMessage )
 LOCAL nActivation := 1
 ? cMessage
 DO WHILE !(PROCNAME(nActivation) == "")
 ? "Called from:", PROCNAME(nActivation),;
 "(" + LTRIM(STR(PROCLINE(nActivation))) + ")"
 nActivation++
 ENDDO
 QUIT
 RETURN NIL

Function QOUT()

 QOUT([<exp list>]) --> NIL
 QQOUT([<exp list>]) --> NIL

QOUT() and QQOUT() are console functions. These are the functional primitives that create the ? and ?? commands, respectively. Like the ? and ?? commands, they display the results of one or more expressions to the console. QOUT() outputs carriage return and line feed characters before displaying the results of <exp list>. QQOUT() displays the results of <exp list> at the current ROW() and COL() position. When QOUT() and QQOUT() display to the console, ROW() and COL() are updated. If SET PRINTER is ON, PROW() and PCOL() are updated instead. If <exp list> is specified, both QOUT() and QQOUT() display a space between the results of each expression.

You can use QOUT() and QQOUT() for console display within an expression. This is particularly useful for blocks, iteration functions such as AEVAL() and DBEVAL(), and in a list of statements in the output pattern of a user-defined command definition.

  This example uses QOUT() with AEVAL() to list the contents of
 a literal array to the console:
 
 LOCAL aElements := { 1, 2, 3, 4, 5 }
 AEVAL(aElements, { |element| QOUT(element) })
 
 

Function SET()

 SET(<nSpecifier>, [<expNewSetting>], [<lOpenMode>]) --> CurrentSetting

SET() is a system function that lets you inspect or change the values of the xClipper system settings. For information on the meaning and legal values for a particular setting, refer to the associated command or function.

Use a manifest constant to specify the setting to be inspected or changed. These constants are defined in a header file called Set.ch. This header file should be included at the top of any source file which uses SET().

Set.ch also defines a constant called _SET_COUNT. This constant is equal to the number of settings that can be changed or inspected with SET(), allowing the construction of a generic function that preserves all settings (see example below).

Note: The numeric values of the manifest constants in Set.ch are version-dependent and should never be used directly; the manifest constants should always be used.

If <nSpecifier> or <expNewSetting> is invalid, the call to SET() is ignored.

 Set Values Defined in Set.ch
 ------------------------------------------------------------------------
 Constant            Value Type     Associated Command or Function
 ------------------------------------------------------------------------
 _SET_EXACT          Logical        SET EXACT
 _SET_FIXED          Logical        SET FIXED
 _SET_DECIMALS       Numeric        SET DECIMALS
 _SET_DATEFORMAT     Character      SET DATE
 _SET_EPOCH          Numeric        SET EPOCH
 _SET_PATH           Character      SET PATH
 _SET_DEFAULT        Character      SET DEFAULT
 _SET_EXCLUSIVE      Logical        SET EXCLUSIVE
 _SET_SOFTSEEK       Logical        SET SOFTSEEK
 _SET_UNIQUE         Logical        SET UNIQUE
 _SET_DELETED        Logical        SET DELETED
 _SET_CANCEL         Logical        SETCANCEL()
 _SET_DEBUG          Numeric        ALTD()
 _SET_COLOR          Character      SETCOLOR()
 _SET_CURSOR         Numeric        SETCURSOR()
 _SET_CONSOLE        Logical        SET CONSOLE
 _SET_ALTERNATE      Logical        SET ALTERNATE
 _SET_ALTFILE        Character      SET ALTERNATE TO
 _SET_DEVICE         Character      SET DEVICE
 _SET_PRINTER        Logical        SET PRINTER
 _SET_PRINTFILE      Character      SET PRINTER TO
 _SET_MARGIN         Numeric        SET MARGIN
 _SET_BELL           Logical        SET BELL
 _SET_CONFIRM        Logical        SET CONFIRM
 _SET_ESCAPE         Logical        SET ESCAPE
 _SET_INSERT         Logical        READINSERT()
 _SET_EXIT           Logical        READEXIT()
 _SET_INTENSITY      Logical        SET INTENSITY
 _SET_SCOREBOARD     Logical        SET SCOREBOARD
 _SET_DELIMITERS     Logical        SET DELIMITERS
 _SET_DELIMCHARS     Character      SET DELIMITERS TO
 _SET_WRAP           Logical        SET WRAP
 _SET_MESSAGE        Numeric        SET MESSAGE
 _SET_MCENTER        Logical        SET MESSAGE
 ------------------------------------------------------------------------
 

Note: _SET_EXTRAFILE and _SET_SCROLLBREAK have no corresponding commands. _SET_EXTRAFILE lets you specify an additional alternate file, and _SET_SCROLLBREAK lets you toggle the interpretation of Ctrl+S.

 In this example a user-defined function preserves or restores
 all global settings.  This function might be used on entry to a
 subsystem to ensure that the subsystem does not affect the state of
 the program that called it:
 
 #include "Set.ch"
 //
 
 FUNCTION SetAll( aNewSets )
 LOCAL aCurrentSets[_SET_COUNT], nCurrent
 IF ( aNewSets != NIL )   // Set new and return current
 FOR nCurrent := 1 TO _SET_COUNT
 aCurrentSets[nCurrent] := ;
 SET(nCurrent, aNewSets[nCurrent])
 NEXT
 ELSE         // Just return current
 FOR nCurrent := 1 TO _SET_COUNT
 aCurrentSets[nCurrent] := SET(nCurrent)
 NEXT
 ENDIF
 RETURN (aCurrentSets)

Function SLEEP()

 SLEEP(<nSec>) 	--> NIL

SLEEP() makes the program sleep until seconds have elapsed.

  do while 100
 ? time()
 SLEEP(10.50)
 enddo
 

Function SYSCMD()

 SYSCMD(<sCmd>, <sStdin>, @<sResult>, @<sError>) 	--> <nResultCode>

SYSCMD() runs system command <sCmd> and sends to this command string <sStdin> to a standart input. All output stream will be write to <sResult>, and all error stream to <sError>.

<sResult> and <sError> can't be constants.

  err_buf1=space(0)
 res_buf1=space(0)
 
 err_buf2=space(0)
 res_buf2=space(0)
 
 result_code1 := SYSCMD("ls -l", "", @res_buf1, @err_buf1)
 
 ? result_code1
 ? res_buf1
 ? err_bus1
 ?
 
 result_code2 := SYSCMD("grep test ", res_buf1, @res_buf2, @err_buf2)
 
 ? result_code2
 ? res_buf2
 ? err_bus2
 ?
 

Function ULIMIT()

 ULIMIT(<sResName>, <vLimitVal>) 	--> <vOldLimitValue>

ULIMIT() sets new limit value <vLimitVal> to use system resource with name <sResName> and returns old value for this resource.

The list of resource names see in ulimit.ch

  #include <ulimit.ch>
 
 /* set the max size for stack */
 
 ? ULIMIT( ULIMIT_STACK, 1024 )
 

Function VERSION()

 VERSION() --> cVersion

VERSION() is an environment function that returns the version of the xClipper library, EXTEND.LIB.