From db79b1ec08d551b413d5b9682412b8f0c8657d4f Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Tue, 29 Feb 2000 22:14:09 +0000 Subject: [PATCH] 20000229-23:13 GMT+1 Victor Szakats --- harbour/ChangeLog | 35 + harbour/doc/en/array.txt | 554 ++++++ harbour/doc/en/binnum.txt | 478 +++++ harbour/doc/en/browse.txt | 346 ++++ harbour/doc/en/command.txt | 406 ++++ harbour/doc/en/dir.txt | 203 ++ harbour/doc/en/error.txt | 43 + harbour/doc/en/file.txt | 849 +++++++++ harbour/doc/en/ht_class.txt | 88 + harbour/doc/en/ht_conv.txt | 261 +++ harbour/doc/en/ht_dbf.txt | 134 ++ harbour/doc/en/ht_doc.txt | 283 +++ harbour/doc/en/ht_file.txt | 96 + harbour/doc/en/ht_gt.txt | 479 +++++ harbour/doc/en/ht_str.txt | 61 + harbour/doc/en/hvm.txt | 360 ++++ harbour/doc/en/input.txt | 384 ++++ harbour/doc/en/license.txt | 42 + harbour/doc/en/memo.txt | 81 + harbour/doc/en/menu.txt | 385 ++++ harbour/doc/en/misc.txt | 197 ++ harbour/doc/en/nation.txt | 108 ++ harbour/doc/en/objfunc.txt | 651 +++++++ harbour/doc/en/rdd.txt | 3541 +++++++++++++++++++++++++++++++++++ harbour/doc/en/readme.txt | 106 ++ harbour/doc/en/set.txt | 683 +++++++ harbour/doc/en/string.txt | 717 +++++++ harbour/doc/en/tclass.txt | 63 + harbour/doc/en/terminal.txt | 556 ++++++ harbour/doc/en/tgetlist.txt | 62 + harbour/doc/en/tlabel.txt | 75 + harbour/doc/en/treport.txt | 92 + harbour/doc/en/var.txt | 737 ++++++++ 33 files changed, 13156 insertions(+) create mode 100644 harbour/doc/en/array.txt create mode 100644 harbour/doc/en/binnum.txt create mode 100644 harbour/doc/en/browse.txt create mode 100644 harbour/doc/en/command.txt create mode 100644 harbour/doc/en/dir.txt create mode 100644 harbour/doc/en/error.txt create mode 100644 harbour/doc/en/file.txt create mode 100644 harbour/doc/en/ht_class.txt create mode 100644 harbour/doc/en/ht_conv.txt create mode 100644 harbour/doc/en/ht_dbf.txt create mode 100644 harbour/doc/en/ht_doc.txt create mode 100644 harbour/doc/en/ht_file.txt create mode 100644 harbour/doc/en/ht_gt.txt create mode 100644 harbour/doc/en/ht_str.txt create mode 100644 harbour/doc/en/hvm.txt create mode 100644 harbour/doc/en/input.txt create mode 100644 harbour/doc/en/license.txt create mode 100644 harbour/doc/en/memo.txt create mode 100644 harbour/doc/en/menu.txt create mode 100644 harbour/doc/en/misc.txt create mode 100644 harbour/doc/en/nation.txt create mode 100644 harbour/doc/en/objfunc.txt create mode 100644 harbour/doc/en/rdd.txt create mode 100644 harbour/doc/en/readme.txt create mode 100644 harbour/doc/en/set.txt create mode 100644 harbour/doc/en/string.txt create mode 100644 harbour/doc/en/tclass.txt create mode 100644 harbour/doc/en/terminal.txt create mode 100644 harbour/doc/en/tgetlist.txt create mode 100644 harbour/doc/en/tlabel.txt create mode 100644 harbour/doc/en/treport.txt create mode 100644 harbour/doc/en/var.txt diff --git a/harbour/ChangeLog b/harbour/ChangeLog index f0e4a74c6e..1a05901dac 100644 --- a/harbour/ChangeLog +++ b/harbour/ChangeLog @@ -1,3 +1,38 @@ +20000229-23:13 GMT+1 Victor Szakats + + doc/en/array.txt + + doc/en/binnum.txt + + doc/en/browse.txt + + doc/en/command.txt + + doc/en/dir.txt + + doc/en/error.txt + + doc/en/file.txt + + doc/en/ht_class.txt + + doc/en/ht_conv.txt + + doc/en/ht_dbf.txt + + doc/en/ht_doc.txt + + doc/en/ht_file.txt + + doc/en/ht_gt.txt + + doc/en/ht_str.txt + + doc/en/hvm.txt + + doc/en/input.txt + + doc/en/license.txt + + doc/en/memo.txt + + doc/en/menu.txt + + doc/en/misc.txt + + doc/en/nation.txt + + doc/en/objfunc.txt + + doc/en/rdd.txt + + doc/en/readme.txt + + doc/en/set.txt + + doc/en/string.txt + + doc/en/tclass.txt + + doc/en/terminal.txt + + doc/en/tgetlist.txt + + doc/en/tlabel.txt + + doc/en/treport.txt + + doc/en/var.txt + + English documentation readded separated from the source files. + 20000229-22:00 GMT+1 Victor Szakats * source/rtl/* source/rdd/dbcmd.c diff --git a/harbour/doc/en/array.txt b/harbour/doc/en/array.txt new file mode 100644 index 0000000000..0171fa42df --- /dev/null +++ b/harbour/doc/en/array.txt @@ -0,0 +1,554 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * ARRAY() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Create an uninitialized array of specified length + * $SYNTAX$ + * ARRAY( [, ...]) --> aArray + * $ARGUMENTS$ + * is the number of elements in the specified dimension. + * $RETURNS$ + * ARRAY() returns an array of specified dimensions. + * $DESCRIPTION$ + * This function returns an uninitialized array with the length of + * . Nested arrays are uninitialized within the same array + * pointer reference if additional parameters are specified. + * Establishing a memory variable with the same name as the array + * may destroy the original array and release the entire contents of + * the array. This depends, of course, on the data storage type of + * either the array or the variable with the same name as the array. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL aArray:=Array(10) + * LOCAL x:=1 + * FOR x:=1 to LEN(aArray) + * aArray[x]:=Array(x) + * NEXT + * Return Nil + * $STATUS$ + * R + * $SEEALSO$ + * AADD(),ADEL(),AFILL(),AINS() + * $COMPLIANCE$ + * This function is CA-CLIPPER Compliant in all Cases, except + * that arrays in Harbour can have an unlimited number of dimensions, + * while Clipper has a limit of 4096 array elements. + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * AADD() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Dynamically add an element to an array + * $SYNTAX$ + * AADD([, ]) --> Value + * $ARGUMENTS$ + * The name of an array + * + * Element to add to array + * $RETURNS$ + * The value of if specified, otherwise this function + * returns a NIL value. + * $DESCRIPTION$ + * This function dynamically increases the length of the array + * named by one element and stores the value of to + * that newly created element. + * may be an array reference pointer, which in turn may be + * stored to an array's subscript position. + * $EXAMPLES$ + * LOCAL aArray:={} + * AADD(aArray,10) + * FOR x:=1 to 10 + * AADD(aArray,x) + * NEXT + * $STATUS$ + * R + * $SEEALSO$ + * AINS(),ASIZE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ASIZE() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Adjust the size of an array + * $SYNTAX$ + * ASIZE(, ) --> aTarget + * $ARGUMENTS$ + * Name of array to be dynamically altered + * + * Numeric value representing the new size of + * $RETURNS$ + * ASIZE() returns an array pointer reference to . + * $DESCRIPTION$ + * This function will dynamically increase or decrease the size + * of by adjusting the length of the array to subscript + * positions. + * If the length of the array is shortened, those former + * subscript positions are lost. If the length of the array is + * lengthened a NIL value is assigned to the new subscript position. + * $EXAMPLES$ + * aArray := { 1 } // Result: aArray is { 1 } + * ASIZE(aArray, 3) // Result: aArray is { 1, NIL, NIL } + * ASIZE(aArray, 1) // Result: aArray is { 1 } + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * If HB_COMPAT_C53 is defined, the function generates an Error, + * else it will return the array itself. + * $SEEALSO$ + * AADD(),ADEL(),AFILL(),AINS() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ATAIL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Returns the rightmost element of an array + * $SYNTAX$ + * ATAIL() --> Element + * $ARGUMENTS$ + * is the array. + * $RETURNS$ + * Atail() return the expression of the last element in the array. + * $DESCRIPTION$ + * This function return the value of the last element in the array named + * . This function does not alter the size of the array or any of + * the subscript values. + * $EXAMPLES$ + * LOCAL array:= {"Harbour", "is", "Supreme", "Power"} + * ? ATAIL(aArray) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * LEN(),ARRAY(),ASIZE(),AADD() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * AINS() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Insert a NIL value at an array subscript position. + * $SYNTAX$ + * AINS(, ) --> aTarget + * $ARGUMENTS$ + * Array name. + * + * Subscript position in + * $RETURNS$ + * AINS() returns a array pointer reference to . + * $DESCRIPTION$ + * This function inserts a NIL value in the array named + * at the th position. + * All array elements starting with the th position will be + * shifted down one subscript position in the array list and the last + * item in the array will be removed completely. In other words, if an + * array element were to be inserted at the fifth subscript position, + * the element previously in the fifth position would now be located + * at the sixth position. The length of the array will remain + * unchanged. + * $EXAMPLES$ + * LOCAL aArray:={"Harbour","is","Power!","!!!"} + * AINS(aArray,4) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * AADD(),ACOPY(),ADEL(),AEVAL(),AFILL(),ASIZE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ADEL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Delete an element form an array. + * $SYNTAX$ + * ADEL(, ) --> aTarget + * $ARGUMENTS$ + * Name of array from which an element is to be removed. + * + * Subscript of the element to be removed. + * $RETURNS$ + * ADEL() Returns an array pointer reference to . + * $DESCRIPTION$ + * This function deletes the element found at subscript + * position in the array . All elements in the array + * below the given subscript position will move up + * one position in the array. In other words, what was formerly the + * sixth subscript position will become the fifth subscript position. + * The length of the array will remain unchanged,as the last + * element in the array will become a NIL data type. + * $EXAMPLES$ + * LOCAL aArray + * aArray := { "Harbour","is","Power" } // Result: aArray is + * + * ADEL(aArray, 2) // Result: aArray is + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * ACOPY(),AINS(),AFILL() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * AFILL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Fill an array with a specified value + * $SYNTAX$ + * AFILL(, , + * [], []) --> aTarget + * $ARGUMENTS$ + * Name of array to be filled. + * + * Expression to be globally filled in + * + * Subscript starting position + * + * Number of subscript to be filled + * $RETURNS$ + * AFILL() returns an array pointer to . + * $DESCRIPTION$ + * This function will fill each element of an array named with + * the value . If specified, denotes the beginning + * element to be filled and the array elements will continue to be + * filled for positions. If Not specified, the value of + * will be 1, and the value of will be the value + * of LEN(); thus, all subscript positions in the array + * will be filled with the value of . + * This function will work on only a single dimension of . + * If there are array pointer references within a subscript , + * those values will be lost, since this function will overwrite those + * values with new values. + * $EXAMPLES$ + * LOCAL aTest:={Nil,0,1,2} + * Afill(aTest,5) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * AADD(),AEVAL(),DBSTRUCT(),DIRECTORY() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ASCAN() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Scan array elements for a specified condition + * $SYNTAX$ + * ASCAN(, , + * [], []) --> nStoppedAt + * $ARGUMENTS$ + * Name of array to be scanned. + * + * Expression to search for in + * + * Beginning subscript position at which to start the + * search. + * + * Number of elements to scan with . + * position. If this argument is not specified, all elements from the + * $RETURNS$ + * A numeric value of subscript position where + * was found. + * $DESCRIPTION$ + * This function scan the content of array named for the + * value of . The return value is the position in the + * array in which was found. If it was not + * found, the return value will be 0. + * If specified, the beginning subscript position at which to start + * scanning may be set with the value passed as . The default + * is 1. + * If specified, the number of array elements to scan may be set with + * the value passed as . The default is the number of elements + * in the array . + * If is a code block, the operation of the function is + * slightly different. Each array subscript pointer reference is passed + * to the code block to be evaluated. The scanning routine will + * continue until the value obtained from the code block is a logical + * true (.T.) or until the end of the array has been reached. + * $EXAMPLES$ + * aDir:=Directory("*.prg") + * AScan(aDir,,,{|x,y| x[1]="Test.prg"}) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is not CA-Clipper compatible. Clipper ASCAN() is + * affected by the SET EXACT ON/OFF Condition + * $SEEALSO$ + * ACOMP(),AEVAL() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * AEVAL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Evaluated the subscript element of an array + * $SYNTAX$ + * AEVAL(, , + * [], []) --> aArray + * $ARGUMENTS$ + * Is the array to be evaluated. + * + * Is a code block to evaluate for each element processed. + * + * The beginning array element to evaluate. + * + * The number of elements to process. + * $RETURNS$ + * AEVAL() returns an array pointer reference. + * $DESCRIPTION$ + * This function will evaluate and process the subscript elements + * in . A code block passed as defines the + * operation to be executed on each element of the array. All + * elements in will be evaluated unless specified by a + * beginning subscript position in for elements. + * + * Two parameters are passed to the code block . The + * individual elements in an array are the first parameter and the + * subscript position is the second. + * + * AEVAL() does not replace a FOR...NEXT loop for processing arrays. + * If an array is an autonomous unit, AEVAL() is appropriate. If the + * array is to be altered or if elements are to be reevaluated, a + * FOR...NEXT loop is more appropriate. + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * EVAL(),DBEVAL() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ACOPY() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Copy elements from one array to another + * $SYNTAX$ + * ACOPY(, , + * [], [], []) --> aTarget + * $ARGUMENTS$ + * is the array to copy elements from. + * + * is the array to copy elements to. + * + * is the beginning subscript position to copy from + * + * the number of subscript elements to copy from . + * + * the starting subscript position in to copy + * elements to. + * $RETURNS$ + * ACOPY() returns an array pointer reference + * $DESCRIPTION$ + * This function copies array elements from to . + * is the beginning element to be copied from ; the + * default is 1. + * is the number of elements to be copied from ; the + * default is the entire array. + * is the subscript number in the target array,, + * to which array elements are to be copied; the default is 1 + * This function will copy all data types in to . + * If an array element in is a pointer reference to another + * array, that array pointer will be copied to ; not all + * subdimensions will be copied from one array to the next. This must + * be accomplished via the ACLONE() function. + * + * Note + * If array is larger then , array elements will + * start copying at and continue copying until the end of + * array is reached. The ACOPY() function doesn't append + * subscript positions to the target array, the size of the target + * array remains constant. + * $EXAMPLES$ + * LOCAL nCount := 2, nStart := 1, aOne, aTwo + * aOne := {"HABOUR"," is ","POWER"} + * aTwo := {"CLIPPER"," was ","POWER"} + * ACOPY(aOne, aTwo, nStart, nCount) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * ACLONE(),ADEL(),AEVAL(),AFILL(),AINS(),ASORT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ACLONE() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Duplicate a multidimensional array + * $SYNTAX$ + * ACLONE() --> aDuplicate + * $ARGUMENTS$ + * Name of the array to be cloned. + * $RETURNS$ + * ACLONE() A new array pointer reference complete with nested array + * values. + * $DESCRIPTION$ + * This function makes a complete copy of the array expressed as + * and return a cloned set of array values.This provides + * a complete + * $EXAMPLES$ + * This example creates an array then duplicates it using + * ACLONE(). The first array is then altered, but the duplicate copy is + * unaffected: + * + * LOCAL aOne, aTwo + * aOne := {"Harbour"," is ","POWER"} + * aTwo := ACLONE(aOne) // Result: aTwo is {1, 2, 3} + * aOne[1] := "The Harbour Compiler" // Result: aOne is {99, 2, 3} + * // aTwo is still {1, 2, 3} + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * Clipper will return NIL if the parameter is not an array. + * $SEEALSO$ + * ACOPY(),ADEL(),AINS(),ASIZE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ASORT() + * $CATEGORY$ + * Array + * $ONELINER$ + * Sort an array + * $SYNTAX$ + * ASORT( , [], [], [] ) --> aArray + * $ARGUMENTS$ + * Array to be sorted. + * + * The first element to start the sort from, default is 1. + * + * Number of elements starting from to sort, default + * is all elements. + * + * Code block for sorting order, default is ascending order + * {| x, y | x < y }. The code block should accept two parameters and + * must return .T. if the sort is in order, .F. if not. + * $RETURNS$ + * ASORT() return reference to the now sorted or NIL if the + * passed is not an array. + * $DESCRIPTION$ + * ASORT() sort all or part of a given array. If is omitted, + * the function expect to be one dimensional array containing + * single data type (one of: Character, Date, Logical, Numeric) and + * sort this array in ascending order: Character are sorted by their + * ASCII value, Dates are sorted chronologically, Logical put .F. + * values before .T., Numeric are sorted by their value. + * + * If is specified, it is used to handle the sorting order. + * With each time the block is evaluate, two array elements are passed + * to the code block, and must return a logical value that + * state if those elements are in order (.T.) or not (.F.). Using + * this block you can sort multidimensional array, descending orders + * or even (but why would you want to do that) sort array that contain + * different data type. + * $EXAMPLES$ + * // sort numeric values in ascending order + * ASORT( { 3, 1, 4, 42, 5, 9 } ) // result: { 1, 3, 4, 5, 9, 42 } + * + * // sort character strings in descending lexical order + * aKeys := { "Ctrl", "Alt", "Delete" } + * bSort := {| x, y | UPPER( x ) > UPPER( y ) } + * ASORT( aKeys,,, bSort ) // result: { "Delete", "Ctrl", "Alt" } + * + * // sort two-dimensional array according to 2nd element of each pair + * aPair := { {"Sun",8}, {"Mon",1}, {"Tue",57}, {"Wed",-6} } + * ASORT( aPair,,, {| x, y | x[2] < y[2] } ) + * // result: { {"Wed",-6}, {"Mon",1}, {"Sun",8}, {"Tue",57} } + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * For speed we are checking the return type of the passed code block. + * This will result in a small incompatibility since the code block + * will be called one more time for the first logical element than in + * Clipper. But this is block calling frequency and order differs from + * Clipper anyway, since they use different sorting algorithm. + * $SEEALSO$ + * ASCAN(),EVAL(),SORT + * $END$ + */ + diff --git a/harbour/doc/en/binnum.txt b/harbour/doc/en/binnum.txt new file mode 100644 index 0000000000..5282e62f52 --- /dev/null +++ b/harbour/doc/en/binnum.txt @@ -0,0 +1,478 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 2000 Chen Kedem + * Documentation for all functions + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * BIN2W() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert unsigned short encoded bytes into Harbour numeric + * $SYNTAX$ + * BIN2W( ) --> nNumber + * $ARGUMENTS$ + * is a character string that contain 16 bit encoded unsigned + * short integer (least significant byte first). The first two bytes + * are taken into account, the rest if any are ignored. + * $RETURNS$ + * BIN2W() return numeric integer (or 0 if is not a string). + * $DESCRIPTION$ + * BIN2W() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. BIN2W() take two bytes of encoded + * 16 bit unsigned short integer and convert it into standard Harbour + * numeric value. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * BIN2W() is the opposite of W2BIN() + * $EXAMPLES$ + * // Show header length of a DBF + * FUNCTION main() + * LOCAL nHandle, cBuffer := space( 2 ) + * nHandle := fopen( "test.dbf" ) + * IF nHandle > 0 + * fseek( nHandle, 8 ) + * fread( nHandle, @cBuffer, 2 ) + * ? "Length of DBF header in bytes:", BIN2W( cBuffer ) + * fclose( nHandle ) + * ELSE + * ? "Can not open file" + * ENDIF + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BIN2W() works exactly like CA-Clipper's BIN2W() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I(),BIN2L(),BIN2U(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(), + * FREAD() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BIN2I() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert signed short encoded bytes into Harbour numeric + * $SYNTAX$ + * BIN2I( ) --> nNumber + * $ARGUMENTS$ + * is a character string that contain 16 bit encoded signed + * short integer (least significant byte first). The first two bytes + * are taken into account, the rest if any are ignored. + * $RETURNS$ + * BIN2I() return numeric integer (or 0 if is not a string). + * $DESCRIPTION$ + * BIN2I() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. BIN2I() take two bytes of encoded + * 16 bit signed short integer and convert it into standard Harbour + * numeric value. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * BIN2I() is the opposite of I2BIN() + * $EXAMPLES$ + * // Show DBF last update date + * FUNCTION main() + * LOCAL nHandle, cYear, cMonth, cDay + * nHandle := fopen( "test.dbf" ) + * IF nHandle > 0 + * fseek( nHandle, 1 ) + * cYear := cMonth := cDay := " " + * fread( nHandle, @cYear , 1 ) + * fread( nHandle, @cMonth, 1 ) + * fread( nHandle, @cDay , 1 ) + * ? "Last update:", BIN2I( cYear ), BIN2I( cMonth ), BIN2I( cDay ) + * fclose( nHandle ) + * ELSE + * ? "Can not open file" + * ENDIF + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BIN2I() works exactly like CA-Clipper's BIN2I() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2L(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(), + * FREAD() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BIN2L() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert signed long encoded bytes into Harbour numeric + * $SYNTAX$ + * BIN2L( ) --> nNumber + * $ARGUMENTS$ + * is a character string that contain 32 bit encoded signed + * long integer (least significant byte first). The first four bytes + * are taken into account, the rest if any are ignored. + * $RETURNS$ + * BIN2L() return numeric integer (or 0 if is not a string). + * $DESCRIPTION$ + * BIN2L() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. BIN2L() take four bytes of encoded + * 32 bit signed long integer and convert it into standard Harbour + * numeric value. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * BIN2L() is the opposite of L2BIN() + * $EXAMPLES$ + * // Show number of records in DBF + * FUNCTION main() + * LOCAL nHandle, cBuffer := space( 4 ) + * nHandle := fopen( "test.dbf" ) + * IF nHandle > 0 + * fseek( nHandle, 4 ) + * fread( nHandle, @cBuffer, 4 ) + * ? "Number of records in file:", BIN2L( cBuffer ) + * fclose( nHandle ) + * ELSE + * ? "Can not open file" + * ENDIF + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BIN2L() works exactly like CA-Clipper's BIN2L() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(), + * FREAD() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BIN2U() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert unsigned long encoded bytes into Harbour numeric + * $SYNTAX$ + * BIN2U( ) --> nNumber + * $ARGUMENTS$ + * is a character string that contain 32 bit encoded unsigned + * long integer (least significant byte first). The first four bytes + * are taken into account, the rest if any are ignored. + * $RETURNS$ + * BIN2U() return numeric integer (or 0 if is not a string). + * $DESCRIPTION$ + * BIN2U() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. BIN2U() take four bytes of encoded + * 32 bit unsigned long integer and convert it into standard Harbour + * numeric value. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * BIN2U() is the opposite of U2BIN() + * $EXAMPLES$ + * // Show number of records in DBF + * FUNCTION main() + * LOCAL nHandle, cBuffer := space( 4 ) + * nHandle := fopen( "test.dbf" ) + * IF nHandle > 0 + * fseek( nHandle, 4 ) + * fread( nHandle, @cBuffer, 4 ) + * ? "Number of records in file:", BIN2U( cBuffer ) + * fclose( nHandle ) + * ELSE + * ? "Can not open file" + * ENDIF + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BIN2U() is an XBase++ compatibility function and does not exist + * as a standard CA-Clipper 5.x function. + * + * This function is only visible if source/rtl/binnum.c was compiled + * with the HB_COMPAT_XPP flag. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I(),BIN2L(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD(),U2BIN(), + * FREAD() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * I2BIN() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert Harbour numeric into signed short encoded bytes + * $SYNTAX$ + * I2BIN( ) --> cBuffer + * $ARGUMENTS$ + * is a numeric value to convert (decimal digits are + * ignored). + * $RETURNS$ + * I2BIN() return two bytes character string that contain 16 bit + * encoded signed short integer (least significant byte first). + * $DESCRIPTION$ + * I2BIN() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. I2BIN() take a numeric integer + * value and convert it into two bytes of encoded 16 bit signed short + * integer. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * I2BIN() is the opposite of BIN2I() + * $EXAMPLES$ + * // Update DBF "last update" date + * #include "fileio.ch" + * FUNCTION main() + * LOCAL nHandle, cYear, cMonth, cDay + * use test + * ? "Original update date is:", lupdate() + * close + * nHandle := fopen( "test.dbf", FO_READWRITE ) + * IF nHandle > 0 + * fseek( nHandle, 1, ) + * cYear := I2BIN( 68 ) + * cMonth := I2BIN( 8 ) + * cDay := I2BIN( 1 ) + * fwrite( nHandle, cYear , 1 ) // write only the first byte + * fwrite( nHandle, cMonth, 1 ) + * fwrite( nHandle, cDay , 1 ) + * fclose( nHandle ) + * use test + * ? "New update date is:", lupdate() + * close + * ELSE + * ? "Can not open file" + * ENDIF + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * I2BIN() works exactly like CA-Clipper's I2BIN() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I,BIN2L(),BIN2U(),BIN2W(),L2BIN(),W2BIN(),WORD(),U2BIN(), + * FWRITE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * W2BIN() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert Harbour numeric into unsigned short encoded bytes + * $SYNTAX$ + * W2BIN( ) --> cBuffer + * $ARGUMENTS$ + * is a numeric value to convert (decimal digits are + * ignored). + * $RETURNS$ + * W2BIN() return two bytes character string that contain 16 bit + * encoded unsigned short integer (least significant byte first). + * $DESCRIPTION$ + * W2BIN() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. W2BIN() take a numeric integer + * value and convert it into two bytes of encoded 16 bit unsigned short + * integer. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * W2BIN() is the opposite of BIN2W() + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * W2BIN() is an XBase++ compatibility function and does not exist + * as a standard CA-Clipper 5.x function. + * + * This function is only visible if source/rtl/binnum.c was compiled + * with the HB_COMPAT_XPP flag. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I,BIN2L(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),WORD(),U2BIN(), + * FWRITE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * L2BIN() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert Harbour numeric into signed long encoded bytes + * $SYNTAX$ + * L2BIN( ) --> cBuffer + * $ARGUMENTS$ + * is a numeric value to convert (decimal digits are + * ignored). + * $RETURNS$ + * L2BIN() return four bytes character string that contain 32 bit + * encoded signed long integer (least significant byte first). + * $DESCRIPTION$ + * L2BIN() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. L2BIN() take a numeric integer + * value and convert it into four bytes of encoded 32 bit signed long + * integer. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * L2BIN() is the opposite of BIN2L() + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * L2BIN() works exactly like CA-Clipper's L2BIN() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I,BIN2L(),BIN2U(),BIN2W(),I2BIN(),W2BIN(),WORD(),U2BIN(), + * FWRITE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * U2BIN() + * $CATEGORY$ + * Binary conversion + * $ONELINER$ + * Convert Harbour numeric into unsigned long encoded bytes + * $SYNTAX$ + * U2BIN( ) --> cBuffer + * $ARGUMENTS$ + * is a numeric value to convert (decimal digits are + * ignored). + * $RETURNS$ + * U2BIN() return four bytes character string that contain 32 bit + * encoded unsigned long integer (least significant byte first). + * $DESCRIPTION$ + * U2BIN() is one of the low level binary conversion functions, those + * functions convert between Harbour numeric and a character + * representation of numeric value. U2BIN() take a numeric integer + * value and convert it into four bytes of encoded 32 bit unsigned long + * integer. + * + * You might ask what is the need for such functions, well, first of + * all it allow you to read/write information from/to a binary file + * (like extracting information from DBF header), it is also a useful + * way to share information from source other than Harbour (C for + * instance). + * + * U2BIN() is the opposite of BIN2U() + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * U2BIN() is an XBase++ compatibility function and does not exist + * as a standard CA-Clipper 5.x function. + * + * This function is only visible if source/rtl/binnum.c was compiled + * with the HB_COMPAT_XPP flag. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * BIN2I,BIN2L(),BIN2U(),BIN2W(),I2BIN(),L2BIN(),W2BIN(),WORD() + * FWRITE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * WORD() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts double to integer values. + * $SYNTAX$ + * WORD( ) --> + * $ARGUMENTS$ + * is a numeric double value. + * $RETURNS$ + * An integer in the range +-32767 + * $DESCRIPTION$ + * This function converts double values to integers to use + * within the CALL command + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * The Clipper NG states that WORD() will only work when used in CALL + * commands parameter list, otherwise it will return NIL, in Harbour + * it will work anywhere. + * $SEEALSO$ + * CALL + * $END$ + */ diff --git a/harbour/doc/en/browse.txt b/harbour/doc/en/browse.txt new file mode 100644 index 0000000000..f81278fad1 --- /dev/null +++ b/harbour/doc/en/browse.txt @@ -0,0 +1,346 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * BROWSE() documentation + * DBEDIT() documentation + * TBROWSEDB() documentation + * DBSKIPPER() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* TODO: put more comprehensive $EXAMPLES$. + DBEDIT() is a complex function, the doc I had made cover all the + parameters but probably not good enough for a new user that does + not know what this function is all about and how to use it. I am + not that good with the English language (and I did not want to + COPY the NG text) I suggest later some one should add to this + text. [chkedem] */ + +/* $DOC$ + * $FUNCNAME$ + * DBEDIT()* + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Browse records in a table + * $SYNTAX$ + * DBEDIT( [], [], [], [], [], + * [], [], [], + * [], [], + * [], [] ) --> lOk + * $ARGUMENTS$ + * coordinate for top row display. could range from 0 to + * MAXROW(), default is 0. + * + * coordinate for left column display. could range from + * 0 to MAXCOL(), default is 0. + * + * coordinate for bottom row display. could range + * from 0 to MAXROW(), default is MAXROW(). + * + * coordinate for right column display. could range + * from 0 to MAXCOL(), default is MAXCOL(). + * + * is an array of character expressions that contain + * database fields names or expressions to display in each column. + * If not specified, the default is to display all fields from the + * database in the current work area. + * + * is a name of a user defined function or a code block + * that would be called every time unrecognized key is been pressed or + * when there are no keys waiting to be processed and DBEDIT() goes + * into idle mode. If is a character string, it must + * contain root name of a valid user define function without + * parentheses. Both the user define function or the code block should + * accept two parameters: nMode, nCurrentColumn. Both should return + * a numeric value that correspond to one of the expected return codes + * (see table below for a list of nMode and return codes). + * + * is an optional picture. If + * is a character string, all columns would used this value as a + * picture string. If is an array, each element + * should be a character string that correspond to a picture string + * for the column with the same index. Look at the help for @...SAY + * to get more information about picture values. + * + * contain the header titles for each column, if this + * is a character string, all columns would have that same header, if + * this is an array, each element is a character string that contain + * the header title for one column. Header may be split to more than + * one line by placing semicolon (;) in places where you want to break + * line. If omitted, the default value for each column header is taken + * from or field name if was not specified. + * + * is an array that contain characters that draw + * the lines separating the headers and the fields data. Instead of an + * array you can use a character string that would be used to display + * the same line for all fields. Default value is a double line. + * + * is an array that contain characters that draw + * the lines separating displayed columns. Instead of an array you can + * use a character string that would be used to display the same line + * for all fields. Default value is a single line. + * + * is an array that contain characters that draw + * the lines separating the fields data area and the footing area. + * Instead of an array you can use a character string that would be + * used to display the same line for all footers. Default is to have to + * no footing separators. + * + * contain the footing to be displayed at the bottom + * of each column, if this is a character string, all columns would + * have that same footer, if this is an array, each element is a + * character string that contain the footer for one column. Footer may + * be split to more than one line by placing semicolon (;) in places + * where you want to break line. If omitted, no footer are displayed. + * $RETURNS$ + * DBEDIT() return .F. if there is no database in use or if the number + * of columns to display is zero, else DBEDIT() return .T. + * $DESCRIPTION$ + * DBEDIT() display and edit records from one or more work areas in + * a grid on screen. Each column is defined by element from + * and is the equivalent of one field. Each row is equivalent of one + * database record. + * + * Following are active keys that handled by DBEDIT(): + * --------------------------------------------------- + * + * Left - Move one column to the left (previous field) + * Right - Move one column to the right (next field) + * Up - Move up one row (previous record) + * Down - Move down one row (next record) + * Page-Up - Move to the previous screen + * Page-Down - Move to the next screen + * Ctrl Page-Up - Move to the top of the file + * Ctrl Page-Down - Move to the end of the file + * Home - Move to the leftmost visible column + * End - Move to the rightmost visible column + * Ctrl Left - Pan one column to the left + * Ctrl Right - Pan one column to the right + * Ctrl Home - Move to the leftmost column + * Ctrl End - Move to the rightmost column + * + * When is omitted, two more keys are active: + * + * Esc - Terminate BROWSE() + * Enter - Terminate BROWSE() + * + * When DBEDIT() execute it pass the following arguments: + * nMode and the index of current record in . If + * is omitted, the index number is the FIELD() number of the open + * database structure. + * + * DBEDIT() nMode could be one of the following: + * --------------------------------------------- + * + * DE_IDLE 0 DBEDIT() is idle, all movement keys have been + * handled. + * DE_HITTOP 1 Attempt to cursor past top of file. + * DE_HITBOTTOM 2 Attempt to cursor past bottom of file. + * DE_EMPTY 3 No records in work area, database is empty. + * DE_EXCEPT 4 Key exception. + * + * The user define function or code block must return a value that tell + * DBEDIT() what to do next. + * + * User function return codes: + * --------------------------- + * + * DE_ABORT 0 Abort DBEDIT(). + * DE_CONT 1 Continue DBEDIT() as is. + * DE_REFRESH 2 Force reread/redisplay of all data rows. + * + * The user function is called once in each of the following cases: + * - The database is empty. + * - The user try to move past top of file or past bottom file. + * - Key exception, the uses had pressed a key that is not handled by + * DBEDIT(). + * - The keyboard buffer is empty or a screen refresh had just occurred + * + * DBEDIT() is a compatibility function, it is superseded by the + * TBrowse class and there for not recommended for new applications. + * $EXAMPLES$ + * // Browse a file using default values + * USE Test + * DBEDIT() + * + * // TODO: put a longer example or point to a sample file + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * can take a code block value, this is a Harbour + * extension. + * + * CA-Clipper will throw an error if there's no database open, Harbour + * would return .F. + * + * CA-Clipper is buggy and will throw an error if the number of columns + * zero, Harbour would return .F. + * + * The CA-Clipper 5.2 NG state that the return value is NIL, this is + * wrong and should be read logical. + * + * There is an undocumented result code (3) from the user defined + * function in Clipper (both 87 and 5.x). This is an Append Mode which: + * "split the screen to allow data to be appended in windowed area". + * This mode is not supported by Harbour. + * $FILES$ + * Header files are dbedit.ch, inkey.ch + * $SEEALSO$ + * @...SAY,BROWSE(),TBrowse class,TRANSFORM() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BROWSE() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Browse a database file + * $SYNTAX$ + * BROWSE( [, , , ] ) --> lOk + * $ARGUMENTS$ + * coordinate for top row display. + * + * coordinate for left column display. + * + * coordinate for bottom row display. + * + * coordinate for right column display. + * $RETURNS$ + * BROWSE() return .F. if there is no database open in this work area, + * else it return .T. + * $DESCRIPTION$ + * BROWSE() is a general purpose database browser, without any + * thinking you can browse a file using the following keys: + * + * Left - Move one column to the left (previous field) + * Right - Move one column to the right (next field) + * Up - Move up one row (previous record) + * Down - Move down one row (next record) + * Page-Up - Move to the previous screen + * Page-Down - Move to the next screen + * Ctrl Page-Up - Move to the top of the file + * Ctrl Page-Down - Move to the end of the file + * Home - Move to the leftmost visible column + * End - Move to the rightmost visible column + * Ctrl Left - Pan one column to the left + * Ctrl Right - Pan one column to the right + * Ctrl Home - Move to the leftmost column + * Ctrl End - Move to the rightmost column + * Esc - Terminate BROWSE() + * + * On top of the screen you see a status line with the following + * indication: + * + * Record ###/### - Current record number / Total number of records. + * - There are no records, the file is empty. + * - You are in append mode at the bottom of file. + * - Current record is deleted. + * - You are at the top of file. + * + * You should pass whole four valid coordinate, if less than four + * parameters are passed to BROWSE() the coordinate are default to: + * 1, 0, MAXROW(), MAXCOL(). + * $EXAMPLES$ + * // this one shows you how to browse around + * USE Around + * BROWSE() + * $TESTS$ + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBEDIT()*,TBrowse class + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TBrowseDB() + * $CATEGORY$ + * TBrowse class + * $ONELINER$ + * Create a new TBrowse object to be used with database file + * $SYNTAX$ + * TBrowseDB( [], [], [], [] ) --> oBrowse + * $ARGUMENTS$ + * coordinate for top row display. + * + * coordinate for left column display. + * + * coordinate for bottom row display. + * + * coordinate for right column display. + * $RETURNS$ + * TBrowseDB() return new TBrowse object with the specified coordinate + * and a default :SkipBlock, :GoTopBlock and :GoBottomBlock to browse + * a database file. + * $DESCRIPTION$ + * TBrowseDB() is a quick way to create a TBrowse object along with + * the minimal support needed to browse a database. Note that the + * returned TBrowse object contain no TBColumn objects and you need + * to add column for each field by your self. + * $EXAMPLES$ + * for a good example, look at the source code for BROWSE() function + * at source/rtl/browse.prg + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * TBrowseDB() works exactly like CA-Clipper's TBrowseDB(). + * $SEEALSO$ + * BROWSE(),TBColumn class,TBrowse class,TBrowseNew() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * dbSkipper() + * $CATEGORY$ + * Data base + * $ONELINER$ + * Helper function to skip a database + * $SYNTAX$ + * dbSkipper( ) --> nSkipped + * $ARGUMENTS$ + * is the number of records to skip relative to current record. + * Positive number would try to move the record pointer forward, while + * a negative number would try to move the record pointer back + * records. + * $RETURNS$ + * dbSkipper() return the number of actual record skipped. + * $DESCRIPTION$ + * dbSkipper() is a helper function used in browse mechanism to skip + * a number of records while giving the caller indication about the + * actual records skipped. + * $EXAMPLES$ + * // open a file and find if we've got enough records in it + * USE MonthSales + * IF dbSkipper( 100 ) == 100 + * ? "Good work! You can party now" + * ELSE + * ? "Too bad, you should really work harder" + * ENDIF + * CLOSE + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * dbSkipper() is an XBase++ compatibility function and does not exist + * as a standard CA-Clipper 5.x function. + * + * This function is only visible if source/rtl/browdb.prg was compiled + * with the HB_COMPAT_XPP flag. + * $SEEALSO$ + * DBSKIP(),SKIP + * $END$ + */ diff --git a/harbour/doc/en/command.txt b/harbour/doc/en/command.txt new file mode 100644 index 0000000000..f2854997ec --- /dev/null +++ b/harbour/doc/en/command.txt @@ -0,0 +1,406 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 2000 Brian Hays + * Documentation for the commands + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $COMMANDNAME$ + * CLASS + * $CATEGORY$ + * Command + * $ONELINER$ + * Define a Class for Object Oriented Programming + * $SYNTAX$ + * CLASS [ ] + * $ARGUMENTS$ + * Name of the class to define. By tradition, Harbour + * classes start with "T" to avoid collisions with user- + * created classes. + * The Parent class to use for inheritance + * $DESCRIPTION$ + * CLASS creates a class from which you can create objects. + * Each Class is defined in a separate .PRG file dedicated to that + * purpose. You cannot create more than one class in a .PRG. + * After the CLASS command begins the definition, the DATA + * elements (also known as instance variables) and METHODS of the + * class are named. + * + * Classes can inherit from a single , but the chain of + * inheritance can extend to many levels. + * + * A program uses a Class by calling the Class Constructor, the + * New() method, to create an object. That object is usually assigned + * to a variable, which is used to access the DATA elements and + * methods. + * $EXAMPLES$ + * CLASS TBColumn + * + * DATA Block // Code block to retrieve data for the column + * DATA Cargo // User-definable variable + * DATA ColorBlock // Code block that determines color of data items + * DATA ColSep // Column separator character + * DATA DefColor // Array of numeric indexes into the color table + * DATA Footing // Column footing + * DATA FootSep // Footing separator character + * DATA Heading // Column heading + * DATA HeadSep // Heading separator character + * DATA Width // Column display width + * DATA ColPos // Temporary column position on screen + * + * METHOD New() // Constructor + * + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * CLASS is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * TClass(),Object Oriented Programming,DATA,METHOD + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * DATA + * $CATEGORY$ + * Command + * $ONELINER$ + * Define a DATA instance variable for the objects of a class + * $SYNTAX$ + * DATA [,] [ AS ] [ INIT ] + * $ARGUMENTS$ + * Name of the DATA + * Optional data type specification from the following: + * Character, Numeric, Date, Logical, Codeblock, Nil + * Optional initial value when creating a new object + * $DESCRIPTION$ + * DATA elements can also be thought of as the "properties" of an + * object. They can be of any data type, including codeblock. + * Once an object has been created, the DATA elements are referenced + * with the colon (:) as in MyObject:Heading := "Last name". + * Usually a class also defines methods to manipulate the DATA. + * + * You can use the "AS " clause to enforce that the DATA is + * maintained as a certain type. Otherwise it will take on the type of + * whatever value is first assigned to it. + * + * Use the "INIT " clause to initialize that DATA to + * whenever a new object is created. + * $EXAMPLES$ + * CLASS TBColumn + * + * DATA Block // Code block to retrieve data for the column + * DATA Cargo // User-definable variable + * DATA ColorBlock // Code block that determines color of data items + * DATA ColSep // Column separator character + * DATA DefColor // Array of numeric indexes into the color table + * DATA Footing // Column footing + * DATA FootSep // Footing separator character + * DATA Heading // Column heading + * DATA HeadSep // Heading separator character + * DATA Width // Column display width + * DATA ColPos // Temporary column position on screen + * + * METHOD New() // Constructor + * + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * DATA is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * Object Oriented Programming,CLASS,METHOD,CLASSDATA + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * CLASSDATA + * $CATEGORY$ + * Command + * $ONELINER$ + * Define a CLASSDATA variable for a class (NOT for an Object!) + * $SYNTAX$ + * CLASSDATA [,] [ AS ] [ INIT ] + * $ARGUMENTS$ + * Name of the DATA + * Optional data type specification from the following: + * Character, Numeric, Date, Logical, Codeblock, Nil + * Optional initial value at program startup + * $DESCRIPTION$ + * CLASSDATA variables can also be thought of as the "properties" of an + * entire class. Each CLASSDATA exists only once, no matter how many + * objects are created. A common usage is for a counter that is + * incremented whenever an object is created and decremented when one + * is destroyed, thus monitoring the number of objects in existance + * for this class. + * + * You can use the "AS " clause to enforce that the CLASSDATA is + * maintained as a certain type. Otherwise it will take on the type of + * whatever value is first assigned to it. + * + * Use the "INIT " clause to initialize that DATA to + * whenever the class is first used. + * $EXAMPLES$ + * CLASS TWindow + * DATA hWnd, nOldProc + * CLASSDATA lRegistered AS LOGICAL + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * CLASSDATA is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * Object Oriented Programming,CLASS,METHOD,DATA + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * METHOD + * $CATEGORY$ + * Command + * $ONELINER$ + * Declare a METHOD for a class in the class header + * $SYNTAX$ + * METHOD ( [] ) [ CONSTRUCTOR ] + * METHOD ( [] ) INLINE + * METHOD ( [] ) BLOCK + * METHOD ( [] ) EXTERN ([]) + * METHOD ( [] ) SETGET + * METHOD ( [] ) VIRTUAL + * METHOD ( [] ) OPERATOR + * METHOD ( [] ) CLASS + * $ARGUMENTS$ + * Name of the method to define + * Optional parameter list + * $DESCRIPTION$ + * Methods are "class functions" which do the work of the class. + * All methods must be defined in the class header between the + * CLASS and ENDCLASS commands. If the body of a method is not fully + * defined here, the full body is written below the ENDCLASS command + * using this syntax: + * + * METHOD ( [] ) CLASS + * + * Methods can reference the current object with the keyword "Self:" or + * its shorthand version "::". + * + * CLAUSES: + * + * CONSTRUCTOR Defines a special method Class Constructor method, + * used to create objects. This is usually the + * New() method. Constructors always return the new + * object. + * + * INLINE Fast and easy to code, INLINE lets you define the + * code for the method immediately within the definition + * of the Class. Any methods not declared INLINE or BLOCK + * must be fully defined after the ENDCLASS command. + * The following INLINE receives a parameter + * of Self. If you need to receive more parameters, use + * the BLOCK clause instead. + * + * BLOCK Use this clause when you want to declare fast 'inline' + * methods that need parameters. The first parameter to + * must be Self, as in: + * + * METHOD BLOCK {|Self,,, ...,|...} + * + * EXTERN If an external function does what the method needs, + * use this clause to make an optimized call to that + * function directly. + * + * SETGET For calculated Data. The name of the method can be + * manipulated like a Data element to Set or Get a value. + * + * VIRTUAL Methods that do nothing. Useful for Base classes where + * the child class will define the method's behavior, or + * when you are first creating and testing a Class. + * + * OPERATOR Operator Overloading for classes. + * See example TestOp.prg for details. + * + * CLASS + * Use this syntax only for defining a full method after + * the ENDCLASS command. + * $EXAMPLES$ + * CLASS TWindow + * DATA hWnd, nOldProc + * METHOD New( ) CONSTRUCTOR + * METHOD Capture() INLINE SetCapture( ::hWnd ) + * METHOD End() BLOCK { | Self, lEnd | If( lEnd := ::lValid(),; + * ::PostMsg( WM_CLOSE ),), lEnd } + * METHOD EraseBkGnd( hDC ) + * METHOD cTitle( cNewTitle ) SETGET + * METHOD Close() VIRTUAL + * ENDCLASS + * + * METHOD New( ) CLASS TWindow + * local nVar, cStr + * ... ... + * ... ... + * RETURN Self + * $STATUS$ + * R + * $COMPLIANCE$ + * METHOD is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * TClass(),Object Oriented Programming,DATA,CLASS,TestOp.prg + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * MESSAGE + * $CATEGORY$ + * Command + * $ONELINER$ + * Route a method call to another Method + * $SYNTAX$ + * MESSAGE METHOD ( [] ) + * MESSAGE () METHOD ( [] ) + * $ARGUMENTS$ + * The pseudo-method name to define + * The method to create and call when + * is invoked. + * Optional parameter list for the method + * $DESCRIPTION$ + * The MESSAGE command is a seldom-used feature that lets you re-route + * a call to a method with a different name. This can be necessary if + * a method name conflicts with a public function that needs to be + * called from within the class methods. + * + * For example, your app may have a public function called BeginPaint() + * that is used in painting windows. It would also be natural to have a + * Window class method called :BeginPaint() that the application can + * call. But within the class method you would not be able to call the + * public function because internally methods are based on static + * functions (which hide public functions of the same name). + * + * The MESSAGE command lets you create the true method with a different + * name (::xBeginPaint()), yet still allow the ::BeginPaint() syntax + * to call ::xBeginPaint(). This is then free to call the public + * function BeginPaint(). + * $EXAMPLES$ + * CLASS TWindow + * DATA hWnd, nOldProc + * METHOD New( ) CONSTRUCTOR + * MESSAGE BeginPaint METHOD xBeginPaint() + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * MESSAGE is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * METHOD,DATA,CLASS,Object Oriented Programming + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * ERROR HANDLER + * $CATEGORY$ + * Command + * $ONELINER$ + * Designate a method as an error handler for the class + * $SYNTAX$ + * ERROR HANDLER ( [] ) + * $ARGUMENTS$ + * Name of the method to define + * Optional parameter list + * $DESCRIPTION$ + * ERROR HANDLER names the method that should handle errors for the + * class being defined. + * $EXAMPLES$ + * CLASS TWindow + * ERROR HANDLER MyErrHandler() + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * ERROR HANDLER is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * Object Oriented Programming,ON ERROR,CLASS,METHOD,DATA + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * ON ERROR + * $CATEGORY$ + * Command + * $ONELINER$ + * Designate a method as an error handler for the class + * $SYNTAX$ + * ON ERROR ( [] ) + * $ARGUMENTS$ + * Name of the method to define + * Optional parameter list + * $DESCRIPTION$ + * ON ERROR is a synonym for ERROR HANDLER. + * It names the method that should handle errors for the + * class being defined. + * $EXAMPLES$ + * CLASS TWindow + * ON ERROR MyErrHandler() + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * ON ERROR is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * Object Oriented Programming,ERROR HANDLER,CLASS,METHOD,DATA + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * ENDCLASS + * $CATEGORY$ + * Command + * $ONELINER$ + * End the declaration of a class. + * $SYNTAX$ + * ENDCLASS + * $DESCRIPTION$ + * ENDCLASS marks the end of a class declaration. + * It is usually followed by the class methods that are not INLINE. + * $EXAMPLES$ + * CLASS TWindow + * DATA hWnd, nOldProc + * ENDCLASS + * $STATUS$ + * R + * $COMPLIANCE$ + * ON ERROR is a Harbour extension. + * $PLATFORMS$ + * All + * $SEEALSO$ + * Object Oriented Programming,CLASS,METHOD,DATA + * $END$ + */ diff --git a/harbour/doc/en/dir.txt b/harbour/doc/en/dir.txt new file mode 100644 index 0000000000..50e04e9456 --- /dev/null +++ b/harbour/doc/en/dir.txt @@ -0,0 +1,203 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * ADIR() documentation + * __DIR() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * __Dir()* + * $CATEGORY$ + * File management + * $ONELINER$ + * Display listings of files + * $SYNTAX$ + * __Dir( [] ) --> NIL + * $ARGUMENTS$ + * File mask to include in the function return. It could + * contain path and standard wildcard characters as supported by your + * OS (like * and ?). If contain no path, then SET DEFAULT + * path is used to display files in the mask. + * $RETURNS$ + * __Dir() always returns NIL. + * $DESCRIPTION$ + * If no is given, __Dir() display information about all + * *.dbf in the SET DEFAULT path, this information contain: file name, + * number of records, last update date and the size of each file. + * + * If is given, __Dir() list all files that match the mask + * with the following details: Name, Extension, Size, Date. + * + * DIR command is preprocessed into __Dir() function during compile + * time. + * + * __Dir() is a compatibility function, it is superseded by DIRECTORY() + * which return all the information in a multidimensional array. + * $EXAMPLES$ + * __Dir() // information for all DBF files in current directory + * + * __Dir( "*.dbf" ) // list all DBF file in current directory + * + * // list all PRG files in Harbour Run-Time library + * // for DOS compatible operating systems + * __Dir( "c:\harbour\source\rtl\*.prg" ) + * + * // list all files in the public section on a Unix like machine + * __Dir( "/pub" ) + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * DBF information: CA-Clipper display 8.3 file names, Harbour display + * the first 15 characters of a long file name if available. + * + * File listing: To format file names displayed we use something like: + * PadR( Name, 8 ) + " " + PadR( Ext, 3 ) + * CA-Clipper use 8.3 file name, with Harbour it would probably cut + * long file names to feet this template. + * $SEEALSO$ + * ADIR(),DIRECTORY(),SET DEFAULT,DIR + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DIR + * $CATEGORY$ + * Command + * $ONELINER$ + * Display listings of files + * $SYNTAX$ + * + * DIR [] + * $ARGUMENTS$ + * File mask to include in the function return. It could + * contain path and standard wildcard characters as supported by your + * OS (like * and ?). If contain no path, then SET DEFAULT + * path is used to display files in the mask. + * $RETURNS$ + * + * $DESCRIPTION$ + * If no is given, __Dir() display information about all + * *.dbf in the SET DEFAULT path, this information contain: file name, + * number of records, last update date and the size of each file. + * + * If is given, __Dir() list all files that match the mask + * with the following details: Name, Extension, Size, Date. + * + * DIR command is preprocessed into __Dir() function during compile + * time. + * + * __Dir() is a compatibility function, it is superseded by DIRECTORY() + * which return all the information in a multidimensional array. + * $EXAMPLES$ + * DIR // information for all DBF files in current directory + * + * dir "*.dbf" // list all DBF file in current directory + * + * // list all PRG files in Harbour Run-Time library + * // for DOS compatible operating systems + * Dir "c:\harbour\source\rtl\*.prg" + * + * // list all files in the public section on a Unix like machine + * Dir "/pub" + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * DBF information: CA-Clipper display 8.3 file names, Harbour display + * the first 15 characters of a long file name if available. + * + * File listing: To format file names displayed we use something like: + * PadR( Name, 8 ) + " " + PadR( Ext, 3 ) + * CA-Clipper use 8.3 file name, with Harbour it would probably cut + * long file names to feet this template. + * $SEEALSO$ + * ADIR(),DIRECTORY(),SET DEFAULT,__DIR()* + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ADIR() + * $CATEGORY$ + * Array + * $ONELINER$ + * Fill pre-defined arrays with file/directory information + * $SYNTAX$ + * ADIR( [], [], [], [], + * [], [] ) -> nDirEnries + * $ARGUMENTS$ + * File mask to include in the function return. It could + * contain path and standard wildcard characters as supported by your + * OS (like * and ?). If you omit or if contain + * no path, then the path from SET DEFAULT is used. + * + * Array to fill with file name of files that meet . + * Each element is a Character string and include the file name and + * extension without the path. The name is the long file name as + * reported by the OS and not necessarily the 8.3 uppercase name. + * + * Array to fill with file size of files that meet . + * Each element is a Numeric integer and include the file size in Bytes. + * Directories are always zero in size. + * + * Array to fill with file last modification date of files that + * meet . Each element is of type Date. + * + * Array to fill with file last modification time of files that + * meet . Each element is a Character string in the format + * HH:mm:ss. + * + * Array to fill with attribute of files that meet . + * Each element is a Character string, see DIRECTORY() for information + * about attribute values. If you pass array to , the function + * is going to return files with normal, hidden, system and directory + * attributes. If is not specified or with type other than + * Array, only files with normal attribute would return. + * $RETURNS$ + * ADIR() return the number of file entries that meet + * $DESCRIPTION$ + * ADIR() return the number of files and/or directories that match + * a specified skeleton, it also fill a series of given arrays with + * the name, size, date, time and attribute of those files. The passed + * arrays should pre-initialized to the proper size, see example below. + * In order to include hidden, system or directories must be + * specified. + * + * ADIR() is a compatibility function, it is superseded by DIRECTORY() + * which return all the information in a multidimensional array. + * $EXAMPLES$ + * LOCAL aName, aSize, aDate, aTime, aAttr, nLen, i + * nLen := ADIR( "*.JPG" ) // Number of JPG files in this directory + * IF nLen > 0 + * aName := Array( nLen ) // make room to store the information + * aSize := Array( nLen ) + * aDate := Array( nLen ) + * aTime := Array( nLen ) + * aAttr := Array( nLen ) + * FOR i = 1 TO nLen + * ? aName[i], aSize[i], aDate[i], aTime[i], aAttr[i] + * NEXT + * ELSE + * ? "This directory is clean from smut" + * ENDIF + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * is going to be fill with long file name and not necessarily + * the 8.3 uppercase name. + * + * $SEEALSO$ + * ARRAY(),DIRECTORY(),SET DEFAULT + * $END$ + */ diff --git a/harbour/doc/en/error.txt b/harbour/doc/en/error.txt new file mode 100644 index 0000000000..a137341edf --- /dev/null +++ b/harbour/doc/en/error.txt @@ -0,0 +1,43 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * ERRORSYS() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * ERRORSYS() + * $CATEGORY$ + * Error recovery + * $ONELINER$ + * Install default error handler + * $SYNTAX$ + * ERRORSYS() --> NIL + * $ARGUMENTS$ + * none. + * $RETURNS$ + * ERRORSYS() always return NIL. + * $DESCRIPTION$ + * ERRORSYS() is called upon startup by Harbour and install the default + * error handler. Normally you should not call this function directly, + * instead use ERRORBLOCK() to install your own error handler. + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * ERRORSYS() works exactly like CA-Clipper's ERRORSYS(). + * $SEEALSO$ + * ERRORBLOCK(),Error class + * $END$ + */ + diff --git a/harbour/doc/en/file.txt b/harbour/doc/en/file.txt new file mode 100644 index 0000000000..e48ce76ebd --- /dev/null +++ b/harbour/doc/en/file.txt @@ -0,0 +1,849 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 2000 Chen Kedem + * __TYPEFILE() / TYPE documentation + * + * Copyright 2000 Luiz Rafael Culik + * FOPEN() Documentation + * FCLOSE() Documentation + * FWRITE() Documentation + * FSEEK() Documentation + * FREAD() Documentation + * FILE() Documentation + * FREADSTR() Documentation + * FRENAME() Documentation + * FERROR() Documentation + * RENAME Documentation + * ERASE Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * FOPEN() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Open a file. + * $SYNTAX$ + * FOPEN( , [] ) --> nHandle + * $ARGUMENTS$ + * Name of file to open + * Dos file open mode + * file is to be accessed. The open mode is composed of elements from the + * two types of modes described in the tables below. If just the Access + * Mode is used, the file is opened non-sharable. The default open mode is + * zero, which indicates non-sharable and read-only. + * + * + * FOPEN() Sharing Modes + * ------------------------------------------------------------------------ + * Mode Fileio.ch Operation + * ------------------------------------------------------------------------ + * 0 FO_COMPAT Compatibility mode (default) + * 16 FO_EXCLUSIVE Exclusive use + * 32 FO_DENYWRITE Prevent others from writing + * 48 FO_DENYREAD Prevent others from reading + * 64 FO_DENYNONE Allow others to read or write + * 64 FO_SHARED Same as FO_DENYNONE + * ------------------------------------------------------------------------ + * + * The Access Modes in combination (+) with the Sharing modes determine the + * accessibility of the file in a network environment. + * + * $RETURNS$ + * FOPEN() returns a DOS file handle + * $DESCRIPTION$ + * This function opens a file expressed as and returns a DOS + * file handle to be used with other low-level file functions.The + * value of represents the status of the file to be opened; + * the default value is 0.The DOS file open modes are as the follows: + * + * 0 Read only + * 1 Write only + * 2 Read/write + * 16 Exclusive read only + * 17 Exclusive write only + * 18 Exclusive read/write only + * 32 Prevent others from writing + * 33 Prevent others from reading + * 34 Prevent read/write only + * 48 Deny read only + * 49 Deny write only + * 50 Deny read/Write + * 64 Share read only + * 65 Share write only + * 66 Share read/write + * + * If there is an error in opening a file, a -1 will be returned by + * the function.Files handles may be in the range of 0 to 65535. The + * status of the SET DEFAULT TO and SET PATH TO commands has no effect + * on this function.Directory names and paths must be specified along + * with the file that is to be opened. + * If an error has occured, see the returns values from FERROR() for + * possible reasons for the error. + * $EXAMPLES$ + * IF (nH:=FOPEN('X.TXT',66)<0 + * ? 'File cann't be open' + * ENDIF + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * FCREATE(),FERROR(),FCLOSE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FCREATE() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Creates a file + * $SYNTAX$ + * FCREATE( , [] ) --> nHandle + * $ARGUMENTS$ + * is the name of the file to create. + * + * Numeric code for the DOS file attribute + * $RETURNS$ + * Numeric expression + * $DESCRIPTION$ + * This function creates a new file with a filename of . The + * default value of is 0 and is used to set the DOS + * attribute byte for the file being created by this function. + * The return value will be DOS file handle that is associated + * with the new file. This number will be between zero to 65,535, + * inclusive. If an error occurs, the return value of this function + * will be -1 + * If the file already exists, the existing file will be + * truncated to a file lenght of 0 bytes. + * If specified, the folowing table shows the value for + * and their related meaning to the file being created by + * this Function. + * + * Value of File Attribute + * 0 Normal/Default,Read/Write + * 1 Read-only,Attemptinf to open for + * output returns an error + * 2 Hidden,Excluded from normal DIR + * search + * 4 Create,Excluded from normal DIR + * search + * $EXAMPLES$ + * IF (nh:=FCREATE("TEST.TXT") <0 + * ? "Can not create file" + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * FCLOSE(),FOPEN(),FWRITE(),FREAD(),FERROR() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FREAD() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Reads a specified number of bytes from a file. + * $SYNTAX$ + * FREAD( , @, ) --> nBytes + * $ARGUMENTS$ + * Dos file handle + * Character expression passed by reference + * Number of bytes to read. + * $RETURNS$ + * FREAD() returns the number of bytes successfyly read from the file + * + * $DESCRIPTION$ + * This function reads the characters from a DOS file whose file handle + * is into it character memory variable expressed as . + * The function returns the number of bytes successfully read into + * . + * The value of is obtained from either it call to the FOPEN() + * or the FCREATE() function. + * The expression is passed by reference and must be defined + * before this function is called. It also must be at least the same + * length as . + * is the number of bytes to read, starting at the current DOS + * file pointer position. If this function is successful in reading + * the characters from the file, the length of or the number + * of bytes specified in will be the value returned. The current + * DOS file pointer advances the number of bytes read with each succe- + * ssive read.The return value is the number of byte successfully read + * from the file . If a 0 is returned, or if the number of + * bytes read matches neither the length of nor the specified + * value in an end-of-file condition has been reached. + * $EXAMPLES$ + * cBuffer:=SPACE(500) + * IF (nH:=FOPEN('X.TXT))>0 + * FREAD(Hh,@cBuffer,500) + * ? cbuffer + * ENDIF + * FCLOSE(nH) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is not CA-Clipper compliant since may can read + * strings greather the 65K depending of platform. + * $SEEALSO$ + * BIN2I(),BIN2L(),BIN2W(),FERROR(),FWRITE() + * $INCLUDE$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FWRITE() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Writes characters to a file + * $SYNTAX$ + * FWRITE( , , [] ) --> nBytesWritten + * $ARGUMENTS$ + * DOS file handle number. + * Character expression to be written. + * The number of bytes to write. + * $RETURNS$ + * FWRITE() returns the number of bytes successfully written. + * $DESCRIPTION$ + * This function writes the contents of to the file designa- + * ted by its file handle . If used, is the number of + * bytes in to write. + * The returned value is the number of bytes successfully written to the + * DOS file. If the returned value is 0, an error has occurred (unless + * this is intended). A successful write occurs when the number returned + * by FWRITE() is equal to either LEN( ) or . + * The value of is the string or variable to be written to the + * open DOS file . + * The value of is the number of bytes to write out to the file. + * The disk write begins with the current file position in . If + * this variable is not used, the entire contents of is written + * to the file. + * To truncate a file. a call of FWRITE( nHandle, "", 0 ) is needed. + * $EXAMPLES$ + * nHandle:=FCREATE('x.txt') + * FOR X:=1 to 10 + * FWRITE(nHandle,STR(x)) + * NEXT + * FCLOSE(nHandle) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is not CA-Clipper compatile since + * it can writes strings greather the 64K + * $SEEALSO$ + * FCLOSE(),FCREATE(),FERROR(),FOPEN(),I2BIN(),L2BIN() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FERROR() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Reports the error status of low-level file functions + * $SYNTAX$ + * FERROR() --> + * $ARGUMENTS$ + * + * $RETURNS$ + * Value of the DOS error last encountered by a + * low-level file function. + * + * FERROR() Return Values + * + * Error Meaning + * + * 0 Successful + * 2 File not found + * 3 Path not found + * 4 Too many files open + * 5 Access denied + * 6 Invalid handle + * 8 Insufficient memory + * 15 Invalid drive specified + * 19 Attempted to write to a write-protected disk + * 21 Drive not ready + * 23 Data CRC error + * 29 Write fault + * 30 Read fault + * 32 Sharing violation + * 33 Lock Violation + * + * $DESCRIPTION$ + * After every low-level file function,this function will return + * a value that provides additional informationon the status of + * the last low-level file functions's performance.If the FERROR() + * function returns a 0, no error was detected.Below is a table + * of possibles values returned by the FERROR() function. + * + * $EXAMPLES$ + * ^CFE 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 + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compatible + * $SEEALSO$ + * FCLOSE(),FERASE(),FOPEN(),FWRITE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FCLOSE() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Closes an open file + * $SYNTAX$ + * FCLOSE( ) --> + * $ARGUMENTS$ + * DOS file handle + * $RETURNS$ + * Logical TRUE (.T.) or FALSE (.F.) + * $DESCRIPTION$ + * This function closes an open file with a dos file handle + * of and writes the associated DOS buffer to the + * disk. The value is derived from the FCREATE() + * or FOPEN() function. + * $EXAMPLES$ + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * FOPEN(),FCREATE(),FREAD(),FWRITE(),FERROR() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FERASE() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Erase a file from disk + * $SYNTAX$ + * FERASE( ) --> nSuccess + * $ARGUMENTS$ + * Name of file to erase. + * $RETURNS$ + * 0 if successful, -1 if not + * $DESCRIPTION$ + * This function deletes the file specified in from the disk. + * No extensions are assumed. The drive and path my be included in + * ; neither the SET DEFAULT not the SET PATH command controls + * the performance of this function.If the drive or path is not used, + * the function will look for the file only on the currently selected + * direcytory on the logged drive. + * + * If the function is able to successfully delete the file from the + * disk, the value of the function will be 0; otherwise a -1 will + * be returned.If not successfu, aditional information may be + * obtained by calling the FERROR() function. + * Note: Any file to be removed by FERASE() must still be closed. + * + * $EXAMPLES$ + * IF (FERASE("TEST.TXT")==0) + * ? "File successfully erased" + * ELSE + * ? "File can not be deleted" + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper Compatible + * $SEEALSO$ + * FERROR(),FRENAME() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FRENAME() + * $CATEGORY$ + * File management + * $ONELINER$ + * Renames a file + * $SYNTAX$ + * FRENAME( , ) --> nSuccess + * $ARGUMENTS$ + * Old filenarne to he changed + * New filename + * $RETURNS$ + * FRENAME() returns If sucessful, a 0 will he returned otherwise, + * a -1 will be returned. + * $DESCRIPTION$ + * This function renames the specified file to . + * A filename and/or directory name may be specified for either para- + * meter. However, if a path is supplied as part of and + * this path is different from either the path specified in + * or (if none is used) the current drive and directory, the function + * will not execute successfully. + * Neither parameter is subject to the control of the SET PATH TO or + * SET DEFAULT TO commands. In attempting to locate the file to be + * renamed, this function will search the default drive and directory + * or the drive and path specified in . It will not search + * directories named by the SET PATH TO and SET DEFAULT TO commands + * or by the DOS PATH statement. + * If the file specified in exists or the file is open, + * the function will be unable to rename the file.If the function + * is unable to complete its operation,it will return a value of -1. + * If it is able to rename the file, the return value for the function + * will be 0.A call to FERROR() function will give additional infor- + * mation about any error found. + * $EXAMPLES$ + * nResult:=FRENAME("x.txt","x1.txt") + * IF nResult <0 + * ? "File could not be renamed." + * ENDIF + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * ERASE,FERASE(),FERROR(),FILE(),RENAME + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FSEEK() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Positions the file pointer in a file. + * $SYNTAX$ + * FSEEK( , , [] ) --> nPosition + * $ARGUMENTS$ + * DOS file handle. + * The number of bytes to move. + * The relative position in the file. + * $RETURNS$ + * FSEEK() return the current position relative to begin-of-file + * $DESCRIPTION$ + * This function sets the file pointer in the file whose DOS file + * handle is and moves the file pointer by bytes + * from the file position designated by . The returned value + * is the relative position of the file pointer to the beginning-of-file + * marker once the operation has been completed. + * is the file handle number. It is obtained from the FOPEN() + * or FCREATE() function. + * The value of is the number of bytes to move the file pointer + * from the position determined by .The value of may + * be a negative number, suggesting backward movement. + * The value of designates the starting point from which the + * file pointer should he moved, as shown in the following table: + * + * File position + * + * 0 Beginning of file + * 1 Current file pointer position + * 2 End of file + * + * If a value is not provided for , it defaults to 0 and + * moves the file pointer from the beginning of the file. + * $EXAMPLES$ + * // here is a function that read one text line from an open file + * + * // nH = file handle obtained from FOPEN() + * // cB = a string buffer passed-by-reference to hold the result + * // nMaxLine = maximum number of bytes to read + * + * #define EOL HB_OSNEWLINE() + * FUNCTION FREADln( nH, cB, nMaxLine ) + * LOCAL cLine, nSavePos, nEol, nNumRead + * cLine := space( nMaxLine ) + * cB := '' + * nSavePos := FSEEK( nH, 0, FS_RELATIVE ) + * nNumRead := FREAD( nH, @cLine, nMaxLine ) + * IF ( nEol := AT( EOL, substr( cLine, 1, nNumRead ) ) ) == 0 + * cB := cLine + * ELSE + * cB := SUBSTR( cLine, 1, nEol - 1 ) + * FSEEK( nH, nSavePos + nEol + 1, FS_SET ) + * ENDIF + * RETURN nNumRead != 0 + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant. + * $SEEALSO$ + * FCREATE(),FERROR(),FOPEN(),FREAD(),FREADSTR(),FWRITE() + * $INCLUDE$ + * Fileio.ch + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FILE() + * $CATEGORY$ + * File management + * $ONELINER$ + * Tests for the existence of file(s) + * $SYNTAX$ + * FILE( ) --> lExists + * $ARGUMENTS$ + * Dos Skeleton or file name to find. + * $RETURNS$ + * FILE() return a logical true (.T.) or logical false (.F.). + * $DESCRIPTION$ + * This function return a logical true (.T.) if the given filename + * exist. + * Dos skeletons symbols may be used in the filename in , + * as may the drive and/or path name. If a drive are not explicity + * specified,FILE() will first search the current drive and directory, + * and will look for the file in the directories specified by SET PATH + * TO and ST DEFAULT TO commands.However, this command does not look + * at the values in the DOS PATH command. + * $EXAMPLES$ + * ? file('c:\harbour\doc\compiler.txt") + * ? file('c:/harbour/doc/subcodes.txt") + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compatible. + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FREADSTR() + * $CATEGORY$ + * Low level file handling + * $ONELINER$ + * Reads a string from a file. + * $SYNTAX$ + * FREADSTR(, ) --> cString + * $ARGUMENTS$ + * DOS file handle number. + * + * Number of bytes to read. + * $RETURNS$ + * FREADSTR() return an characted expression + * $DESCRIPTION$ + * This function returns a character string of bytes from a + * file whose DOS file handle is . + * The value of the file handle is obtained from either the + * FOPEN() or FCREATE() functions. + * The value of is the number of bytes to read from the file. + * The returned string will be the number of characters specified in + * or the number of bytes read before an end-of-file charac- + * ter (ASCII 26) is found. + * NOTE This function is similar to the FREAD() function, except that + * it will not read binary characters that may he required as part of + * a header of a file construct. Characters Such as CHR(0) and CHR(26) + * may keep this function from performing its intended operation. In this + * event, the FREAD() function should he used in place of the FREADSTR() + * function. + * $EXAMPLES$ + * IF ( nH := FOPEN("x.txt") ) > 0 + * cStr := Freadstr(nH,100) + * ? cStr + * ENDIF + * FCLOSE(nH) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is not CA-Clipper compliant since may read + * strings greather the 65K depending of platform. + * $SEEALSO$ + * BIN2I(),BIN2L(),BIN2W(),FERROR(),FREAD(),FSEEK() + * $INCLUDE$ + * + * $END$ + */ + +/* HARBOUR COMMANDS */ + +/* $DOC$ + * $FUNCNAME$ + * RENAME + * $CATEGORY$ + * Command + * $ONELINER$ + * Changes the name of a specified file + * $SYNTAX$ + * RENAME TO + * $ARGUMENTS$ + * Old filename + * New Filename + * $RETURNS$ + * $DESCRIPTION$ + * This command changes the name of to .Both + * and must include a file extension.This command + * if not affected by the SET PATH TO or SET DEFAULT TO commands;drive + * and directoy designaters must be specified if either file is in a + * directory other then the default drive and directory. + * If id currently open or if it previously exists, this + * command will not perform the desired operation. + * $EXAMPLES$ + * RENAME c:\autoexec.bat to c:\autoexec.old + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This command is CA-Clipper compatible + * $SEEALSO$ + * CURDIR(),ERASE,FILE(),FERASE(),FRENAME() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ERASE + * $CATEGORY$ + * Command + * $ONELINER$ + * Remove a file from disk + * $SYNTAX$ + * ERASE + * $ARGUMENTS$ + * Name of file to remove + * $RETURNS$ + * $DESCRIPTION$ + * This command removes a file from the disk.The use of a drive,directo- + * ry,and wild-card skeleton operator is allowed for the root of the + * filename.The file extension is required.The SET DEFAULT and SET PATH + * commands do not affect this command. + * The file must be considered closed by the operating system before it + * may be deleted. + * $EXAMPLES$ + * Erase c:\autoexec.bat + * Erase c:/temp/read.txt + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This command is CA-Clipper compatible + * $SEEALSO$ + * CURDIR(),FILE(),FERASE(),DELETE FILE + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DELETE FILE + * $CATEGORY$ + * Command + * $ONELINER$ + * Remove a file from disk + * $SYNTAX$ + * DELETE FILE + * $ARGUMENTS$ + * Name of file to remove + * $RETURNS$ + * $DESCRIPTION$ + * This command removes a file from the disk.The use of a drive,directo- + * ry,and wild-card skeleton operator is allowed for the root of the + * filename.The file extension is required.The SET DEFAULT and SET PATH + * commands do not affect this command. + * The file must be considered closed by the operating system before it + * may be deleted. + * $EXAMPLES$ + * Erase c:\autoexec.bat + * Erase c:/temp/read.txt + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This command is CA-Clipper compatible + * $SEEALSO$ + * CURDIR(),FILE(),FERASE(),ERASE + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __TYPEFILE() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Show the content of a file on the console and/or printer + * $SYNTAX$ + * __TYPEFILE( , [] ) --> NIL + * $ARGUMENTS$ + * is a name of the file to display. If the file have an + * extension, it must be specified (there is no default value). + * + * is an optional logical value that specifies whether the + * output should go only to the screen (.F.) or to both the screen and + * printer (.T.), the default is (.F.). + * $RETURNS$ + * __TYPEFILE() always return NIL. + * $DESCRIPTION$ + * __TYPEFILE() function type the content of a text file on the screen + * with an option to send this information also to the printer. The + * file is displayed as is without any headings or formating. + * + * If contain no path, __TYPEFILE() try to find the file first + * in the SET DEFAULT directory and then in search all of the SET PATH + * directories. If can not be found a run-time error occur. + * + * Use SET CONSOLE OFF to suppress screen output. + * You can pause the output using Ctrl-S, press any key to resume. + * + * __TYPEFILE() function is used in the preprocessing of the TYPE + * command. + * $EXAMPLES$ + * The following examples assume a file name MyText.DAT exist in all + * specified paths, a run-time error would displayed if it does not + * + * // display MyText.DAT file on screen + * __TYPEFILE( "MyText.DAT" ) + * + * // display MyText.DAT file on screen and printer + * __TYPEFILE( "MyText.DAT", .T. ) + * + * // display MyText.DAT file on printer only + * SET CONSOLE OFF + * __TYPEFILE( "MyText.DAT", .T. ) + * SET CONSOLE ON + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * __TYPEFILE() works exactly like CA-Clipper's __TYPEFILE() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * "COPY FILE","SET DEFAULT","SET PATH","SET PRINTER",TYPE + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TYPE + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Show the content of a file on the console, printer or file + * $SYNTAX$ + * TYPE [TO PRINTER] [TO FILE ] + * $ARGUMENTS$ + * is a name of the file to display. If the file have an + * extension, it must be specified (there is no default value). + * It can be specified as literal file name or as a character + * expression enclosed in parentheses. + * + * TO PRINTER is an optional keyword that specifies that the output + * should go to both the screen and printer. + * + * TO FILE copy the source also to a file. If no + * extension is given (.txt) is added to the output file name. + * can be specified as literal file name or as a character + * expression enclosed in parentheses. + * $RETURNS$ + * $DESCRIPTION$ + * TYPE command type the content of a text file on the screen + * with an option to send this information also to the printer or to + * an alternate file. The file is displayed as is without any headings + * or formating. + * + * If contain no path, TYPE try to find the file first in the + * SET DEFAULT directory and then in search all of the SET PATH + * directories. If can not be found a run-time error occur. + * + * If contain no path it is created in the SET DEFAULT + * directory. + * + * Use SET CONSOLE OFF to suppress screen output. + * You can pause the output using Ctrl-S, press any key to resume. + * $EXAMPLES$ + * The following examples assume a file name MyText.DAT exist in all + * specified paths, a run-time error would displayed if it does not + * + * // display MyText.DAT file on screen + * TYPE MyText.DAT + * + * // display MyText.DAT file on screen and printer + * TYPE MyText.DAT TO PRINTER + * + * // display MyText.DAT file on printer only + * SET CONSOLE OFF + * TYPE MyText.DAT" TO PRINTER + * SET CONSOLE ON + * + * // display MyText.DAT file on screen and into a file MyReport.txt + * TYPE MyText.DAT TO FILE MyReport + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * TYPE works exactly like CA-Clipper's TYPE + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * "COPY FILE","SET DEFAULT","SET PATH","SET PRINTER",__TYPEFILE() + * $END$ + */ diff --git a/harbour/doc/en/ht_class.txt b/harbour/doc/en/ht_class.txt new file mode 100644 index 0000000000..6594ce32c9 --- /dev/null +++ b/harbour/doc/en/ht_class.txt @@ -0,0 +1,88 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 David G. Holm + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * TFileRead() + * $CATEGORY$ + * Harbour Tools + * $ONELINER$ + * Read a file one line at a time + * $SYNTAX$ + * oFile := TFileRead():New( [, ] ) + * $ARGUMENTS$ + * cFileName is the required name of the file to be read. + * nReadSize is the optional size to use when reading from the file. + * The default value is 4096 and the allowed range is 1 through 65535. + * Any value outside of this range causes the default value to be used. + * $RETURNS$ + * An instance of the File Reader class + * $DESCRIPTION$ + * TFileRead() is used to access a file one line at a time. You must + * specify the name of the file when an instance of the class is created. + * The class data should be considered private to the class. + * The class methods are as follows: + * New() Creates a new instance of the TFileRead class. + * Open([]) Opens the file for reading. The optional nFlags + * parameter can use any of the FOPEN() flags from + * fileio.ch. The default is FO_READ + FO_SHARED. + * Calling this method when the file is already + * open causes the next ReadLine() to start over + * from the beginning of the file. + * Close() Closes the file. + * ReadLine() Returns one line from the file, stripping the + * newline characters. The following sequences are + * treated as one newline: 1) CR CR LF; 2) CR LF; + * 3) LF; and 4) CR. Note: LF CR is 2 newlines. + * Name() Returns the name of the file. + * IsOpen() Returns .T. if the file is open. + * MoreToRead() Returns .T. if there are more lines to be read + * (think of it as an inverse EOF function). + * Error() Returns .T. if an error has occurred. + * ErrorNo() Returns the current error code. + * ErrorMsg([]) Returns a formatted error message. + * $EXAMPLES$ + * #ifdef __HARBOUR__ + * #define NEW_LINE CHR( 10 ) + * #else + * #define NEW_LINE CHR( 13 ) + CHR( 10 ) + * #endif + * #include "fileio.ch" + * + * PROCEDURE Main( cFile ) + * LOCAL oFile := TFileRead():New( cFile ) + * + * oFile:Open() + * IF oFile:Error() + * QOUT( oFile:ErrorMsg( "FileRead: " ) ) + * ELSE + * WHILE oFile:MoreToRead() + * OUTSTD( oFile:ReadLine() ) + * OUTSTD( NEW_LINE ) + * END WHILE + * oFile:Close() + * END IF + * QUIT + * $TESTS$ + * See Examples + * $STATUS$ + * R + * $COMPLIANCE$ + * This is a new Harbour Tools class + * $SEEALSO$ + * TClass() + * $END$ + */ + diff --git a/harbour/doc/en/ht_conv.txt b/harbour/doc/en/ht_conv.txt new file mode 100644 index 0000000000..9668e49e08 --- /dev/null +++ b/harbour/doc/en/ht_conv.txt @@ -0,0 +1,261 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Luiz Rafael Culik + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * ISBIN() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Check if the value is a Binary Number + * $SYNTAX$ + * ISBIN() -> + * $ARGUMENTS$ + * STRING TO BE CHECKED + * $RETURNS$ + * .T. IF THE STRING IS BYNARY + * .F. IF NOT + * $DESCRIPTION$ + * check if the passed string is a bynary number or not + * $EXAMPLES$ + * $SEEALSO$ + * ISOCTAL(),ISDEC(),ISHEXA() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISOCTAL() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Check if the value is a Octal Number + * $SYNTAX$ + * ISOCTAL() -> + * $ARGUMENTS$ + * STRING TO BE CHECKED + * $RETURNS$ + * .T. IF THE STRING IS OCTAL + * .F. IF NOT + * $DESCRIPTION$ + * check if the passed string is a octal number or not + * $EXAMPLES$ + * $SEEALSO$ + * ISBIN(),ISDEC(),ISHEXA() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISDEC() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Check if the value is a Decimal Number + * $SYNTAX$ + * ISDEC() -> + * $ARGUMENTS$ + * STRING TO BE CHECKED + * $RETURNS$ + * .T. IF THE STRING IS DECIMAL + * .F. IF NOT + * $DESCRIPTION$ + * check if the passed string is a decimal number or not + * $EXAMPLES$ + * $SEEALSO$ + * ISOCTAL(),ISBIN(),ISHEXA() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISHEXA() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Check if the value is a Hexal Number + * $SYNTAX$ + * ISHEXA() -> + * $ARGUMENTS$ + * STRING TO BE CHECKED + * $RETURNS$ + * .T. IF THE STRING IS HEXA + * .F. IF NOT + * $DESCRIPTION$ + * check if the passed string is a hexa number or not + * $EXAMPLES$ + * $SEEALSO$ + * ISOCTAL(),ISDEC(),ISBIN() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DECTOBIN() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts a Decimal Value to Binary + * $SYNTAX$ + * DECTOBIN() -> + * $ARGUMENTS$ + * NUMBER TO BE CONVERTED + * $RETURNS$ + * NUMBER CONVERTED + * $DESCRIPTION$ + * This function converts a string from an decimal value + * to an binary value. + * $EXAMPLES$ + * + * $SEEALSO$ + * Dectohexa(),dectooctal() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DECTOOCTAL() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts a Decimal Value to Octal + * $SYNTAX$ + * DECTOOCTAL() -> + * $ARGUMENTS$ + * NUMBER TO BE CONVERTED + * $RETURNS$ + * NUMBER CONVERTED + * $DESCRIPTION$ + * This function converts a string from an decimal value + * to an octal value. + * $EXAMPLES$ + * + * $SEEALSO$ + * Dectohexa(),dectobin() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DECTOHEXA() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts a Decimal Value to Hexa + * $SYNTAX$ + * DECTOHEXA() -> + * $ARGUMENTS$ + * NUMBER TO BE CONVERTED + * $RETURNS$ + * NUMBER CONVERTED + * $DESCRIPTION$ + * This function converts a string from an decimal value + * to an hexadecimal value. + * $EXAMPLES$ + * + * $SEEALSO$ + * Dectobin(),dectoctal() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BIntODEC() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts a Binary Value to Decimal + * $SYNTAX$ + * BIntODEC() -> + * $ARGUMENTS$ + * NUMBER TO BE CONVERTED + * $RETURNS$ + * NUMBER CONVERTED + * $DESCRIPTION$ + * This function converts a string from an binary value + * to a numeric decimal value. + * $EXAMPLES$ + * + * $SEEALSO$ + * OctaltoDec(),HexatoDec() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * OCTALTODEC() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts a Octal Value to Decimal + * $SYNTAX$ + * OCTALTODEC() -> + * $ARGUMENTS$ + * NUMBER TO BE CONVERTED + * $RETURNS$ + * NUMBER CONVERTED + * $DESCRIPTION$ + * This function converts a string from an octal value + * to a numeric decimal value. + * $EXAMPLES$ + * + * $SEEALSO$ + * BintoDec(),HexatoDec() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HEXATODEC() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Converts a Hexa Value to Decimal + * $SYNTAX$ + * HEXATODEC() -> + * $ARGUMENTS$ + * NUMBER TO BE CONVERTED + * $RETURNS$ + * NUMBER CONVERTED + * $DESCRIPTION$ + * This function converts a string from an hexadecimal value + * to a numeric decimal value. + * $EXAMPLES$ + * + * $SEEALSO$ + * OctaltoDec(),BintoDec() + * $INCLUDE$ + * + * $END$ + */ + diff --git a/harbour/doc/en/ht_dbf.txt b/harbour/doc/en/ht_dbf.txt new file mode 100644 index 0000000000..ffa4ed9f9d --- /dev/null +++ b/harbour/doc/en/ht_dbf.txt @@ -0,0 +1,134 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 2000 Alexander Kresin + * FIELDTYPE() documentation + * FIELDSIZE() documentation + * FIELDDECI() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDTYPE() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determines the type of a given field. + * $SYNTAX$ + * FIELDTYPE() --> cFieldType + * $ARGUMENTS$ + * Data field , which type need to be determined. + * $RETURNS$ + * FIELDTYPE() returns the character that designates the type of a given field: + * 'C' - character string; + * 'N' - numeric; + * 'L' - logical; + * 'D' - date; + * 'M' - memo. + * $DESCRIPTION$ + * This function determines the type of a field, designated by its number. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL i + * USE Tests NEW + * FOR i = 1 TO FCOUNT() + * ? FieldType( i ) + * NEXT + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-CLIPPER TOOLS compatible + * $SEEALSO$ + * FIELDSIZE(), FIELDDECI() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDSIZE() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determines the size of a given field. + * $SYNTAX$ + * FIELDSIZE() --> nFieldSize + * $ARGUMENTS$ + * Data field , which size need to be determined. + * $RETURNS$ + * FIELDSIZE() returns the number that designates the size of a given field. + * $DESCRIPTION$ + * This function determines the size of a field, designated by its number. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL i + * USE Tests NEW + * FOR i = 1 TO FCOUNT() + * ? FieldSize( i ) + * NEXT + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-CLIPPER TOOLS compatible + * $SEEALSO$ + * FIELDTYPE(), FIELDDECI() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDDECI() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determines the number of decimal places of a given numeric field. + * $SYNTAX$ + * FIELDDECI() --> nFieldDeci + * $ARGUMENTS$ + * Numeric data field , for which number of decimal + * places need to be determined. + * $RETURNS$ + * FIELDDECI() returns the numeric value that designates the number + * of decimal places of a given field. + * $DESCRIPTION$ + * This function determines the number of decimal places of a given numeric field. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL i + * USE Tests NEW + * FOR i = 1 TO FCOUNT() + * ? FieldDeci( i ) + * NEXT + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-CLIPPER TOOLS compatible + * $SEEALSO$ + * FIELDTYPE(), FIELDSIZE() + * $INCLUDE$ + * + * $END$ + */ diff --git a/harbour/doc/en/ht_doc.txt b/harbour/doc/en/ht_doc.txt new file mode 100644 index 0000000000..d9e7197015 --- /dev/null +++ b/harbour/doc/en/ht_doc.txt @@ -0,0 +1,283 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Luiz Rafael Culik + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * THtml() + * $CATEGORY$ + * Harbour Tools + * $ONELINER$ + * Html Class + * $SYNTAX$ + * oHtml:=THtml():New() + * $ARGUMENTS$ + * Name of the Html file to create + * $RETURNS$ + * An instance of the THtml Class + * $DESCRIPTION$ + * THtml() is a class that creates an .html file of the same + * name you pass to the constructor. + * The class methods are as follows: + * New() Create a new instance of the THtml class + * Close() Close the created file + * WriteTitle() Write the file title + * WritePar() Writes a paragraph + * WriteParBold() Same as WritePar(), but the text is bold + * WriteLink(,) Write a link to another topic + * WriteText() Write any text + * $EXAMPLES$ + * FUNCTION MAIN() + * + * LOCAL oHtm + * + * oHtm := THTML():New( "www\harbour.html" ) + * oHtm:WriteTitle( "Harbour Reference Guide" ) + * oHtm:WritePar( "HARBOUR" ) + * oHtm:WriteLink( "OverView" ) + * oHtm:WriteLink( "License" ) + * oHtm:WriteLink( "http://www.gnu.org/copyleft/gpl" ) + * oHtm:WritePar( "See the Links Above" ) + * oHtm:Close() + * RETURN Nil + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This is a new Harbour Tools class + * $PLATFORMS$ + * ALL + * $FILES$ + * + * $SEEALSO$ + * TCLASS() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TOs2() + * $CATEGORY$ + * Harbour Tools + * $ONELINER$ + * OS/2 Documentation Class + * $SYNTAX$ + * oNg:=TOs2():New() + * $ARGUMENTS$ + * Name of the IPF Source file to create + * $RETURNS$ + * An instance of the TOs2 Class + * $DESCRIPTION$ + * TOs2() is a class that creates the OS/2 IPF Source + * of the same name you pass to the constructor. + * The class methods are as follows: + * New() Create a new instance of the TOs2 class + * Close() Close the created file + * WriteTitle(,) Write the file title + * WritePar() Write a paragraph + * WriteParBold() Same as WritePar(), but the text is bold + * WriteLink() Write a link to another topic + * ScanLink() Scan the aLinkRef array for a valid topic + * DosToOs2Text() Convert a Dos string to a OS/2 String + * $EXAMPLES$ + * FUNCTION MAIN() + * + * LOCAL oNg + * + * oNg := TOs2():New( "ngi\harbour.ngi" ) + * oNg:WriteTitle( "Harbour Reference Guide" ) + * oNg:WritePar( "HARBOUR" ) + * oNg:WriteLink( "OverView" ) + * oNg:WriteLink( "License" ) + * + * oNg:WritePar( "See the Links Above" ) + * oNg:Close() + * RETURN Nil + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This is a new Harbour Tools class + * $PLATFORMS$ + * ALL + * $FILES$ + * + * $SEEALSO$ + * TNortonGuide() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TNortonGuide() + * $CATEGORY$ + * Harbour Tools + * $ONELINER$ + * Norton Guide Class + * $SYNTAX$ + * oNg:=TNortonGuide():New() + * $ARGUMENTS$ + * Name of the Ng Source file to create + * $RETURNS$ + * An instance of the TNortonGuide Class + * $DESCRIPTION$ + * TNortonGuide() is a class that creates the Norton Guide Source + * Code of the same name you pass to the constructor. + * The class methods are as follows: + * New() Create an instance of the TNortonGuide class + * Close() Close the created file + * WriteTitle(,) Write the file title + * WritePar() Write a paragraph + * WriteParBold() Same as WritePar(), but the text is bold + * WriteLink() Write a link to another topic + * $EXAMPLES$ + * FUNCTION MAIN() + * + * LOCAL oNg + * + * oNg := TNortonGuide():New( "ngi\harbour.ngi" ) + * oNg:WriteTitle( "Harbour Reference Guide" ) + * oNg:WritePar( "HARBOUR" ) + * oNg:WriteLink( "OverView" ) + * oNg:WriteLink( "License" ) + * + * oNg:WritePar( "See the Links Above" ) + * oNg:Close() + * RETURN Nil + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This is a new Harbour Tools class + * $PLATFORMS$ + * ALL + * $FILES$ + * $SEEALSO$ + * TTroff(), TRtf(), THtml(), TOs2() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TRtf() + * $CATEGORY$ + * Harbour Tools + * $ONELINER$ + * Rtf Class + * $SYNTAX$ + * oNg:=TRtf():New() + * $ARGUMENTS$ + * Name of the RTF file to create + * $RETURNS$ + * An instance of the TRtf Class + * $DESCRIPTION$ + * TRtf() is a class that creates the RTF Documentation Source + * Code of the same name you pass to the constructor. + * The class methods are as follows: + * New() Create a new instance of the TRtf class + * Close() Close the create file + * WriteTitle(,) Write the file title + * WritePar() Write a paragraph + * WriteParBold() Same as WritePar(), but the text is bold + * WriteLink() Write a link to another topic + * WriteHeader() Write the RTF header + * EndPar() Write the end paragraph delimiter + * $EXAMPLES$ + * FUNCTION MAIN() + * + * LOCAL oRtf + * + * oRtf := TRtf():New( "rtf\harbour.rtf" ) + * oRtf:WriteHeader() + * oRtf:WriteTitle( "Harbour Reference Guide" ) + * oRtf:WritePar( "HARBOUR" ):Endpar() + * oRtf:WriteLink( "OverView" ) + * oRtf:WriteLink( "License" ) + * + * oRtf:WritePar( "See the Links Above" ):EndPar() + * oRtf:Close() + * RETURN Nil + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This is a new Harbour Tools class + * $PLATFORMS$ + * ALL + * $FILES$ + * + * $SEEALSO$ + * TNortonGuide() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TTroff() + * $CATEGORY$ + * Harbour Tools + * $ONELINER$ + * Troff Class + * $SYNTAX$ + * oTroff:=TTrof():New() + * $ARGUMENTS$ + * Name of the Troff file to create + * $RETURNS$ + * An instance of the TTroff Class + * $DESCRIPTION$ + * TTroff() is a class that creates the TROFF Documentation Source + * Code of the same name you pass to the constructor. + * The class methods are as follows: + * New() Create a new instance of the THtml class + * Close() Close the created file + * WriteTitle(,) Write the file title + * WritePar() Write a paragraph + * WriteParBold() Same as WritePar(), but the text is bold + * WriteLink() Write a link to another topic + * WriteText() Writes text without formating + * $EXAMPLES$ + * FUNCTION MAIN() + * + * LOCAL oTroff + * oTroff := TTroff():New( "tr\harbour.ngi" ) + * oTroff:WriteTitle( "Harbour Reference Guide" ) + * oTroff:WritePar( "HARBOUR" ) + * oTroff:WriteLink( "OverView" ) + * oTroff:WriteLink( "License" ) + * + * oTroff:WritePar( "See the Links Above" ) + * oTroff:Close() + * + * RETURN Nil + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This is a new Harbour Tools class + * $PLATFORMS$ + * ALL + * $FILES$ + * + * $SEEALSO$ + * TNortonGuide() + * $END$ + */ diff --git a/harbour/doc/en/ht_file.txt b/harbour/doc/en/ht_file.txt new file mode 100644 index 0000000000..07932e9d23 --- /dev/null +++ b/harbour/doc/en/ht_file.txt @@ -0,0 +1,96 @@ +/* + * $Id$ + */ + +/* $DOC$ + * $FUNCNAME$ + * CD() + * $CATEGORY$ + * DOS + * $ONELINER$ + * Change the Current Directory + * $SYNTAX$ + * CD() + * $ARGUMENTS$ + * DIR TO BE CHANGED + * $RETURNS$ + * .T. IF SUCEFUL + * .F. IF NOT + * + * $DESCRIPTION$ + * CHANGE THE CURRENT DIRECTORY + * $EXAMPLES$ + * IF CD("OLA") + * RETURN(.T.) + * ELSE + * RETURN(.F.) + * ENDIF + * + * $SEEALSO$ + * MD() RD() + * $INCLUDE$ + * extend.h dos.h dir.h bios.h + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * MD() + * $CATEGORY$ + * DOS + * $ONELINER$ + * Creates a Directory + * $SYNTAX$ + * MD() + * $ARGUMENTS$ + * DIRECTORY TO BE CREATED + * $RETURNS$ + * .T. IF SUCEFUL + * .F. IF NOT + * + * $DESCRIPTION$ + * CREATE A DIRECTORY + * $EXAMPLES$ + * IF MD("OLA") + * RETURN(.T.) + * ELSE + * RETURN(.F.) + * ENDIF + * + * $SEEALSO$ + * CD() MD() + * $INCLUDE$ + * extend.h dos.h dir.h bios.h + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RD() + * $CATEGORY$ + * DOS + * $ONELINER$ + * Remove a Directory + * $SYNTAX$ + * RD() + * $ARGUMENTS$ + * DIR TO BE DELETED + * $RETURNS$ + * .T. IF SUCEFUL + * .F. IF NOT + * + * $DESCRIPTION$ + * REMOVE A DIRECTORY + * $EXAMPLES$ + * IF RD("OLA") + * RETURN(.T.) + * ELSE + * RETURN(.F.) + * ENDIF + * + * $SEEALSO$ + * CD() MD() + * $INCLUDE$ + * extend.h dos.h dir.h bios.h + * $END$ + */ diff --git a/harbour/doc/en/ht_gt.txt b/harbour/doc/en/ht_gt.txt new file mode 100644 index 0000000000..d92ebcd503 --- /dev/null +++ b/harbour/doc/en/ht_gt.txt @@ -0,0 +1,479 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Andy M Leighton + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_ASCPOS() + * $CATEGORY$ + * String + * $ONELINER$ + * Return the ascii value of a specified character in a string + * $SYNTAX$ + * GT_Ascpos(, ) --> nAscVal + * $ARGUMENTS$ + * - The string + * - The position in + * $RETURNS$ + * nAscVal - The ascii value of substr(, , 1) + * $DESCRIPTION$ + * Return the ascii value of a specified character in a string + * Equivalent (but much faster) to + * asc(substr(cStr, nPos, 1) + * + * NOTE: + * invalid parameters will return -1 + * nPos > len(cStr) will return -2 + * + * This last behaviour is different to the Funcky function of the + * same name. I changed the behaviour because some of the strings + * I process contain embedded NULs. + * $EXAMPLES$ + * ? gt_ascpos("the cat sat on the mat", 3) // prints e + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_ASCIISUM() + * $CATEGORY$ + * String + * $ONELINER$ + * Sum the ascii values in a string. + * $SYNTAX$ + * GT_AsciiSum() --> nSum + * $ARGUMENTS$ + * - The string to sum + * $RETURNS$ + * nSum - The sum of all ascii values in . + * $DESCRIPTION$ + * Sum the ascii value of every character in the passed string + * and return the result. + * $EXAMPLES$ + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_ATDIFF() + * $CATEGORY$ + * String + * $ONELINER$ + * Return the position where two strings begin to differ + * $SYNTAX$ + * GT_AtDiff(, ) --> nPos + * $ARGUMENTS$ + * - A character string to compare + * - The string to compare with + * $RETURNS$ + * nPos - The position in where begins to differ + * $DESCRIPTION$ + * Return the position in where begins to differ. + * If the strings differ in the first character GT_AtDiff() will + * return 1. If the two strings are identical (or identical upto + * the last character in ) the function will return 0. + * + * NOTE: + * invalid parameters will return -1 + * $EXAMPLES$ + * ? gt_atDiff("the cat", "the rat") // prints 5 + * ? gt_atDiff("the cat", "the ") // prints 0 + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_CHAREVEN() + * $CATEGORY$ + * String + * $ONELINER$ + * Return a string of all the characters in even positions + * $SYNTAX$ + * GT_CharEven() --> cRet + * $ARGUMENTS$ + * - A character string to extract chars from + * $RETURNS$ + * cRet - A string of all the chars in even positions + * $DESCRIPTION$ + * Return a string consisting of all the characters in even + * positions in . + * + * NOTE: + * invalid parameters will return "" + * $EXAMPLES$ + * + * ? gt_CharEven("abcdefghijklm") // prints "bdfhjl" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_CHARMIX() + * $CATEGORY$ + * String + * $ONELINER$ + * Amalgamate two strings to form the return value + * $SYNTAX$ + * GT_CharMix(, ) --> cRet + * $ARGUMENTS$ + * - A character string to mix + * - A character string to mix with + * $RETURNS$ + * cRet - A string consisting of all the characters in + * mixed with all the characters in + * $DESCRIPTION$ + * Return a string consisting of all the characters in + * mixed with the characters from . + * + * NOTE: + * invalid parameters will return "" + * $EXAMPLES$ + * + * ? gt_CharMix("abc", "123") // prints "a1b2c3" + * ? gt_CharMix("abcde", "123") // prints "a1b2c3de" + * ? gt_CharMix("abc", "12345") // prints "a1b2c345" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_CHARODD() + * $CATEGORY$ + * String + * $ONELINER$ + * Return a string of all the characters in odd positions + * $SYNTAX$ + * GT_CharOdd() --> cRet + * $ARGUMENTS$ + * - A character string to extract chars from + * $RETURNS$ + * cRet - A string of all the chars in odd positions + * $DESCRIPTION$ + * Return a string consisting of all the characters in odd + * positions in . + * + * NOTE: + * invalid parameters will return "" + * $EXAMPLES$ + * + * ? gt_CharOdd("abcdefghijklm") // prints "acegikm" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_CHRCOUNT() + * $CATEGORY$ + * String + * $ONELINER$ + * Count the number of times a character appears in a string + * $SYNTAX$ + * GT_ChrCount(, ) --> nFreq + * $ARGUMENTS$ + * - The character to find the frequence of + * - The string in which to find the character + * $RETURNS$ + * nFreq - The number of times occurs in + * $DESCRIPTION$ + * GT_ChrCount() counts how many times a specified character + * appears in a string. + * + * NOTE: + * invalid parameters will return -1 + * $EXAMPLES$ + * + * ? GT_ChrCount("t", "the cat sat on the mat") // prints 4 + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_CHRFIRST() + * $CATEGORY$ + * String + * $ONELINER$ + * Find which character occurs first in a string + * $SYNTAX$ + * GT_ChrFirst(, ) --> nAsc + * $ARGUMENTS$ + * - The set of characters to find + * - The input string + * $RETURNS$ + * nAsc - The ASCII value of the first character in + * which appears first in + * $DESCRIPTION$ + * Return the ascii value of a character in + * which appears first in . + * $EXAMPLES$ + * + * ? chr(GT_ChrFirst("sa ", "This is a test")) // prints "s" + * ? chr(GT_ChrFirst("et", "This is a test")) // prints "t" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_CHRTOTAL() + * $CATEGORY$ + * String + * $ONELINER$ + * Find number of times a set of characters appears in a string + * $SYNTAX$ + * GT_ChrTotal(, ) --> nTotOcc + * $ARGUMENTS$ + * - The set of characters + * - The string to search + * $RETURNS$ + * nTotOcc - The number of times the characters specified in + * appears in + * $DESCRIPTION$ + * Returns the numnber of occurrences of characters belonging + * to the set in the string . If no characters + * in appears in GT_ChrTotal() will return 0. + * + * NOTE: + * invalid parameters will return -1 + * $EXAMPLES$ + * + * local cStr1 := "the cat sat on the mat" + * + * ? GT_ChrTotal("tae", cStr1) // prints 10 + * ? GT_ChrTotal("zqw", cStr1) // prints 0 + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STRCOUNT() + * $CATEGORY$ + * String + * $ONELINER$ + * Count the number of times a substring appears in a string + * $SYNTAX$ + * GT_StrCount(, ) --> nFreq + * $ARGUMENTS$ + * - The substring to find the frequence of + * - The string in which to find the character + * $RETURNS$ + * nFreq - The number of times occurs in + * $DESCRIPTION$ + * GT_StrCount() counts how many times a specified substring + * appears in a string. + * If the substring does NOT appear in this function + * will return 0. + * If the substring is a single character use GT_ChrCount() as + * it will be faster. + * + * NOTE: + * invalid parameters will return -1 + * $EXAMPLES$ + * + * ? GT_StrCount("the", "the cat sat on the mat") // prints 2 + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STRCSPN() + * $CATEGORY$ + * String + * $ONELINER$ + * Return length of prefix in string of chars NOT in set. + * $SYNTAX$ + * GT_strcspn(, ) --> nLength + * $ARGUMENTS$ + * - The string to find the prefix in + * - The set of characters + * $RETURNS$ + * nLength - The length of a string upto a character in the set + * $DESCRIPTION$ + * Return the number of characters in the leading segment of a + * string that consists solely of characters NOT in the set. + * $EXAMPLES$ + * + * ? GT_strcspn("this is a test", "as ") // prints 3 + * ? GT_strcspn("this is a test", "elnjpq") // prints 11 + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STRDIFF() + * $CATEGORY$ + * String + * $ONELINER$ + * Return a string where it begins to differ from another + * $SYNTAX$ + * GT_StrDiff(, ) --> cRet + * $ARGUMENTS$ + * - A character string to compare + * - The string to compare with + * $RETURNS$ + * cRet - A string beginning at the position in where + * begins to differ from + * $DESCRIPTION$ + * Return a string beginning at the position in where + * begins to differ from . If the two strings are + * identical (or identical upto the last character in ) + * the function will return "". + * + * NOTE: + * invalid parameters will return "" + * $EXAMPLES$ + * ? gt_strDiff("the cat", "the rat") // prints "rat" + * ? gt_strDiff("the cat", "the ") // prints "" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STREXPAND() + * $CATEGORY$ + * String + * $ONELINER$ + * Insert fillers between characters in a passed string + * $SYNTAX$ + * GT_StrExpand(, [], []) --> cRet + * $ARGUMENTS$ + * - A character string to insert chars into + * - The number of fill characters to insert (default 1) + * - The fill chararacter (default space) + * $RETURNS$ + * cRet - The input string with fill characters inserted between + * every character in the original. + * $DESCRIPTION$ + * Inserts fill characters into a string. + * + * NOTE: + * invalid parameters will return "" + * $EXAMPLES$ + * + * ? gt_strexpand("abc") // prints "a b c" + * ? gt_strexpand("abc", 2) // prints "a b c" + * ? gt_strexpand("abc", 2, 'þ') // prints "aþþbþþc" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STRLEFT() + * $CATEGORY$ + * String + * $ONELINER$ + * Find length of prefix of a string + * $SYNTAX$ + * GT_StrLeft(, ) --> nLen + * $ARGUMENTS$ + * - The input string + * - The set of characters to find + * $RETURNS$ + * nLen - The length of the prefix found. + * $DESCRIPTION$ + * Return the length of the leading segment in the passed string + * that consists solely of the characters in the character + * set . + * + * If no characters in the the search set are found, the function + * shall return 0 + * $EXAMPLES$ + * + * ? GT_StrLeft("this is a test", "hsit ") // prints 8 + * ? GT_StrLeft("this is a test", "hit a") // prints 3 + * ? GT_StrLeft("this is a test", "zxy") // prints 0 + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STRPBRK() + * $CATEGORY$ + * String + * $ONELINER$ + * Return string after 1st char from a set + * $SYNTAX$ + * GT_StrpBrk(, ) --> cString + * $ARGUMENTS$ + * - The input string + * - The set of characters to find + * $RETURNS$ + * cString - The input string after the first occurance of any + * character from + * $DESCRIPTION$ + * Return a string after the first occurance of any character from + * the input set . + * $EXAMPLES$ + * + * ? GT_Strpbrk("This is a test", "sa ") // prints "s is a test" + * ? GT_Strpbrk("This is a test", "et") // prints "test" + * + * $END$ + */ + +/* + * $DOC$ + * $FUNCNAME$ + * GT_STRRIGHT() + * $CATEGORY$ + * String + * $ONELINER$ + * Find length of a suffix of a string + * $SYNTAX$ + * GT_StrRight(, ) --> nLen + * $ARGUMENTS$ + * - The input string + * - The set of characters to find + * $RETURNS$ + * nLen - The length of the prefix found. + * $DESCRIPTION$ + * Return the length of the trailing segment in the passed string + * that consists solely of the characters in the character + * set . + * + * If no characters in the the search set are found, the function + * shall return 0 + * $EXAMPLES$ + * + * ? GT_StrRight("this is a test", "teas ") // prints 8 + * ? GT_StrRight("this is a test", "tes h") // prints 5 + * ? GT_StrRight("this is a test", "zxy") // prints 0 + * + * $END$ + */ + diff --git a/harbour/doc/en/ht_str.txt b/harbour/doc/en/ht_str.txt new file mode 100644 index 0000000000..ae96abdc1f --- /dev/null +++ b/harbour/doc/en/ht_str.txt @@ -0,0 +1,61 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Victor Szakats + * STRFORMAT() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * StrFormat() + * $CATEGORY$ + * String + * $ONELINER$ + * ... + * $SYNTAX$ + * StrFormat([, [, [, ...]]) + * $ARGUMENTS$ + * Holds the mask for the resulting string + * Holds the strings to be inserted in the mask + * maximum 9 of them can be specified. + * $RETURNS$ + * Return the mask with all the parameters inserted. + * $DESCRIPTION$ + * String replacment, can be useful when writing international + * apps. You can separate the constant strings from the variable ones. + * Each %1 - %9 marks will be replaced with the appropriate parameter + * from the parameter list. + * Marks can be in any order, and can be duplicated. + * You can print "%" character with "%%". + * $EXAMPLES$ + * StrFormat("Please insert disk %1 to drive %2", LTrim(Str(2)), "A:") + * StrFormat("This is %1 from %2", "Victor", "Hungary") + * StrFormat("%2 %1 %2", "Param1", "Param2") + * $TESTS$ + * ? StrFormat("Please insert disk %1 to drive %2", LTrim(Str(2)), "A:") + * ? StrFormat("This is %1 from %2", "Victor", "Hungary") + * ? StrFormat("%2 %1 %2", "Param1", "Param2") + * ? StrFormat("Hello") + * ? StrFormat("%1 - %2", "one") + * ? StrFormat("%1 - %2", "one", "two") + * ? StrFormat("%2 - %1", "one", "two") + * ? StrFormat("%2 - %", "one", "two") + * ? StrFormat("%% - %", "one", "two") + * ? StrFormat("%9 - %", "one", "two") + * $STATUS$ + * Done + * $COMPLIANCE$ + * All platforms + * $SEEALSO$ + * + * $END$ + */ + diff --git a/harbour/doc/en/hvm.txt b/harbour/doc/en/hvm.txt new file mode 100644 index 0000000000..b5ce073983 --- /dev/null +++ b/harbour/doc/en/hvm.txt @@ -0,0 +1,360 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * CLIPINIT() documentation + * __SETHELPK() documentation + * + * Copyright 1999 Ryszard Glab + * DO() documentation + * EVAL() documentation + * + * 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( ) --> + * $ARGUMENTS$ + * is the function level required. + * $RETURNS$ + * Return the name of the function that it is being executed. + * $DESCRIPTION$ + * This function look 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 . + * $EXAMPLES$ + * See Test + * $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 + * $STATUS$ + * R + * $COMPLIANCE$ + * PROCNAME() is fully CA-Clipper compliant. + * $SEEALSO$ + * PROCLINE(),PROCFILE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * PROCLINE() + * $CATEGORY$ + * Misc + * $ONELINER$ + * Gets the line number of the current function on the stack + * $SYNTAX$ + * PROCLINE( ) --> + * $ARGUMENTS$ + * is the function level required. + * $RETURNS$ + * Return the line number of the function that it is being executed. + * $DESCRIPTION$ + * This function look at the top of the stack and gets the current + * line number of executed function if no arguments are passed. + * Otherwise it returns the line number of the function or procedure + * at . + * $EXAMPLES$ + * See Test + * $TESTS$ + * function Test() + * ? ProcLine( 0 ) + * ? ProcName( 2 ) + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * PROCLINE() is fully CA-Clipper compliant. + * $SEEALSO$ + * PROCNAME(),PROCFILE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * PROCFILE() + * $CATEGORY$ + * Misc + * $ONELINER$ + * This function allways returns an empty string. + * $SYNTAX$ + * PROCFILE( ) --> + * $ARGUMENTS$ + * is any valid type. + * $RETURNS$ + * Return and empty string + * $DESCRIPTION$ + * This function is added to the RTL for full compatibility. It allways + * returns an empty string. + * $EXAMPLES$ + * ? ProcFile() + * $TESTS$ + * function Test() + * ? ProcFile() + * ? ProcFile( NIL ) + * ? ProcFile( 2 ) + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * PROCFILE() is fully CA-Clipper compliant. + * $SEEALSO$ + * PROCNAME(),PROCLINE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_PVALUE() + * $CATEGORY$ + * Parameter Checks + * $ONELINER$ + * Retrieves the value of an argument. + * $SYNTAX$ + * HB_PVALUE( ) --> + * $ARGUMENTS$ + * A number that indicates the argument to check. + * $RETURNS$ + * Returns the value stored by an argument. + * $DESCRIPTION$ + * This function is useful to check the value stored in an argument. + * $EXAMPLES$ + * See Test + * $TESTS$ + * function Test( nValue, cString ) + * if PCount() == 2 + * ? hb_PValue( 1 ), nValue + * ? hb_PValue( 2 ), cString + * endif + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * HB_PVALUE() is a new function and hence not CA-Clipper compliant. + * $SEEALSO$ + * PCOUNT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * PCOUNT() + * $CATEGORY$ + * Parameter Checks + * $ONELINER$ + * Retrieves the number of arguments passed to a function. + * $SYNTAX$ + * PCOUNT() --> + * $ARGUMENTS$ + * None + * $RETURNS$ + * Returns a number that indicates the number of arguments + * passed to a function or procedure. + * $DESCRIPTION$ + * This function is useful to check if a function or procedure + * has received the required number of arguments. + * $EXAMPLES$ + * See Test + * $TESTS$ + * function Test( xExp ) + * if PCount() == 0 + * ? "This function needs a parameter" + * else + * ? xExp + * endif + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * PCOUNT() is fully CA-Clipper compliant. + * $SEEALSO$ + * HB_PVALUE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __QUIT() + * $CATEGORY$ + * Events + * $ONELINER$ + * Terminates an application. + * $SYNTAX$ + * __QUIT() --> NIL + * $ARGUMENTS$ + * None + * $RETURNS$ + * NIL + * $DESCRIPTION$ + * This function terminates the current application and returns + * to the system. + * $EXAMPLES$ + * See Test + * $TESTS$ + * function EndApp( lYesNo ) + * if lYesNo + * __Quit() + * endif + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * __QUIT() is fully CA-Clipper compliant. + * $SEEALSO$ + * QUIT + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * CLIPINIT() + * $CATEGORY$ + * Internal + * $ONELINER$ + * Initialize various Harbour sub-systems + * $SYNTAX$ + * CLIPINIT() --> NIL + * $ARGUMENTS$ + * none. + * $RETURNS$ + * CLIPINIT() always return NIL. + * $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 activate the + * default error handler, and (at least for the moment) call the + * function that set the default help key. + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * It is said that CLIPINIT() should not call that function that set + * the default help key since CA-Clipper do it in some other place. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * INIT PROCEDURE + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __SetHelpK() + * $CATEGORY$ + * Internal + * $ONELINER$ + * Set F1 as the default help key + * $SYNTAX$ + * __SetHelpK() --> NIL + * $ARGUMENTS$ + * none. + * $RETURNS$ + * __SetHelpK() always return NIL. + * $DESCRIPTION$ + * Set F1 to execute a function called HELP if such a function is + * linked into the program. + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __SetHelpK() works exactly like CA-Clipper's __SetHelpK() + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __XHelp(),SET KEY,SETKEY() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BREAK() + * $CATEGORY$ + * Error recovery + * $ONELINER$ + * Exits from a BEGIN SEQUENCE block + * $SYNTAX$ + * BREAK( ) --> NIL + * $ARGUMENTS$ + * is any valid expression. It is always required. + * If do not want to pass any argument, just use NIL. + * $RETURNS$ + * NIL + * $DESCRIPTION$ + * This function passes control to the RECOVER statement in a + * BEGIN SEQUENCE block. + * $EXAMPLES$ + * Break( NIL ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BREAK() is fully CA-Clipper compliant. + * $SEEALSO$ + * BEGIN SEQUENCE + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DO() + * $CATEGORY$ + * Utility + * $ONELINER$ + * Calls a procedure or a function + * $SYNTAX$ + * DO( [, ] ) + * $ARGUMENTS$ + * = Either a string with a function/procedure name to be called + * or a codeblock to evaluate + * = arguments passed to a called function/procedure or to + * a codeblock + * $RETURNS$ + * A value that was returned from called function + * $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 WITH ... statement. + * If called procedure/function doesn't exist then the runtime error + * is generated. + * This function can be used as replacement of macro operator. + * It is also used internally to implement DO WITH + * In this case is of type HB_SYMB + * $EXAMPLES$ + * cbCode ={|x| MyFunc( x )} + * DO( cbCode, 1 ) + * + * cFunction := "MyFunc" + * xRetVal :=DO( cFunction, 2 ) + * + * Old style (slower): + * DO &cFunction WITH 3 + * + * $TESTS$ + * + * $STATUS$ + * + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $END$ + */ diff --git a/harbour/doc/en/input.txt b/harbour/doc/en/input.txt new file mode 100644 index 0000000000..230bb9ae1c --- /dev/null +++ b/harbour/doc/en/input.txt @@ -0,0 +1,384 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * READKEY() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * INKEY() + * $CATEGORY$ + * Console input + * $ONELINER$ + * Extracts the next key code from the Harbour keyboard buffer + * $SYNTAX$ + * INKEY( [] [,] ) --> nKey + * $ARGUMENTS$ + * is an optional timeout value in seconds, with a granularity + * of 1/10th of a second. If omitted, INKEY() returns immediately. If set + * to 0, INKEY() waits until an input event occurs. If set to any other + * value, INKEY() will return either when an input event occurs or when + * the timeout period has elapsed. If only this parameter is specified + * and it is not numeric, it will be treated as if it were 0. But if both + * parameters are specified and this parameter is not numeric, it will be + * treated as if it were not present. + * + * is an optional mask of input events that are to be enabled. + * If omitted, defaults to hb_set.HB_SET_EVENTMASK. Valid input maks are + * in inkey.ch and are explained below. It is recommended that the mask + * names be used rather than their numeric values, in case the numeric + * values change in future releases of Harbour. To allow more than one + * type of input event, simply add the various mask names together. + * INKEY_MOVE = Mouse motion events are allowed + * INKEY_LDOWN = The mouse left click down event is allowed + * INKEY_LUP = The mouse left click up event is allowed + * INKEY_RDOWN = The mouse right click down event is allowed + * INKEY_RUP = The mouse right click up event is allowed + * INKEY_KEYBOARD = All keyboard events are allowed + * INKEY_ALL = All mouse and keyboard events are allowed + * If the parameter is not numeric, it will be treated as if it were set + * to hb_set.HB_SET_EVENTMASK. + * $RETURNS$ + * 0 in case of timeout with no input event, otherwise returns a value + * in the range -39 to 386 for keyboard events or the range 1001 to 1007 + * for mouse events. Mouse events and non-printable keyboard events are + * represented by the K_ values listed in inkey.ch. Keyboard + * event return codes in the range 32 through 127 are equivalent to the + * printable ASCII character set. Keyboard event return codes in the + * range 128 through 255 are assumed to be printable, but results may + * vary based on hardware and nationality. + * $DESCRIPTION$ + * INKEY() can be used to detect input events, such as keypress, mouse + * movement, or mouse key clicks (up and/or down). + * $EXAMPLES$ + * // Wait for the user to press the Esc key + * ? "Please press the ESC key." + * WHILE INKEY( 0.1 ) != K_ESC + * END + * $TESTS$ + * KEYBOARD "AB"; ? INKEY(), INKEY() ==> 65 66 + * $STATUS$ + * S + * $COMPLIANCE$ + * INKEY() is compliant with the Clipper 5.3 INKEY() function with one + * exceptions: The Harbour INKEY() function will raise an argument error + * if the first parameter is less than or equal to 0 and the second + * parameter (or the default mask) is not valid, because otherwise INKEY + * would never return, because it was, in effect, asked to wait forever + * for no events (Note: In Clipper, this also blocks SET KEY events). + * $SEEALSO$ + * inkey.ch + * $END$ + */ + + +/* $DOC$ + * $FUNCNAME$ + * __KEYBOARD() + * $CATEGORY$ + * Console input + * $ONELINER$ + * DO NOT CALL THIS FUNCTION DIRECTLY! + * $SYNTAX$ + * KEYBOARD + * CLEAR TYPEAHEAD + * $ARGUMENTS$ + * is the optional string to stuff into the Harbour keyboard + * buffer after clearing it first. Note: The character ";" is converted + * to CHR(13) (this is an undocumented CA-Clipper feature). + * $RETURNS$ + * There is no return value + * $DESCRIPTION$ + * Clears the Harbour keyboard typeahead buffer and then inserts an + * optional string into it. + * $EXAMPLES$ + * // Stuff an Enter key into the keyboard buffer + * KEYBOARD CHR(13) + * // Clear the keyboard buffer + * CLEAR TYPEAHEAD + * $TESTS$ + * KEYBOARD CHR(13); ? INKEY() ==> 13 + * KEYBOARD ";" ? INKEY() ==> 13 + * KEYBOARD "HELLO"; CLEAR TYPEAHEAD; ? INKEY() ==> 0 + * $STATUS$ + * R + * $COMPLIANCE$ + * __KEYBOARD() is compliant with CA-Clipper 5.3 + * $SEEALSO$ + * CLEAR TYPEAHEAD, KEYBOARD + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __KEYPUT() + * $CATEGORY$ + * Console input + * $ONELINER$ + * Put an inkey code to the keyboard buffer + * $SYNTAX$ + * __keyPut( ) + * $ARGUMENTS$ + * is the inkey code, which should be inserted into the + * keyboard buffer. + * $RETURNS$ + * There is no return value + * $DESCRIPTION$ + * Inserts an inkey code to the string buffer. The buffer is *not* + * cleared in this operation. This function allows to insert such + * inkey codes which are not in the range of 0 to 255. To insert more + * than one code, call the function repeatedly. The zero code cannot + * be inserted. + * $EXAMPLES$ + * // Stuff an Alt+PgDn key into the keyboard buffer + * __keyPut( K_ALT_PGDN ) + * $TESTS$ + * __keyPut( K_ALT_PGDN ) ; ? INKEY() ==> 417 + * __keyPut( K_F11 ) ; ? INKEY() ==> -40 + * $STATUS$ + * R + * $COMPLIANCE$ + * Was not part of Clipper + * $SEEALSO$ + * KEYBOARD,CLEAR TYPEAHEAD,INKEY() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * NEXTKEY() + * $CATEGORY$ + * Console input + * $ONELINER$ + * Returns the value of the next key in the Harbour keyboard buffer + * $SYNTAX$ + * NEXTKEY() --> nKey + * $ARGUMENTS$ + * None + * $RETURNS$ + * There is no return value + * $DESCRIPTION$ + * Returns the value of the next key in the Harbour keyboard buffer + * without extracting it. + * $EXAMPLES$ + * // Use NEXTKEY() with INKEY() to change display character or by + * // itself to exit the loop, so that the caller can detect the Esc. + * LOCAL nKey, cChar := "+" + * WHILE TRUE + * ?? cChar + * nKey := NEXTKEY() + * IF nKey == K_ESC + * EXIT + * ELSE + * IF nKey != 0 + * cChar := CHR( nKey ) + * END IF + * END IF + * END WHILE + * $TESTS$ + * KEYBOARD "AB"; ? NEXTKEY(), NEXTKEY() ==> 65 65 + * $STATUS$ + * R + * $COMPLIANCE$ + * NEXTKEY() is compliant with CA-Clipper 5.3 + * $SEEALSO$ + * INKEY(),LASTKEY() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * LASTKEY() + * $CATEGORY$ + * Console input + * $ONELINER$ + * Returns the last key exttracted from the Harbour keyboard buffer + * $SYNTAX$ + * LASTKEY() --> nKey + * $ARGUMENTS$ + * None + * $RETURNS$ + * There is no return value + * $DESCRIPTION$ + * Returns the value of the last key exttracted from the Harbour + * keyboard buffer + * $EXAMPLES$ + * // Continue looping unless the ESC key was pressed in MainFunc() + * WHILE TRUE + * MainFunc() + * IF LASTKEY() == K_ESC + * EXIT + * END IF + * END WHILE + * $TESTS$ + * KEYBOARD "AB"; ? INKEY(), LASTKEY() ==> 65 65 + * $STATUS$ + * R + * $COMPLIANCE$ + * LASTKEY() is compliant with CA-Clipper 5.3 + * $SEEALSO$ + * INKEY(),LASTKEY() + * $END$ + */ + + +/* $DOC$ + * $FUNCNAME$ + * KEYBOARD + * $CATEGORY$ + * Command + * $ONELINER$ + * Stuffs the keyboard with a string + * $SYNTAX$ + * KEYBOARD + * $ARGUMENTS$ + * String to be processed, one character at a time, + * by the Harbour keyboard processor + * $RETURNS$ + * + * $DESCRIPTION$ + * This command stuff the input buffer with . The + * number of character that can be stuffed into the keyboard + * buffer is controled by SET TYPEAHEAD command and may range + * from 0 to 32,622, with each character appearing in the ASCII + * range of 0 to 255. None of the extended keys may be stuffed + * in the keyboard buffer. + * Issuing a KEYBOARD " " will clear the keyboard buffer. + * $EXAMPLES$ + * // Stuff an Enter key into the keyboard buffer + * KEYBOARD CHR(13) + * // Clear the keyboard buffer + * CLEAR TYPEAHEAD + * $TESTS$ + * KEYBOARD CHR(13); ? INKEY() ==> 13 + * KEYBOARD "HELLO"; CLEAR TYPEAHEAD; ? INKEY() ==> 0 + * $STATUS$ + * R + * $COMPLIANCE$ + * __KEYBOARD() is compliant with CA-Clipper 5.3 + * $SEEALSO$ + * CLEAR TYPEAHEAD,__KEYBOARD() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * READKEY()* + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Find out which key terminate a READ + * $SYNTAX$ + * READKEY() --> nKeyCode + * $ARGUMENTS$ + * none. + * $RETURNS$ + * READKEY() return a numeric code representing the key that cause READ + * to terminate. + * $DESCRIPTION$ + * READKEY() is used after a READ was terminated to determine the exit + * key pressed. If the get buffer was updated during READ, 256 is added + * to the return code. + * + * Exit key Return code Return code + * (not updated) (updated) + * -------------- ------------- ----------- + * Up 4 260 + * Down 5 261 + * Page-Up 6 262 + * Page-Down 7 263 + * Ctrl Page-Up 34 290 + * Ctrl Page-Down 35 291 + * Esc 12 268 + * Ctrl End 14 270 + * Enter 15 271 + * + * Key >= 32 15 271 + * otherwise 0 0 + * + * READKEY() is a compatibility function so try not use it. READKEY() + * is superseded by LASTKEY() which return INKEY() code for that key, + * UPDATED() could be use to find if the get buffer was changed during + * READ. + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * READKEY() works exactly like CA-Clipper's READKEY(). + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * @...GET,INKEY(),LASTKEY(),READ,READEXIT(),UPDATED() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * MROW() + * $CATEGORY$ + * Console input + * $ONELINER$ + * Returns the mouse cursor row position + * $SYNTAX$ + * MRow() --> nMouseColumn + * $ARGUMENTS$ + * None + * $RETURNS$ + * The mouse cursor column position + * $DESCRIPTION$ + * $EXAMPLES$ + * local nKey + * nKey = InKey( 0 ) + * do case + * case nKey == + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is a Harbour Specific + * $PLATFORMS$ + * This function is Windows Specific + * $SEEALSO$ + * MCOL() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * MCOL() + * $CATEGORY$ + * Console input + * $ONELINER$ + * Returns the mouse cursor column position + * $SYNTAX$ + * MCol() --> nMouseColumn + * $ARGUMENTS$ + * None + * $RETURNS$ + * The mouse cursor column position + * $DESCRIPTION$ + * $EXAMPLES$ + * local nKey + * nKey = InKey( 0 ) + * do case + * case nKey == + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is a Harbour Specific + * $PLATFORMS$ + * This function is Windows Specific + * $SEEALSO$ + * MROW() + * $END$ + */ diff --git a/harbour/doc/en/license.txt b/harbour/doc/en/license.txt new file mode 100644 index 0000000000..d40c5a30b7 --- /dev/null +++ b/harbour/doc/en/license.txt @@ -0,0 +1,42 @@ +/* + * $Id$ + */ + +/* $DOC$ + * $FUNCNAME$ + * License + * $CATEGORY$ + * Document + * $ONELINER$ + * Harbour License + * $DESCRIPTION$ + * + * THE HARBOUR PROJECT LICENSE + * =========================== + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version, with one exception: + * + * The exception is that if you link the Harbour Runtime Library (HRL) + * and/or the Harbour Virtual Machine (HVM) with other files to produce + * an executable, this does not by itself cause the resulting executable + * to be covered by the GNU General Public License. Your use of that + * executable is in no way restricted on account of linking the HRL + * and/or HVM code into it. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA (or visit + * their web site at http://www.gnu.org/). + * + * $SEEALSO$ + * OverView + * $END$ + */ diff --git a/harbour/doc/en/memo.txt b/harbour/doc/en/memo.txt new file mode 100644 index 0000000000..523c412ac0 --- /dev/null +++ b/harbour/doc/en/memo.txt @@ -0,0 +1,81 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Jose Lalin + * MEMOTRAN() documentation + * HARDCR() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * MEMOTRAN() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Converts hard and soft carriages within strings. + * $SYNTAX$ + * MEMOTRAN( , , ) --> + * $ARGUMENTS$ + * is a string of chars to convert. + * is the character to replace hard carriages with. If not + * specified defaults to semicolon. + * is the character to replace soft carriages with. If not + * specified defaults to single space. + * $RETURNS$ + * Trasformed string. + * $DESCRIPTION$ + * Returns a string/memo with carriage chars converted to specified + * chars. + * $EXAMPLES$ + * ? MEMOTRAN( DATA->CNOTES ) + * $TESTS$ + * @ 1, 1 SAY MEMOTRAN( Data->CNOTES ) + * will display converted string starting on row two, column two of the + * current device. + * $STATUS$ + * R + * $COMPLIANCE$ + * MEMOTRAN() is fully CA-Clipper compliant. + * $SEEALSO$ + * HARDCR(),STRTRAN() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HARDCR() + * $CATEGORY$ + * STRINGS + * $ONELINER$ + * Globaly replace all soft cariages returns with hard cariages returs + * $SYNTAX$ + * HARDCR( ) --> + * $ARGUMENTS$ + * is a string of chars to convert. + * $RETURNS$ + * Trasformed string. + * $DESCRIPTION$ + * Returns a string/memo with soft carriages chars converted to + * hard carraige char. + * $EXAMPLES$ + * ? HARDCR( Data->CNOTES ) + * $TESTS$ + * @ 1, 1 SAY HARDCR( Data->CNOTES ) + * will display converted string starting on row two, column two of the + * current device. + * $STATUS$ + * R + * $COMPLIANCE$ + * HARDCR() is fully CA-Clipper compliant. + * $SEEALSO$ + * MEMOTRAN(),STRTRAN() + * $END$ + */ diff --git a/harbour/doc/en/menu.txt b/harbour/doc/en/menu.txt new file mode 100644 index 0000000000..cadd2d2c4f --- /dev/null +++ b/harbour/doc/en/menu.txt @@ -0,0 +1,385 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * __ATPROMPT() documentation + * __MENUTO() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * ACHOICE() + * $CATEGORY$ + * Array + * $ONELINER$ + * Allows selection of an element from an array + * $SYNTAX$ + * ACHOICE(, , , , + * , + * [ | ], + * [ | ], + * [], + * []) --> nPosition + * + * $ARGUMENTS$ + * nTop - topmost row used to display array (default 0) + * nLeft - leftmost row used to display array (default 0) + * nBottom - bottommost row used to display array (default MAXROW()) + * nRight - rightmost row used to display array (default MAXCOL()) + * acMenuItems - the character array of items from which to select + * alSelectableItems - an array of items, either logical or character, + * which is used to determine if a particular item + * may be selected. If the type of a given item is + * character, it is macro evaluated, and the result + * is expected to be a logical. A value of .T. means + * that the item may be selected, .F. that it may not. + * (See next argument: lSelectableItems) + * lSelectableItems - a logical value which is used to apply to all + * items in acMenuItems. If .T., all items may be + * selected; if .F., none may be selected. + * (See previous argument: alSelectableItems) + * Default .T. + * cUserFunction - the name of a function to be called which may + * affect special processing of keystrokes. It is + * specified without parentheses or parameters. + * When it is called, it will be supplied with the + * parameters: nMode, nCurElement, and nRowPos. + * Default NIL. + * bUserBlock - a codeblock to be called which may + * affect special processing of keystrokes. It + * should be specified in the form + * {|nMode, nCurElemenet, nRowPos| ; + * MyFunc(nMode, nCurElemenet, nRowPos) }. + * Default NIL. + * nInitialItem - the number of the element to be highlighted as + * the current item when the array is initially + * displayed. 1 origin. Default 1. + * nWindowRow - the number of the window row on which the initial + * item is to be displayed. 0 origin. Default 0. + * + * $RETURNS$ + * nPosition - the number of the item to be selected, or 0 if the + * selection was aborted. + * + * $DESCRIPTION$ + * Allows selection of an element from an array. + * Please see standard Clipper documentation for ACHOICE for + * additional detail. + * + * $EXAMPLES$ + * aItems := { "One", "Two", "Three" } + * nChoice := ACHOICE( 10, 10, 20, 20, aItems ) + * IF nChoice == 0 + * ? "You did not choose an item" + * ELSE + * ? "You chose element " + LTRIM( STR( nChoice ) ) + * ?? " which has a value of " + aItems[ nChoice ] + * ENDIF + * + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __AtPrompt() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Display a menu item on screen and define a message + * $SYNTAX$ + * __AtPrompt( , , , [] ) --> .F. + * + * $ARGUMENTS$ + * is the row number to display the menu . Value could + * range from zero to MAXROW(). + * + * is the column number to display the menu . Value + * could range from zero to MAXCOL(). + * + * is the menu item character string to display. + * + * define a message to display each time this menu item is + * highlighted. could be a character string or code block that + * is evaluated to a character string. If is not specified or + * got the wrong type, an empty string ("") would be used. + * $RETURNS$ + * __AtPrompt() always return .F. + * $DESCRIPTION$ + * With __AtPrompt() you define and display a menu item, each call to + * __AtPrompt() add another item to the menu, to start the menu itself + * you should call the __MenuTo() function (MENU TO command). You can + * define any row and column combination and they will be displayed at + * the order of definition. After each call to __AtPrompt(), the cursor + * is placed one column to the right of the last text displayed, and + * ROW() and COL() are updated. + * + * @...PROMPT command is preprocessed into __AtPrompt() function during + * compile time. + * $EXAMPLES$ + * // display a two line menu with status line at the bottom + * // let the user select favorite day + * SET MESSAGE TO 24 CENTER + * @ 10, 2 PROMPT "Sunday" MESSAGE "This is the 1st item" + * @ 11, 2 PROMPT "Monday" MESSAGE "Now we're on the 2nd item" + * MENU TO nChoice + * DO CASE + * CASE nChoice == 0 // user press Esc key + * QUIT + * CASE nChoice == 1 // user select 1st menu item + * ? "Guess you don't like Mondays" + * CASE nChoice == 2 // user select 2nd menu item + * ? "Just another day for some" + * ENDCASE + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * CA-Clipper array is limited to 4096 items, and therefor 4096 menu + * items are the maximum that could be defined per one menu, Harbour + * does not have this limit (not that you'll ever need that). + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * ACHOICE(),MENU TO,SET MESSAGE,SET INTENSITY,SET WRAP,__MENUTO() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * @...PROMPT + * $CATEGORY$ + * Command + * $ONELINER$ + * Display a menu item on screen and define a message + * $SYNTAX$ + * @ , PROMPT [MESSAGE ] + * $ARGUMENTS$ + * is the row number to display the menu . Value could + * range from zero to MAXROW(). + * + * is the column number to display the menu . Value + * could range from zero to MAXCOL(). + * + * is the menu item character string to display. + * + * define a message to display each time this menu item is + * highlighted. could be a character string or code block that + * is evaluated to a character string. If is not specified or + * got the wrong type, an empty string ("") would be used. + * $RETURNS$ + * @...Prompt always return .F. + * $DESCRIPTION$ + * With @...Prompt you define and display a menu item, each call to + * @...Prompt add another item to the menu, to start the menu itself + * you should call the __MenuTo() function (MENU TO command). You can + * define any row and column combination and they will be displayed at + * the order of definition. After each call to @...Prompt, the cursor + * is placed one column to the right of the last text displayed, and + * ROW() and COL() are updated. + * + * @...PROMPT command is preprocessed into __AtPrompt() function during + * compile time. + * $EXAMPLES$ + * // display a two line menu with status line at the bottom + * // let the user select favorite day + * SET MESSAGE TO 24 CENTER + * @ 10, 2 PROMPT "Sunday" MESSAGE "This is the 1st item" + * @ 11, 2 PROMPT "Monday" MESSAGE "Now we're on the 2nd item" + * MENU TO nChoice + * DO CASE + * CASE nChoice == 0 // user press Esc key + * QUIT + * CASE nChoice == 1 // user select 1st menu item + * ? "Guess you don't like Mondays" + * CASE nChoice == 2 // user select 2nd menu item + * ? "Just another day for some" + * ENDCASE + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * CA-Clipper array is limited to 4096 items, and therefor 4096 menu + * items are the maximum that could be defined per one menu, Harbour + * does not have this limit (not that you'll ever need that). + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * ACHOICE(),MENU TO,SET MESSAGE,SET INTENSITY,SET WRAP,__MENUTO() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MenuTo() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Invoked a menu defined by set of @...PROMPT + * $SYNTAX$ + * __MenuTo( , ) --> nChoice + * $ARGUMENTS$ + * is a set/get code block for variable named . + * + * is a character string that contain the name of the + * variable to hold the menu choices, if this variable does not exist + * a PRIVATE variable with the name would be created to + * hold the result. + * $RETURNS$ + * __MenuTo() return the number of select menu item, or 0 if there was + * no item to select from or if the user pressed the Esc key. + * $DESCRIPTION$ + * __MenuTo() invoked the menu define by previous __AtPrompt() call + * and display a highlight bar that the user can move to select an + * option from the menu. If does not exist or not visible, + * a PRIVATE variable named is created and hold the current + * menu selection. If there is a variable named , its value + * is used to select the first highlighted item. + * + * Menu prompts and messages are displayed in current Standard color, + * highlighted bar is displayed using current Enhanced color. + * + * Pressing the arrow keys move the highlighted bar. When a menu item + * is highlighted the message associated with it is displayed on the + * line specified with SET MESSAGE. If SET WRAP is ON and the user + * press UP arrow while on the first selection the last menu item is + * highlighted, if the user press Down arrow while on the last item, + * the first item is highlighted. + * + * Following are active keys that handled by __MenuTo(): + * ----------------------------------------------------- + * + * Up - Move to previous item + * Down - Move to next item + * Left - Move to previous item + * Right - Move to next item + * Home - Move to the first item + * End - Move to the last item + * Page-Up - Select menu item, return position + * Page-Down - Select menu item, return position + * Enter - Select menu item, return position + * Esc - Abort selection, return 0 + * First letter - Select next menu with the same first letter, + * return this item position. + * + * upon exit the cursor is placed at MAXROW()-1, 0 + * __MenuTo() can be nested without loosing the previous prompts. + * + * MENU TO command is preprocessed into __MenuTo() function during + * compile time. + * $EXAMPLES$ + * // display menu item on each screen corner and let user select one + * CLS + * SET MESSAGE TO MAXROW()/2 CENTER + * SET WRAP ON + * @ 0, 0 PROMPT "1. Upper left" MESSAGE " One " + * @ 0, MAXCOL()-16 PROMPT "2. Upper right" MESSAGE " Two " + * @ MAXROW()-1,MAXCOL()-16 PROMPT "3. Bottom right" MESSAGE "Three" + * @ MAXROW()-1,0 PROMPT "4. Bottom left" MESSAGE "Four " + * MENU TO nChoice + * SETPOS ( MAXROW()/2, MAXCOL()/2 - 10 ) + * if nChoice == 0 + * ?? "Esc was pressed" + * else + * ?? "Selected option is", nChoice + * endif + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * @...PROMPT,ACHOICE(),SET MESSAGE,SET INTENSITY,SET WRAP,__ATPROMPT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * MENU TO + * $CATEGORY$ + * Command + * $ONELINER$ + * Invoked a menu defined by set of @...PROMPT + * $SYNTAX$ + * MENU TO + * $ARGUMENTS$ + * is a character string that contain the name of the + * variable to hold the menu choices, if this variable does not exist + * a PRIVATE variable with the name would be created to + * hold the result. + * $RETURNS$ + * Menu To return the number of select menu item, or 0 if there was + * no item to select from or if the user pressed the Esc key. + * $DESCRIPTION$ + * Menu To() invoked the menu define by previous __AtPrompt() call + * and display a highlight bar that the user can move to select an + * option from the menu. If does not exist or not visible, + * a PRIVATE variable named is created and hold the current + * menu selection. If there is a variable named , its value + * is used to select the first highlighted item. + * + * Menu prompts and messages are displayed in current Standard color, + * highlighted bar is displayed using current Enhanced color. + * + * Pressing the arrow keys move the highlighted bar. When a menu item + * is highlighted the message associated with it is displayed on the + * line specified with SET MESSAGE. If SET WRAP is ON and the user + * press UP arrow while on the first selection the last menu item is + * highlighted, if the user press Down arrow while on the last item, + * the first item is highlighted. + * + * Following are active keys that handled by Menu To: + * ----------------------------------------------------- + * + * Up - Move to previous item + * Down - Move to next item + * Left - Move to previous item + * Right - Move to next item + * Home - Move to the first item + * End - Move to the last item + * Page-Up - Select menu item, return position + * Page-Down - Select menu item, return position + * Enter - Select menu item, return position + * Esc - Abort selection, return 0 + * First letter - Select next menu with the same first letter, + * return this item position. + * + * upon exit the cursor is placed at MAXROW()-1, 0 + * Menu To can be nested without loosing the previous prompts. + * + * MENU TO command is preprocessed into __MenuTo() function during + * compile time. + * $EXAMPLES$ + * // display menu item on each screen corner and let user select one + * CLS + * SET MESSAGE TO MAXROW()/2 CENTER + * SET WRAP ON + * @ 0, 0 PROMPT "1. Upper left" MESSAGE " One " + * @ 0, MAXCOL()-16 PROMPT "2. Upper right" MESSAGE " Two " + * @ MAXROW()-1,MAXCOL()-16 PROMPT "3. Bottom right" MESSAGE "Three" + * @ MAXROW()-1,0 PROMPT "4. Bottom left" MESSAGE "Four " + * MENU TO nChoice + * SETPOS ( MAXROW()/2, MAXCOL()/2 - 10 ) + * if nChoice == 0 + * ?? "Esc was pressed" + * else + * ?? "Selected option is", nChoice + * endif + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * @...PROMPT,ACHOICE(),SET MESSAGE,SET INTENSITY,SET WRAP,__ATPROMPT() + * $END$ + */ diff --git a/harbour/doc/en/misc.txt b/harbour/doc/en/misc.txt new file mode 100644 index 0000000000..f65aea913c --- /dev/null +++ b/harbour/doc/en/misc.txt @@ -0,0 +1,197 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 2000 Chen Kedem + * TONE() + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * OS() + * $ONELINER$ + * Return the current operating system + * $SYNTAX$ + * OS() -> + * $CATEGORY$ + * DOS + * $ARGUMENTS$ + * + * $RETURNS$ + * -> The Current operating system + * $DESCRIPTION$ + * This function will return the current operating system + * $EXAMPLES$ + * ? OS() + * + * $FILES$ + * source/rtl/environ.c + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * VERSION() + * $CATEGORY$ + * Environment + * $ONELINER$ + * Returns the HARBOUR Version or the Harbour/Compiler Version + * $SYNTAX$ + * VERSION([] --> + * $ARGUMENTS$ + * [] Optional Parameter that enables the display + * of the C compiler version that HARBOUR was built with. + * $RETURNS$ + * String contining the Harbour Version or the Harbour + * and C compiler Version when the parameter is used. + * $DESCRIPTION$ + * This function returns the HARBOUR Version or the Harbour Version+C + * compiler Version used to create the Harbour runtime library + * $EXAMPLES$ + * ? QOUT(VERSION()) // Displays Harbour version only + * ? QOUT(VERSION(NIL)) // Displays Harbour and C Compiler versions + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * This function is an enhanced version of the CA-Clipper VERSION function. + * The CA-Clipper version does not have a parameter and it only returns + * the Version of the CA-Clipper Compiler. The Harbour version returns + * only the Harbour Version if called without the parameter, but + * returns both the Harbour Version and the Version of the C compiler used + * to build Harbour when the parameter is present. + * $PLATFORMS$ + * + * $FILES$ + * source/rtl/environ.c + * $SEEALSO$ + * OS() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * GETENV() + * $CATEGORY$ + * Environment + * $ONELINER$ + * Obtains DOS system environmental settings + * $SYNTAX$ + * GETENV(, ) --> + * $ARGUMENTS$ + * Enviromental variable to obtain + * Optional value to return if is not found + * $RETURNS$ + * Value of the Variable + * $DESCRIPTION$ + * This function yields a string that is the value of the + * environmental variable , witch is stored at the + * level with the Set command. If no environmental variable + * can be found, the value of the function will be a empty string. + * $EXAMPLES$ + * ? QOUT(GETENV('PATH')) + * ? QOUT(GETENV('CONFIG')) + * ? QOUT(GETENV('HARBOURCMD', '-n -l -es2')) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This functions is CA-CLIPPER compliant + * $PLATFORMS$ + * + * $FILES$ + * source/rtl/environ.c + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __RUN() + * $CATEGORY$ + * DOS + * $ONELINER$ + * Run a external program + * $SYNTAX$ + * __RUN( ) + * $CATEGORY$ + * DOS + * $ARGUMENTS$ + * 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 it cause 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) + * $FILES$ + * source/rtl/environ.c + * $SEEALSO$ + * RUN + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TONE() + * $CATEGORY$ + * Misc + * $ONELINER$ + * Sound a tone with a specifies frequency and duration + * $SYNTAX$ + * TONE( , ) --> NIL + * $ARGUMENTS$ + * is a non-negative numeric value that specifies the + * frequency of the tone in hertz. + * is a positive numeric value which specifies the duration + * of the tone in 1/18 of a second units. + * $RETURNS$ + * TONE() always return 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 + * $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 + * $STATUS$ + * S + * $COMPLIANCE$ + * TONE() works exactly like CA-Clipper's TONE(). + * $SEEALSO$ + * CHR(),SET BELL + * $END$ + */ diff --git a/harbour/doc/en/nation.txt b/harbour/doc/en/nation.txt new file mode 100644 index 0000000000..dd9dfb9ff4 --- /dev/null +++ b/harbour/doc/en/nation.txt @@ -0,0 +1,108 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Jose Lalin + * ISAFFIRM() documentation + * ISNEGATIVE() documentation + * NATIONMSG() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * ISAFFIRM() + * $CATEGORY$ + * NATION + * $ONELINER$ + * Checks if passed char is an affirmation char + * $SYNTAX$ + * ISAFFIRM( ) --> + * $ARGUMENTS$ + * is a char or string of chars + * $RETURNS$ + * True if passed char is an affirmation char, false otherwise + * $DESCRIPTION$ + * This function it is used to check if a user input is true or not + * regarding of the msgxxx module used. + * $EXAMPLES$ + * // Wait until user enters Y + * DO WHILE !ISAFFIRM( cYesNo ) + * ACCEPT "Sure: " TO cYesNo + * END DO + * $STATUS$ + * R + * $COMPLIANCE$ + * ISAFFIRM() is fully CA-Clipper compliant. + * $SEEALSO$ + * ISNEGATIVE(),NATIONMSG() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISNEGATIVE() + * $CATEGORY$ + * NATION + * $ONELINER$ + * Checks if passed char is a negation char + * $SYNTAX$ + * ISNEGATIVE( ) --> + * $ARGUMENTS$ + * is a char or string of chars + * $RETURNS$ + * True if passed char is a negation char, false otherwise + * $DESCRIPTION$ + * This function it is used to check if a user input is true or not + * regarding of the msgxxx module used. + * $EXAMPLES$ + * // Wait until user enters N + * DO WHILE !ISNEGATIVE( cYesNo ) + * ACCEPT "Sure: " TO cYesNo + * END DO + * $STATUS$ + * R + * $COMPLIANCE$ + * ISNEGATIVE() is fully CA-Clipper compliant. + * $SEEALSO$ + * ISAFFIRM(),NATIONMSG() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * NATIONMSG() + * $CATEGORY$ + * NATION + * $ONELINER$ + * Returns international strings messages. + * $SYNTAX$ + * NATIONMSG( ) --> + * $ARGUMENTS$ + * is the message number you want to get + * $RETURNS$ + * If is a valid message selector return the message, if + * is nil returns "Invalid Argument" and if is any other type it + * returns an empty string. + * $DESCRIPTION$ + * This functions returns international message descriptions. + * $EXAMPLES$ + * // Displays "Sure Y/N: " and waits until user enters Y + * // Y/N is the string for NATIONMSG( 12 ) with default natmsg module. + * DO WHILE !ISAFFIRM( cYesNo ) + * ACCEPT "Sure " + NATIONMSG( 12 ) + ": " TO cYesNo + * END DO + * $STATUS$ + * C + * $COMPLIANCE$ + * NATIONMSG() is fully CA-Clipper compliant. + * $SEEALSO$ + * ISAFFIRM(),ISNEGATIVE() + * $END$ + */ diff --git a/harbour/doc/en/objfunc.txt b/harbour/doc/en/objfunc.txt new file mode 100644 index 0000000000..470b49d142 --- /dev/null +++ b/harbour/doc/en/objfunc.txt @@ -0,0 +1,651 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * Documentation for all functions + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * __objHasData() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Determine whether a symbol exist in object as DATA + * $SYNTAX$ + * __objHasData( , ) --> lExist + * $ARGUMENTS$ + * is an object to scan. + * + * is the name of the symbol to look for. + * $RETURNS$ + * __objHasData() return .T. if the given exist as DATA + * (instance variable) in object , ) --> lExist + * $ARGUMENTS$ + * is an object to scan. + * + * is the name of the symbol to look for. + * $RETURNS$ + * __objHasMethod() return .T. if the given exist as METHOD + * (class function) in object , [] ) --> aNames + * $ARGUMENTS$ + * is an object to scan. + * + * is an optional logical value that specifies the information + * to return. A value of .T. instruct the function to return list of + * all DATA names, .F. return list of all METHOD names. Default value + * is .T. + * $RETURNS$ + * __objGetMsgList() return an array of character stings with all DATA + * names or all METHOD names for a given object. __objGetMsgList() + * would return an empty array {} if the given object does not contain + * the requested information. + * $DESCRIPTION$ + * __objGetMsgList() is a low level class support function that let you + * find all instance variable or class functions names for a given + * object. + * $EXAMPLES$ + * // show information about TBrowse class + * oB := TBrowseNew( 0, 0, 24, 79 ) + * aData := __objGetMsgList( oB, .T. ) + * aMethod := __objGetMsgList( oB, .F. ) + * FOR i = 1 to len ( aData ) + * ? "DATA name:", aData[ i ] + * NEXT + * FOR i = 1 to len ( aMethod ) + * ? "METHOD name:", aMethod[ i ] + * NEXT + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objGetMsgList() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __ObjGetMethodList(),__ObjGetValueList(),__objHasData(),__objHasMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objGetMethodList() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Return names of all METHOD for a given object + * $SYNTAX$ + * __objGetMethodList( ) --> aMethodNames + * $ARGUMENTS$ + * is an object to scan. + * $RETURNS$ + * __objGetMethodList() return an array of character stings with all + * METHOD names for a given object. __objGetMethodList() would return + * an empty array {} if the given object does not contain any METHOD. + * $DESCRIPTION$ + * __objGetMethodList() is a low level class support function that let + * you find all class functions names for a given object. + * It is equivalent to __objGetMsgList( oObject, .F. ). + * $EXAMPLES$ + * // show information about TBrowse class + * oB := TBrowseNew( 0, 0, 24, 79 ) + * aMethod := __objGetMethodList( oB ) + * FOR i = 1 to len ( aMethod ) + * ? "METHOD name:", aMethod[ i ] + * NEXT + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objGetMethodList() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objGetMsgList(),__ObjGetValueList(),__objHasData(),__objHasMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objGetValueList() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Return an array of DATA names and values for a given object + * $SYNTAX$ + * __objGetValueList( , [] ) --> aData + * $ARGUMENTS$ + * is an object to scan. + * + * is an optional array with DATA names you want to exclude + * from the scan. + * $RETURNS$ + * __objGetValueList() return a 2D array that contain pairs of a DATA + * symbol name and the value of DATA. __objGetValueList() would return + * an empty array {} if the given object does not contain the requested + * information. + * $DESCRIPTION$ + * __objGetValueList() is a low level class support function that + * return an array with DATA names and value, each array element is a + * pair of: aData[ i, HB_OO_DATA_SYMBOL ] contain the symbol name + * aData[ i, HB_OO_DATA_VALUE ] contain the value of DATA + * $EXAMPLES$ + * // show information about TBrowse class + * oB := TBrowseNew( 0, 0, 24, 79 ) + * aData := __objGetValueList( oB ) + * FOR i = 1 to len ( aData ) + * ? "DATA name:", aData[ i, HB_OO_DATA_SYMBOL ], ; + * " value=", aData[ i, HB_OO_DATA_VALUE ] + * NEXT + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objGetValueList() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * Header file is hboo.ch + * $SEEALSO$ + * __objGetMethodList(),__objGetMsgList(),__objHasData(),__objHasMethod(),__ObjSetValueList() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __ObjSetValueList() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Set object with an array of DATA names and values + * $SYNTAX$ + * __ObjSetValueList( , ) --> oObject + * $ARGUMENTS$ + * is an object to set. + * + * is a 2D array with a pair of instance variables and values + * for setting those variable. + * $RETURNS$ + * __ObjSetValueList() return a reference to . + * $DESCRIPTION$ + * __ObjSetValueList() is a low level class support function that let + * you set a group of instance variables with values. each array + * element in is a pair of: + * aData[ i, HB_OO_DATA_SYMBOL ] which contain the variable name to set + * aData[ i, HB_OO_DATA_VALUE ] contain the new variable value. + * $EXAMPLES$ + * // set some TBrowse instance variable + * oB := TBrowse():New() + * aData := array( 4, 2 ) + * aData[ 1, HB_OO_DATA_SYMBOL ] = "nTop" + * aData[ 1, HB_OO_DATA_VALUE ] = 1 + * aData[ 2, HB_OO_DATA_SYMBOL ] = "nLeft" + * aData[ 2, HB_OO_DATA_VALUE ] = 10 + * aData[ 3, HB_OO_DATA_SYMBOL ] = "nBottom" + * aData[ 3, HB_OO_DATA_VALUE ] = 20 + * aData[ 4, HB_OO_DATA_SYMBOL ] = "nRight" + * aData[ 4, HB_OO_DATA_VALUE ] = 70 + * __ObjSetValueList( oB, aData ) + * ? oB:nTop // 1 + * ? oB:nLeft // 10 + * ? oB:nBottom // 20 + * ? oB:nRight // 70 + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __ObjSetValueList() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * Header file is hboo.ch + * $SEEALSO$ + * __ObjGetValueList() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objAddMethod() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Add a METHOD to an already existing class + * $SYNTAX$ + * __objAddMethod( , , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of the new METHOD to add. + * + * is a pointer to a function to associate with the method. + * $RETURNS$ + * __objAddMethod() return a reference to . + * $DESCRIPTION$ + * __objAddMethod() is a low level class support function that add a + * new METHOD to an object. is unchanged if a symbol with the + * name already exist in . + * + * Note that is a special pointer to a function that was + * created using the @ operator, see example below. + * $EXAMPLES$ + * // create a new THappy class and add a Smile method + * oHappy := TClass():New( "THappy" ) + * __objAddMethod( oHappy, "Smile", @MySmile() ) + * ? oHappy:Smile( 1 ) // :) + * ? oHappy:Smile( 2 ) // ;) + * ? oHappy:Smile( 3 ) // *SMILE* + * + * STATIC FUNCTION MySmile( nType ) + * LOCAL cSmile + * DO CASE + * CASE nType == 1 + * cSmile := ":)" + * CASE nType == 2 + * cSmile := ";)" + * CASE nType == 3 + * cSmile := "*SMILE*" + * ENDCASE + * RETURN cSmile + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objAddMethod() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddInline(),__objAddData(),__objDelMethod(),__ObjGetMethodList(),__objGetMsgList(),__objHasMethod(),__objModMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objAddInline() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Add an INLINE to an already existing class + * $SYNTAX$ + * __objAddInline( , , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of the new INLINE to add. + * + * is a code block to associate with the INLINE method. + * $RETURNS$ + * __objAddInline() return a reference to . + * $DESCRIPTION$ + * __objAddInline() is a low level class support function that add a + * new INLINE method to an object. is unchanged if a symbol + * with the name already exist in . + * $EXAMPLES$ + * // create a new THappy class and add a Smile INLINE method + * oHappy := TClass():New( "THappy" ) + * bInline := { | nType | { ":)", ";)", "*SMILE*" }[ nType ] } + * __objAddInline( oHappy, "Smile", bInline ) + * ? oHappy:Smile( 1 ) // :) + * ? oHappy:Smile( 2 ) // ;) + * ? oHappy:Smile( 3 ) // *SMILE* + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objAddInline() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddData(),__objAddMethod(),__objDelInline(),__ObjGetMethodList(),__objGetMsgList(),__objHasMethod() ,__objModInline() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objAddData() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Add a DATA to an already existing class + * $SYNTAX$ + * __objAddData( , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of the new DATA to add. + * $RETURNS$ + * __objAddData() return a reference to . + * $DESCRIPTION$ + * __objAddData() is a low level class support function that add a new + * DATA to an object. is unchanged if a symbol with the name + * already exist in . + * $EXAMPLES$ + * // create a new THappy class and add a lHappy DATA + * oHappy := TClass():New( "THappy" ) + * __objAddData( oHappy, "lHappy" ) + * oHappy:lHappy := .T. + * IF oHappy:lHappy + * ? "Happy, Happy, Joy, Joy !!!" + * ELSE + * ? ":(..." + * ENDIF + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objAddData() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddInline(),__objAddMethod(),__objDelData(),__objGetMsgList(),__ObjGetValueList(),__objHasData(),__ObjSetValueList() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objModMethod() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Modify (replace) a METHOD in an already existing class + * $SYNTAX$ + * __objModMethod( , , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of the METHOD to modify. + * + * is a pointer to a new function to associate with the + * method. + * $RETURNS$ + * __objModMethod() return a reference to . + * $DESCRIPTION$ + * __objModMethod() is a low level class support function that modify + * a METHOD in an object and replace it with a new function. + * is unchanged if a symbol with the name does not exist + * in . __objModMethod() is used in inheritance mechanism. + * + * Note that is a special pointer to a function that was + * created using the @ operator, see example below. + * $EXAMPLES$ + * // create a new THappy class and add a Smile method + * oHappy := TClass():New( "THappy" ) + * __objAddMethod( oHappy, "Smile", @MySmile() ) + * ? oHappy:Smile( 1 ) // :) + * ? oHappy:Smile( 2 ) // ;) + * // replace Smile method with a new function + * __objAddMethod( oHappy, "Smile", @YourSmile() ) + * ? oHappy:Smile( 1 ) // *SMILE* + * ? oHappy:Smile( 2 ) // *WINK* + * + * STATIC FUNCTION MySmile( nType ) + * LOCAL cSmile + * DO CASE + * CASE nType == 1 + * cSmile := ":)" + * CASE nType == 2 + * cSmile := ";)" + * ENDCASE + * RETURN cSmile + * + * STATIC FUNCTION YourSmile( nType ) + * LOCAL cSmile + * DO CASE + * CASE nType == 1 + * cSmile := "*SMILE*" + * CASE nType == 2 + * cSmile := "*WINK*" + * ENDCASE + * RETURN cSmile + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objModMethod() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddMethod(),__objDelMethod(),__ObjGetMethodList(),__objGetMsgList(),__objHasMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objModInline() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Modify (replace) an INLINE method in an already existing class + * $SYNTAX$ + * __objModInline( , , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of the INLINE method to modify. + * + * is a new code block to associate with the INLINE method. + * $RETURNS$ + * __objModInline() return a reference to . + * $DESCRIPTION$ + * __objModInline() is a low level class support function that modify + * an INLINE method in an object and replace it with a new code block. + * is unchanged if a symbol with the name does + * not exist in . __objModInline() is used in inheritance + * mechanism. + * $EXAMPLES$ + * // create a new THappy class and add a Smile INLINE method + * oHappy := TClass():New( "THappy" ) + * bMyInline := { | nType | { ":)", ";)" }[ nType ] } + * bYourInline := { | nType | { "*SMILE*", "*WINK*" }[ nType ] } + * __objAddInline( oHappy, "Smile", bMyInline ) + * ? oHappy:Smile( 1 ) // :) + * ? oHappy:Smile( 2 ) // ;) + * // replace Smile inline method with a new code block + * __objModInline( oHappy, "Smile", bYourInline ) + * ? oHappy:Smile( 1 ) // *SMILE* + * ? oHappy:Smile( 2 ) // *WINK* + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objModInline() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddInline(),__objDelInline(),__ObjGetMethodList(),__objGetMsgList(),__objHasMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objDelMethod() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Delete a METHOD from class + * $SYNTAX$ + * __objDelMethod( , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of METHOD or INLINE method to be + * deleted (removed) from the object. + * $RETURNS$ + * __objDelMethod() return a reference to . + * $DESCRIPTION$ + * __objDelMethod() is a low level class support function that delete + * (remove) a METHOD or an INLINE method from an object. is + * unchanged if a symbol with the name does not exist in + * . + * + * __objDelInline() is exactly the same as __objDelMethod(). + * $EXAMPLES$ + * // create a new THappy class and add a Smile method + * oHappy := TClass():New( "THappy" ) + * __objAddMethod( oHappy, "Smile", @MySmile() ) + * ? __objHasMethod( oHappy, "Smile" ) // .T. + * // remove Smile method + * __objDelMethod( oHappy, "Smile" ) + * ? __objHasMethod( oHappy, "Smile" ) // .F. + * + * STATIC FUNCTION MySmile( nType ) + * LOCAL cSmile + * DO CASE + * CASE nType == 1 + * cSmile := ":)" + * CASE nType == 2 + * cSmile := ";)" + * ENDCASE + * RETURN cSmile + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objDelMethod() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddInline(),__objAddMethod(),__ObjGetMethodList(),__objGetMsgList(),__objHasMethod(),__objModInline(),__objModMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objDelInline() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Delete a METHOD INLINE from class + * $SYNTAX$ + * __objDelInline( , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of METHOD or INLINE method to be + * deleted (removed) from the object. + * $RETURNS$ + * __objDelInMethod() return a reference to . + * $DESCRIPTION$ + * __objDelInMethod() is a low level class support function that delete + * (remove) a METHOD or an INLINE method from an object. is + * unchanged if a symbol with the name does not exist in + * . + * $EXAMPLES$ + * // create a new THappy class and add a Smile method + * oHappy := TClass():New( "THappy" ) + * __objAddMethod( oHappy, "Smile", @MySmile() ) + * ? __objHasMethod( oHappy, "Smile" ) // .T. + * // remove Smile method + * __objDelInMethod( oHappy, "Smile" ) + * ? __objHasMethod( oHappy, "Smile" ) // .F. + * + * STATIC FUNCTION MySmile( nType ) + * LOCAL cSmile + * DO CASE + * CASE nType == 1 + * cSmile := ":)" + * CASE nType == 2 + * cSmile := ";)" + * ENDCASE + * RETURN cSmile + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objDelMethod() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddInline(),__objAddMethod(),__ObjGetMethodList(),__objGetMsgList(),__objHasMethod(),__objModInline(),__objModMethod() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __objDelData() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Delete a DATA (instance variable) from class + * $SYNTAX$ + * __objDelMethod( , ) --> oObject + * $ARGUMENTS$ + * is the object to work on. + * + * is the symbol name of DATA to be deleted (removed) from + * the object. + * $RETURNS$ + * __objDelData() return a reference to . + * $DESCRIPTION$ + * __objDelData() is a low level class support function that delete + * (remove) a DATA from an object. is unchanged if a symbol + * with the name does not exist in . + * $EXAMPLES$ + * // create a new THappy class and add a lHappy DATA + * oHappy := TClass():New( "THappy" ) + * __objAddData( oHappy, "lHappy" ) + * ? __objHasData( oHappy, "lHappy" ) // .T. + * // remove lHappy DATA + * __objDelData( oHappy, "lHappy" ) + * ? __objHasData( oHappy, "lHappy" ) // .F. + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __objDelData() is a Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddData(),__objGetMsgList(),__ObjGetValueList(),__objHasData(),__ObjSetValueList() + * $END$ + */ diff --git a/harbour/doc/en/rdd.txt b/harbour/doc/en/rdd.txt new file mode 100644 index 0000000000..e869eaebce --- /dev/null +++ b/harbour/doc/en/rdd.txt @@ -0,0 +1,3541 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Luiz Rafael Culik + * DB*() documentation + * ORD*() documentation + * RDD*() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * AFIELDS() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Fills referenced arrays with database field information + * $SYNTAX$ + * AFields([,][,][,]) --> + * $ARGUMENTS$ + * Array of field names + * Array of field names + * Array of field names + * Array of field names + * $RETURNS$ + * Number od fields in a database or work area + * $DESCRIPTION$ + * This function will fill a series of arrays with field + * names,field types,field lenghts, and number of field + * decimal positions for the currently selected or designed + * database. Each array parallels the different descriptors + * of a file's structure.The first array will consist of the + * names of the fields in the current work area.All other arrays + * are optional and will be filled with the corrensponding data. + * This function will return zero if no parameters are specified + * or if no database is avaliable in the current work area.Otherwise, + * the number of fields or the lenght of the shortest array argument, + * witchever is smaller, will be returned. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL aNames:={},aTypes:={},aLens:={},aDecs:={},nFields:=0 + * + * USE Test + * + * dbGoTop() + * nFields:=aFields(aNames,aTypes,aLens,aDecs) + * + * ? "Number of fields", nFields + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * AFIELDS() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ALIAS() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Returns the alias name of a work area + * $SYNTAX$ + * Alias([]) --> + * $ARGUMENTS$ + * Number of a work area + * $RETURNS$ + * Name of alias + * $DESCRIPTION$ + * This function returns the alias of the work area indicated by + * If is not provided, the alias of the current work area is + * returned. + * $EXAMPLES$ + * FUNCTION Main() + * + * USE Test + * select 0 + * qOut( IF(Alias()=="","No Name",Alias())) + * Test->(qOut(Alias()) + * qOut(Alias(1)) + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * ALIAS() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBEVAL() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Performs a code block operation on the current DATA BASE + * $SYNTAX$ + * DBEVAL( , + * [], [], + * [], [], + * [] ) --> NIL + * $ARGUMENTS$ + * Operation that is to be performed + * Code block for the For condition + * Code block for the WHILE condition + * Number of NEXT records to process + * Record number to work on exactly + * Toggle to rewind record pointer + * $RETURNS$ + * NIL + * $DESCRIPTION$ + * Performs a code block operation on the current DATA BASE + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL nCount + * + * USE Test + * + * dbGoto( 4 ) + * ? RecNo() + * COUNT TO nCount + * ? RecNo(), nCount + * COUNT TO nCount NEXT 10 + * ? RecNo(), nCount + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * S + * $COMPLIANCE$ + * DBEVAL is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBF() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Alias name of a work area + * $SYNTAX$ + * Dbf() --> + * $ARGUMENTS$ + * + * $RETURNS$ + * Name of alias + * $DESCRIPTION$ + * This function returns the same alias name ofthe currently selected work + * area. + * $EXAMPLES$ + * FUNCTION Main() + * + * USE Test + * + * select 0 + * qOut( IF(DBF()=="","No Name",DBF())) + * Test->(qOut(DBF()) + * qOut(Alias(1)) + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * DBF() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * BOF() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Test for the beggining-of-file condition + * $SYNTAX$ + * BOF() --> + * $ARGUMENTS$ + * + * $RETURNS$ + * Logical true (.T.) or false (.F.) + * $DESCRIPTION$ + * This function determines if the beggining of the file marker has been + * reached. If so, the function will return a logical true (.T.); otherwise, + * a logical false(.F.) will be returned. + * By default, BOF() will apply to the currently selected database unless + * the function is preceded by an alias + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests NEW + * DBGOTOP() + * ? "Is Eof()",EOF() + * DBGOBOTTOM() + * ? "Is Eof()",EOF() + * USE + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BOF() is fully CA-Clipper compliant. + * $SEEALSO$ + * EOF(),FOUND(),LASTREC() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBAPPEND() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Appends a new record to a database file. + * $SYNTAX$ + * DbAppend(<]) --> NIL + * $ARGUMENTS$ + * Toggle to release record locks + * $RETURNS$ + * $DESCRIPTION$ + * This function add a new record to the end of the database + * in the selected or aliased work area. All fields in that + * database will be given empty data values - character fields + * will be filled with blank spaces,date fields with CTOD('//'), + * numeric fields with 0,logical fields with .F., and memo fields + * with NULL bytes.The header of the database is not updated until + * the record is flushed from the buffer and the contents are + * written to the disk. + * Under a networking enviroment, DBAPPEND() performs an addi- + * tional operation: It attrmps to lock the newly added record. If + * the database file is currently locked or if a locking assignment + * if made to LASTREC()+1,NETERR() will return a logical true (.T.) + * immediately after the DBAPPEND() function. This function does + * not unlock the locked records. + * If is passed a logical true (.T.) value, it will + * release the record locks, which allows the application to main- + * tain multiple record locks during an appending operation. The + * default for this parameter is a logical false (.F.). + * $EXAMPLES$ + * FUNCTION Main() + * + * USE Test + * local cName="HARBOUR",nId=10 + * Test->(DbAppend()) + * Replace Test->Name wit cName,Id with nId + * Use + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * DBAPPEND() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBCLEARFILTER() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Clears the current filter condiction in a work area + * $SYNTAX$ + * DbClearFilTer() -> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * + * $DESCRIPTION$ + * This function clears any active filter condiction + * for the current or selected work area. + * $EXAMPLES$ + * Function Main() + * + * Use Test + * + * Set Filter to Left(Test->Name,2) == "An" + * + * Dbedit() + * + * Test->(DbClearFilter()) + * + * USE + * + * Return Nil + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * DBCLEARFILTER() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBCLOSEALL() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Close all open files in all work areas. + * $SYNTAX$ + * DbCloseAll() -> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBCLOSEALL always return NIL + * $DESCRIPTION$ + * This function close all open databases and all associated + * indexes.In addition, it closes all format files and moves + * the work area pointer to the first position + * $EXAMPLES$ + * Function Main() + * + * Use Test New + * + * DbEdit() + * + * Use Test1 New + * + * DbEdit() + * + * DbCloseAll() + * + * USE + * + * Return Nil + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * DBCLOSEALL() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBCLOSEAREA() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Close a database file in a work area. + * $SYNTAX$ + * DbCloseArea() -> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * + * $DESCRIPTION$ + * This function will close any database open in the selected + * or aliased work area. + * $EXAMPLES$ + * Function Main() + * + * Use Test + * + * Dbedit() + * + * Test->(DbCloseArea()) + * + * USE + * + * Return Nil + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * DBCLOSEAREA() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBCOMMIT() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Updates all index and database buffers for a given workarea + * $SYNTAX$ + * DBCOMMIT() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBCOMMIT() always returns NIL. + * $DESCRIPTION$ + * This function updates all of the information for a give,selected, + * or active workarea.This operation includes all database and index + * buffers for that work area only. This function does not update all + * open work areas. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL cName:=SPACE(40) + * LOCAL nId:=0 + * USE Test EXCLUSIVE NEW + * // + * @ 10, 10 GET cName + * @ 11, 10 GET nId + * READ + * // + * IF UPDATED() + * APPEND BLANK + * REPLACE Tests->Name WITH cName + * REPLACE Tests->Id WITH nId + * Tests->( DBCOMMIT() ) + * ENDIF + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * DBCLOSEALL(),DBCOMMITALL(),DBUNLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBCOMMITALL() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Flushes the memory buffer and performs a hard-disk write + * $SYNTAX$ + * DBCOMMIT() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBCOMMIT() always returns NIL. + * $DESCRIPTION$ + * This function performs a hard-disk write for all work areas. + * Before the disk write is performed,all buffers are flushed. + * open work areas. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL cName:=SPACE(40) + * LOCAL nId:=0 + * USE Test EXCLUSIVE NEW + * USE TestId New INDEX Testid + * // + * @ 10, 10 GET cName + * @ 11, 10 GET nId + * READ + * // + * IF UPDATED() + * APPEND BLANK + * REPLACE Tests->Name WITH cName + * REPLACE Tests->Id WITH nId + * IF !TestId->(DBSEEK(nId)) + * APPEND BLANK + * REPLACE Tests->Id WITH nId + * ENDIF + * ENDIF + * DBCOMMITALL() + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * DBCLOSEALL(),DBCOMMIT(),DBUNLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __DBCONTINUE() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Resume a pending LOCATE + * $SYNTAX$ + * __DbCONTINUE() -> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * __DbCONTINUE() Always return nil + * $DESCRIPTION$ + * __DBCONTINUE is a database command that searches from the current record + * position for the next record meeting the most recent LOCATE condition + * executed in the current work area. It terminates when a match is found + * or end of file is encountered. If __DBCONTINUE is successful, the matching + * record becomes the current record and FOUND() returns true (.T.); if + * unsuccessful, FOUND() returns false (.F.). + * + * Each work area may have an active LOCATE condition. In CA-Clipper, a + * LOCATE condition remains pending until a new LOCATE condition is + * specified. No other commands release the condition. + * + * Notes + * + * Scope and WHILE condition: Note that the scope and WHILE + * condition of the initial LOCATE are ignored; only the FOR condition + * is used with CONTINUE. If you are using a LOCATE with a WHILE + * condition and want to continue the search for a matching record, use + * SKIP and then repeat the original LOCATE statement adding REST as the + * scope. + * + * $EXAMPLES$ + * This example scans records in Sales.dbf for a particular + * salesman and displays a running total sales amounts: + * + * LOCAL nRunTotal := 0 + * USE Sales NEW + * LOCATE FOR Sales->Salesman = "1002" + * DO WHILE FOUND() + * ? Sales->Salesname, nRunTotal += Sales->Amount + * __DBCONTINUE() + * ENDDO + * + * This example demonstrates how to continue if the pending + * LOCATE scope contains a WHILE condition: + * + * LOCAL nRunTotal := 0 + * USE Sales INDEX Salesman NEW + * SEEK "1002" + * LOCATE REST WHILE Sales->Salesman = "1002"; + * FOR Sales->Amount > 5000 + * DO WHILE FOUND() + * ? Sales->Salesname, nRunTotal += Sales->Amount + * SKIP + * LOCATE REST WHILE Sales->Salesman = "1002"; + * FOR Sales->Amount > 5000 + * ENDDO + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * + * $SEEALSO$ + * EOF(),FOUND() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBCREATE() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Creates an empty database from a array. + * $SYNTAX$ + * DBCREATE(, ,[],[],[]) --> NIL + * $ARGUMENTS$ + * Name of database to be create + * Name of a multidimensional array that contains the a database + * structure + * Name of the RDD + * Toggle to Open the create File + * Name of database Alias + * $RETURNS$ + * DBCREATE() always returns NIL. + * $DESCRIPTION$ + * This function creates the database file specified as from the + * multidimensional array .If no file extension is use with + * the .DBF extension is assumed. + * The array specified in must follow a few guidelines when being + * built prior to a call to DBCREATE(): + * + * - All subscripts values in the second dimension must be set to proper values + * + * - The fourth subscript value in the second dimension - which contains + * the decimal value-must he specified. even 1kw nonnumeric fields. + * + * - The second subscript value in the second dimension-which contains + * the field data type-must contain a proper value: C, D, L, M or N + * It is possible to use additional letters (or clarity (e.g., 'Numeric' + * for 'N'): however, the first letter of this array element must + * be a proper value. + * + * The DBCREATE( ) function does not use the decimal field to + * calculate the length of a character held longer than 256. Values + * up to the maximum length of a character field (which is 65,519 bytes) + * are stored directly in the database in the length attribute if that + * database was created via this function. However, a file containing + * fields longer than 256 bytes is not compatible with any interpreter. + * + * The parameter specifies the name of the Replaceable Da- + * tabase Driver to use to create the database. If it is not specified, then the + * Replaceable Database Driver in the current work area is tised. + * The parameter specifies if the already created database is to be opened, + * The parameter specifies the alias name for the new opened database + * $EXAMPLES$ + * function main() + * + * local nI, aStruct := { { "CHARACTER", "C", 25, 0 }, ; + * { "NUMERIC", "N", 8, 0 }, ; + * { "DOUBLE", "N", 8, 2 }, ; + * { "DATE", "D", 8, 0 }, ; + * { "LOGICAL", "L", 1, 0 }, ; + * { "MEMO1", "M", 10, 0 }, ; + * { "MEMO2", "M", 10, 0 } } + * + * REQUEST DBFCDX + * + * dbCreate( "testdbf", aStruct, "DBFCDX", .t., "MYALIAS" ) + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is Not CA-Clipper compliant + * $SEEALSO$ + * AFIELDS(),DBSTRUCT() + * $INCLUDE$ + * "Dbstruct.ch" + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBDELETE() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Marks records for deletion in a database. + * $SYNTAX$ + * DBDELETE() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBDELETE() always returns NIL. + * $DESCRIPTION$ + * This function marks a record for deletion in the selected + * or aliased work area.If the DELETED setting is on, the record + * will still be visible until the record pointer in that work area + * is moved to another record. + * In a networking situation, this function requires that the record + * be locked prior to issuing the DBDELETE() function. + * $EXAMPLES$ + * nId:=10 + * USE TestId INDEX TestId NEW + * IF TestId->(DBSEEK(nId)) + * IF TestId->(RLOCK()) + * DBDELETE() + * ENDIF + * ENDIF + * USE + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * DBRECALL() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBFILTER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the filter expression in a work area + * $SYNTAX$ + * DBFILTER() --> cFilter + * $ARGUMENTS$ + * + * $RETURNS$ + * DBFILTER() returns the filter expression. + * $DESCRIPTION$ + * This function return the expression of the SET FILTER TO command + * for the current or designated work area. If no filter condition + * is present,a NULL string will be returned. + * $EXAMPLES$ + * USE Test INDEX Test NEW + * SET FILTER TO Name= "Harbour" + * USE TestId INDEX TestId NEW + * SET FILTER TO Id = 1 + * SELECT Test + * // + * ? DBFILTER() + * ? TestId->(DBFILTER()) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * DBRELATION(),DBRSELECT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBGOBOTTOM() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Moves the record pointer to the bottom of the database. + * $SYNTAX$ + * DBGOBOTTOM() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBGOBOTTOM() always returns NIL. + * $DESCRIPTION$ + * This function moves the record pointer in the selected or aliased + * work area to the end of the file.The position of the record pointer + * is affected by the values in the index key or by an active FILTER + * condition.Otherwise,if no index is active or if no filter condition + * is present,the value of the record pointer will be LASTREC(). + * $EXAMPLES$ + * USE Tests + * DBGOTOP() + * ? RECNO() + * DBGOBOTTOM() + * ? RECNO() + * USE + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * BOF(),EOF(),DBSKIP(),DBSEEK(),DBGOTOP() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBGOTO() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Position the record pointer to a specific location. + * $SYNTAX$ + * DBGOTO() --> NIL + * $ARGUMENTS$ + * Record number or unique identity + * $RETURNS$ + * DBGOTO() always returns NIL. + * $DESCRIPTION$ + * This function places the record pointer,if working with a .DBF file, + * in selected or aliased work area at the record number specified by + * .The position if not affected by an active index or + * by any enviromental SET condiction. + * Issuing a DBGOTO(RECNO()) call in a network enviroment will refresh + * the database and index buffers.This is the same as a DBSKIP(0) call. + * The parameter may be something other than a record + * number.In some data formats, for example, the value of + * is a unique primary key while in other formats, could + * be an array offset if the data set was an array. + * $EXAMPLES$ + * + * The following example uses DBGOTO() to iteratively process + * every fourth record: + * + * DBUSEAREA( .T., "DBFNTX", "Sales", "Sales", .T. ) + * // + * // toggle every fourth record + * DO WHILE !EOF() + * DBGOTO( RECNO() + 4 ) + * Sales->Group := "Bear" + * ENDDO + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * BOF(),EOF(),DBGOTOP(),DBGOBOTTOM(),DBSEEK(),DBSKIP() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBGOTOP() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Moves the record pointer to the bottom of the database. + * $SYNTAX$ + * DBGOTOP() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBGOTOP() always returns NIL. + * This function moves the record pointer in the selected or aliased + * work area to the top of the file.The position of the record pointer + * is affected by the values in the index key or by an active FILTER + * condition.Otherwise,if no index is active or if no filter condition + * is present,the value of RECNO() will be 1. + * $EXAMPLES$ + * USE Tests + * DBGOTOP() + * ? RECNO() + * DBGOBOTTOM() + * ? RECNO() + * USE + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * BOF(),EOF(),DBSKIP(),DBSEEK(),DBGOBOTTOM() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBRECALL() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Recalls a record previousy marked for deletion. + * $SYNTAX$ + * DBRECALL() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBRECALL() always returns NIL. + * $DESCRIPTION$ + * This function unmarks those records marked for deletion nd reactivates + * them in the aliased or selected work area.If a record is DELETED and + * the DELETED setting is on, the record will still be visible for a + * DBRECALL() provided that the database record pointer has not been + * skipped.Once a record marked for deletion with the DELETE setting ON + * has been skipped, it no longer canbe brought back with DBRECALL(). + * $EXAMPLES$ + * USE Test NEW + * DBGOTO(10) + * DBDELETE() + * ? DELETED() + * DBRECALL() + * ? DELETED() + * USE + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * DBDELETE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBRLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * This function locks the record basedon identify + * $SYNTAX$ + * DBRLOCK([]) --> lSuccess + * $ARGUMENTS$ + * Record indetifier + * $RETURNS$ + * DBRLOCK() returns a logical true (.T.) if lock was successful + * $DESCRIPTION$ + * This function attempts to lock a record which is indentified + * by in the active data set.If the lock is successful + * the function will return a logical true (.T.) value;otherwise + * a logical false (.F.) will be returned.If is not + * passed it will be assumed to lock the current active record/data item. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL x:=0 + * USE Tests New + * FOR x:=1 to reccount() + * IF !DBRLOCK() + * DBUNLOCK() + * ENDIF + * NEXT + * USE + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUNLOCK(),DBUNLOCKALL(),FLOCK(),RLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBRLOCKLIST() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * This function return a list of records in the database work area + * $SYNTAX$ + * DBRLOCKLIST() --> aRecordLocks + * $ARGUMENTS$ + * + * $RETURNS$ + * DBRLOCKLIST() return a array of lock records + * $DESCRIPTION$ + * This function will return an array of locked records in a given + * and active work area.If the return array is an empty array + * (meaning no elements in it),then there are no locked record in that + * work area. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL aList:={} + * LOCAL x:=0 + * USE Tests NEW + * DBGOTO(10) + * RLOCK() + * DBGOTO(100) + * RLOCK() + * aList:=DBRLOCKLIST() + * FOR x:=1 TO LEN(aList) + * ? aList[x] + * NEXT + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * RLOCK(),DBRLOCK(),DBRUNLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBRUNLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Unlocks a record base on its indentifier + * $SYNTAX$ + * DBRUNLOCK([]) --> NIL + * $ARGUMENTS$ + * Record indentifier,tipicaly a record number + * $RETURNS$ + * DBRUNLOCK() always returns NIL. + * $DESCRIPTION$ + * This function will attempt to unlock the record specified as + * ,which in a .DBF format is the record number.If not + * specified,them the current active record/data item will be + * unlocked + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests New + * DBGOTO(10) + * IF RLOCK() + * ? Tests->ID + * DBRUNLOCK() + * ENDIF + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * RLOCK(),DBRLOCK(),DBRLOCKLIST() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBSEEK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Searches for a value based on an active index. + * $SYNTAX$ + * DBSEEK(, [],[]) --> lFound + * $ARGUMENTS$ + * Any expression + * Toggle SOFTSEEK condition + * is an optional logical value that set the current + * record position to the last record if successful + * $RETURNS$ + * DBSEEK() returns logical true (.T.) if found, otherwise false + * $DESCRIPTION$ + * This function searches for the first record in a database file whose index + * key matches . If the item is found, the function will return a logical + * true (.T.), the value of FOUND() wilI be a logical true (.T.), and the value of + * EOF() wilI be a logical false (.F.). If no item is found. then the function will + * return a logical false, the value of FOUND( ) will be a logical false (.F.), and + * the value of EOF( ) will be a logical true (.T.). + * This function always "rewinds" the database pointer and starts the search from + * the top of the file. + * If the SOFTSEEK flag is on or if is set to a logical true (.T.) + * the value of FOUND() wilI be a logical false and EOF() will he a logical + * false if there is an item in the index key with a greater value than the key + * expression ; at this point the record pointer will position itself on that + * record. However, if there is no greater key in the index,EOF() will return a + * logical true (.T.) value. If is not passed, the function will look + * to the internal status of SOFTSEEK before performing the operation. The default + * of is a logical false (.F.) + * + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests New INDEX Tests + * DBGOTO(10) + * nId:=Tests->nId + * IF Tests->(DBSEEK(nId)) + * IF RLOCK() + * ? Tests->Name + * DBRUNLOCK() + * ENDIF + * ENDIF + * USE + * RETURN NIL + * + * ACCEPT "Employee name: " TO cName + * IF ( Employee->(DBSEEK(cName)) ) + * Employee->(ViewRecord()) + * ELSE + * ? "Not found" + * END + * + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * DBSEEK() is Compatible with CA-Clipper 5.3 + * $SEEALSO$ + * DBGOBOTTOM(),DBGOTOP(),DBSKIP(),EOF(),BOF(),FOUND() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBSELECTAREA() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Change to another work area + * $SYNTAX$ + * DBSELECTAREA() --> NIL + * $ARGUMENTS$ + * Alias or work area + * $RETURNS$ + * DBSELECTAREA() always returns NIL. + * $DESCRIPTION$ + * This function moves the Harbour internal primary focus to the work + * area designated by . If is numeric, them it will + * select the numeric work area;if is character,then it will + * select the work area with the alias name. + * DBSELECTAREA(0) will select the next avaliable and unused work area. + * Up to 255 work areas are supported.Each work area has its own alias + * and record pointer, as well as its own FOUND(),DBFILTER(),DBRSELECT(), + * and DBRELATION() function values. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL nId + * USE Tests NEW INDEX Tests + * USE Tests1 NEW INDEX Tests1 + * DBSELECTAREA(1) + * nId:=Tests->Id + * DBSELECTAREA(2) + * IF DBSEEK(nId) + * ? Tests1->cName + * ENDIF + * DBCLOSEALL() + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-CLIPPER compatible. + * $SEEALSO$ + * DBUSEAREA(),SELECT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBSETDRIVER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Establishes the name of replaceable daabas driver for a selected work area + * $SYNTAX$ + * DBSETDRIVER([]) --> cCurrentDriver + * $ARGUMENTS$ + * Optional database driver name + * $RETURNS$ + * DBSETDRIVER() returns the name of active driver + * $DESCRIPTION$ + * This function returns the name of the current database driver for the + * selected work area. The default will be "DBFNTX". If specified, + * contains the name of the database driver that should be used to activate + * and manage the work area.If the specified driver is not avaliable,this + * function will have no effect. + * $EXAMPLES$ + * DBSETDRIVER("ADS") + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compatible + * $SEEALSO$ + * DBUSEAREA() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBSKIP() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Moves the record pointer in the selected work area. + * $SYNTAX$ + * DBSKIP([]) --> NIL + * $ARGUMENTS$ + * Numbers of records to move record pointer. + * $RETURNS$ + * DBSKIP() always returns NIL. + * $DESCRIPTION$ + * This function moves the record pointer in the selected or + * aliased work area.The default value for will be 1. + * A DBSKIP(0) will flush and refresh the internal database bufer and make + * any changes made to the record visible without moving the record pointer + * in either direction. + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests NEW + * DBGOTOP() + * WHILE !EOF() + * ? Tests->Id,Tests->Name + * DBSKIP() + * ENDDO + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-CLIPPER compatible + * $SEEALSO$ + * BOF(),DBGOBOTTOM(),DBGOTOP(),DBSEEK(),EOF() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBSETFILTER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Establishes a filter condition for a work area. + * $SYNTAX$ + * DBSETFILTER(, []) --> NIL + * $ARGUMENTS$ + * Code block expression for filtered evaluation. + * Optional character expression of code block. + * $RETURNS$ + * DBSETFILTER() always returns NIL. + * $DESCRIPTION$ + * This function masks a database so that only those records that meet the + * condition prescribed by the expression in the code block + * and literally expressed as are visible. + * If is not passed to this function,then the DBFILTER() + * function will return an empty string showing no filter in that work area + * which in fact,would be not correct. + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests NEW + * DBSETFILTER({|| Tests->Id <100},"Tests->Id <100") + * DBGOTOP() + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBFILTER(),DBCLEARFILTER() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBSTRUCT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Creates a multidimensional array of a database structure. + * $SYNTAX$ + * DBSTRUCT() --> aStruct + * $ARGUMENTS$ + * + * $RETURNS$ + * DBSTRUCT() returns an array pointer to database structure + * $DESCRIPTION$ + * This function returns a multidimensional array.This array has array + * pointers to other arrays,each of which contains the characteristic + * of a field in the active work area.The lenght of this array is based + * in the number of fields in that particular work area.In other words, + * LEN(DBSTRUCT()) is equal to the value obtained from FCOUNT(). + * Each subscript position + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL aStru,x + * USE Tests NEW + * aStru:=DBSTRUCT() + * FOR x:=1 TO LEN(aStru) + * ? aStru[x,1] + * NEXT + * USE + * RETURN NIL + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * AFIELDS() + * $INCLUDE$ + * DbStruct.ch + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBUNLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Unlock a record or release a file lock + * $SYNTAX$ + * DBUNLOCK() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBUNLOCK() always returns NIL. + * $DESCRIPTION$ + * This function releases the file or record lock in the currently selected + * or aliased work area.It will not unlock an associated lock in a related data- + * bases. + * $EXAMPLES$ + * nId:=10 + * USE TestId INDEX TestId NEW + * IF TestId->(DBSEEK(nId)) + * IF TestId->(RLOCK()) + * DBDELETE() + * ELSE + * DBUNLOCK() + * ENDIF + * ENDIF + * USE + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compatible. + * $SEEALSO$ + * DBUNLOCKALL(),FLOCK(),RLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBUNLOCKALL() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Unlocks all records and releases all file locks in all work areas. + * $SYNTAX$ + * DBUNLOCKALL() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBUNLOCKALL() always returns NIL. + * $DESCRIPTION$ + * This function will remove all file and record locks in all work area. + * $EXAMPLES$ + * nId:=10 + * USE Tests INDEX TestId NEW + * USE Tests1 INDEX Tests NEW + * IF TestId->(DBSEEK(nId)) + * IF TestId->(RLOCK()) + * DBDELETE() + * ELSE + * DBUNLOCK() + * ENDIF + * ELSE + * DBUNLOCKALL() + * ENDIF + * USE + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUNLOCK(),FLOCK(),RLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DBUSEAREA() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Opens a work area and uses a database file. + * $SYNTAX$ + * DBUSEAREA( [], [], , [], + * [], []) --> NIL + * $ARGUMENTS$ + * A optional logical expression for the new work area + * Database driver name + * File Name + * Alias name + * Shared/exclusive status flag + * Read-write status flag. + * $RETURNS$ + * DBUSEAREA() always returns NIL. + * $DESCRIPTION$ + * This function opens an existing database named in the current + * work area. If is set to a logical true (.T.) value, then + * the database will be opened in the next available and unused + * work area. The default value of is a logical false (.F.). + * If used, is the name of the database driver associated with + * the file that is opened. The default for this will be the value + * of DBSETDRlVER(). + * IF used, contains the alias name for that work area, If not + * specified, the root name of the database specified in will be + * used. + * If is set to a logical true (.T.) value, the database that + * is specified in will be opened by the user EXCLUSIVELY. Thus + * locking it from all other nodes or users on the network. If is + * set to a logical false (.F.) value, then the database will be in SHARED + * mode. If is not passed, then the function will turn to the + * internal setting of SET EXCLUSIVE to determine a setting. + * If is specified, the file will be set to READ ONLY mode. + * If it is not specified, the file will he opened in normal read-write + * mode. + * $EXAMPLES$ + * DBUSEAREA(.T.,,"Tests") + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * DBCLOSEAREA(),DBSETDRIVER(),SELECT(),SET() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __DBZAP() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Remove all records from the current database file + * $SYNTAX$ + * __DbZap() -> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * __DbZap() will always return nil + * $DESCRIPTION$ + * __DbZap*( is a database command that permanently removes all records from + * files open in the current work area. This includes the current database + * file, index files, and associated memo file. Disk space previously + * occupied by the ZAPped files is released to the operating system. + * __DbZap() performs the same operation as DELETE ALL followed by PACK but is + * almost instantaneous. + * + * To ZAP in a network environment, the current database file must be USEd + * EXCLUSIVEly. + * + * $EXAMPLES$ + * This example demonstrates a typical ZAP operation in a network + * environment: + * + * USE Sales EXCLUSIVE NEW + * IF !NETERR() + * SET INDEX TO Sales, Branch, Salesman + * __dbZAP() + * CLOSE Sales + * ELSE + * ? "Zap operation failed" + * BREAK + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $COMMANDNAME$ + * ZAP + * $CATEGORY$ + * Command + * $ONELINER$ + * Remove all records from the current database file + * $SYNTAX$ + * ZAP + * $ARGUMENTS$ + * + * $RETURNS$ + * + * $DESCRIPTION$ + * This command removes all of the records from the database in the + * current work area.This operation also updates any index file in + * use at the time of this operation.In addition, this command removes + * all items within an associated memo file. + * In a network enviroment,any file that is about to be ZAPped must + * be used exclusively. + * $EXAMPLES$ + * USE Tests NEW index Tests + * ZAP + * USE + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DELETE,PACK,USE + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DELETED() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Tests the record's deletion flag. + * $SYNTAX$ + * DELETED() --> lDeleted + * $ARGUMENTS$ + * $RETURNS$ + * DELETED() return a logical true (.T.) or false (.F.). + * $DESCRIPTION$ + * This function returns a logical true (.T.) is the current record in the + * selected or designated work area ha ben marked for deletion.If not, the + * function will return a logical false (.F.). + * $EXAMPLES$ + * FUNCTION Main() + * USE Test New + * DBGOTO() + * DBDELETE() + * ? "Is Record Deleted",Test->(DELETED()) + * DBRECALL() + * USE + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * DBDELETE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * EOF() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Test for end-of-file condition. + * $SYNTAX$ + * EOF() --> + * $ARGUMENTS$ + * + * $RETURNS$ + * Logical true (.T.) or false (.F.) + * $DESCRIPTION$ + * This function determines if the end-of-file marker has been reached. + * If it has, the function will return a logical true (.T.); otherwise + * a logical false (.F.) will be returnd + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests NEW + * DBGOTOP() + * ? "Is Eof()",EOF() + * DBGOBOTTOM() + * ? "Is Eof()",EOF() + * USE + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * EOF() is fully CA-Clipper compliant. + * $SEEALSO$ + * BOF(),FOUND(),LASTREC() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FCOUNT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Counts the number of fields in an active database. + * $SYNTAX$ + * FCOUNT() --> nFields + * $ARGUMENTS$ + * + * $RETURNS$ + * FCOUNT() Return the number of fields + * $DESCRIPTION$ + * This function returns the number of fields in the current or designated + * work area.If no database is open in this work area, the function will + * return 0. + * $EXAMPLES$ + * FUNCTION Main() + * USE Tests NEW + * ? "This database have ",Tests->(FCOUNT()),"Fields" + * USE + * RETURN Nil + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $SEEALSO$ + * FIELDNAME(),TYPE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDGET() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Obtains the value of a specified field + * $SYNTAX$ + * FIELDGET() --> ValueField + * $ARGUMENTS$ + * Is the numeric field position + * $RETURNS$ + * FIELDGET() Any expression + * $DESCRIPTION$ + * This function returns the value of the field at the th location + * in the selected or designed work area.If the value in does not + * correspond to n avaliable field position in this work area, the function + * will return a NIL data type. + * $EXAMPLES$ + * FUNCTION Main() + * USE Test NEW + * ? Test->(FieldGet(1)) + * USE + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper Compliant. + * $SEEALSO$ + * FIELDPUT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDNAME() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the name of a field at a numeric field location. + * $SYNTAX$ + * FIELDNAME/FIELD() --> cFieldName + * $ARGUMENTS$ + * Field order in the database. + * $RETURNS$ + * FIELDNAME() returns the field name. + * $DESCRIPTION$ + * This function return the name of the field at the th position. + * If the numeric value passed to this function does not correspond to an + * existing field in the designated or selected work area,this function + * will return a NULL byte. + * $EXAMPLES$ + * FUNCTION Main() + * LOCAL x + * USE Tests NEW + * FOR x := 1 to Tests->(FCOUNT()) + * ? "Field Name",FieldName(x) + * NEXT + * USE + * RETURN Nil + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compatible. + * $SEEALSO$ + * DBSTRUCT(),FCOUNT(),LEN(),VALTYPE() + * + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDPOS() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the ordinal position of a field. + * $SYNTAX$ + * FIELDPOS() --> nFieldPos + * $ARGUMENTS$ + * Name of a field. + * $RETURNS$ + * FIELDPOS() returns the ordinal position of the field. + * $DESCRIPTION$ + * This function return the ordinal position of the specified field + * in the current or aliased work areaIf there isn't field under the name + * of or of no database is open in the selected work area, the func- + * tion will return a 0. + * $EXAMPLES$ + * FUNCTION Main() + * USE Test NEW + * ? Test->(FIELDPOS("ID")) + * USE + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant. + * $SEEALSO$ + * FIELDGET(),FIELDPUT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDPUT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set the value of a field variable + * $SYNTAX$ + * FIELDPUT(, ) --> ValueAssigned + * $ARGUMENTS$ + * is the ordinal position of the field in the current + * database file. + * + * is the value to assign to the given field. The data + * type of this expression must match the data type of the designated field + * variable. + * $RETURNS$ + * FIELDPUT() returns the value assigned to the designated field. If + * does not correspond to the position of any field in the current + * database file, FIELDPUT() returns NIL. + * $DESCRIPTION$ + * FIELDPUT() is a database function that assigns to the field + * at ordinal position in the current work area. This function + * allows you to set the value of a field using its position within the + * database file structure rather than its field name. Within generic + * database service functions this allows, among other things, the setting + * of field values without use of the macro operator. + * $EXAMPLES$ + * This example compares FIELDPUT() to functionally equivalent + * code that uses the macro operator to set the value of a field: + * + * // Using macro operator + * FName := FIELD(nField) // Get field name + * FIELD->&FName := FVal // Set field value + * // Using FIELDPUT() + * FIELDPUT(nField, FVal) // Set field value + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FIELDGET() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Lock an open and shared database file + * $SYNTAX$ + * FLOCK() --> lSuccess + * $ARGUMENTS$ + * + * $RETURNS$ + * FLOCK() returns true (.T.) if an attempt to lock a database file in USE + * in the current work area succeeds; otherwise, it returns false (.F.). + * For more information on file locking, refer to the Network Programming + * chapter in the Programming and Utilities guide. + * + * $DESCRIPTION$ + * FLOCK() is a database function used in network environments to lock an + * open and shared database file, preventing other users from updating the + * file until the lock is released. Records in the locked file are + * accessible for read-only operations. + * + * FLOCK() is related to USE...EXCLUSIVE and RLOCK(). USE...EXCLUSIVE + * opens a database file so that no other user can open the same file at + * the same time and is the most restrictive locking mechanism in + * HARBOUR. RLOCK() is the least restrictive and attempts to place an + * update lock on a shared record, precluding other users from updating the + * current record. FLOCK() falls in the middle. + * + * FLOCK() is used for operations that access the entire database file. + * Typically, these are commands that update the file with a scope or a + * condition such as DELETE or REPLACE ALL. The following is a list of + * such commands: + * + * Commands that require an FLOCK() + * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ + * Command Mode + * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ + * APPEND FROM FLOCK() or USE...EXCLUSIVE + * DELETE (multiple records) FLOCK() or USE...EXCLUSIVE + * RECALL (multiple records) FLOCK() or USE...EXCLUSIVE + * REPLACE (multiple records) FLOCK() or USE...EXCLUSIVE + * UPDATE ON FLOCK() or USE...EXCLUSIVE + * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ + * + * For each invocation of FLOCK(), there is one attempt to lock the + * database file, and the result is returned as a logical value. A file + * lock fails if another user currently has a file or record lock for the + * same database file or EXCLUSIVE USE of the database file. If FLOCK() is + * successful, the file lock remains in place until you UNLOCK, CLOSE the + * DATABASE, or RLOCK(). + * + * By default, FLOCK() operates on the currently selected work area as + * shown in the example below. + * + * Notes + * + * SET RELATION: HARBOUR does not automatically lock all work + * areas in the relation chain when you lock the current work area, and + * an UNLOCK has no effect on related work areas. + * $EXAMPLES$ + * This example uses FLOCK() for a batch update of prices in + * Inventory.dbf: + * + * USE Inventory NEW + * IF FLOCK() + * REPLACE ALL Inventory->Price WITH ; + * Inventory->Price * 1.1 + * ELSE + * ? "File not available" + * ENDIF + * + * This example uses an aliased expression to attempt a file lock + * in an unselected work area: + * + * USE Sales NEW + * USE Customer NEW + * // + * IF !Sales->(FLOCK()) + * ? "Sales is in use by another" + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * RLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FOUND() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine if the previous search operation succeeded + * $SYNTAX$ + * FOUND() --> lSuccess + * $ARGUMENTS$ + * + * $RETURNS$ + * FOUND() returns true (.T.) if the last search command was successful; + * otherwise, it returns false (.F.). + * + * $DESCRIPTION$ + * FOUND() is a database function that determines whether a search + * operation (i.e., FIND, LOCATE, CONTINUE, SEEK, or SET RELATION) + * succeeded. When any of these commands are executed, FOUND() is set to + * true (.T.) if there is a match; otherwise, it is set to false (.F.). + * + * If the search command is LOCATE or CONTINUE, a match is the next record + * meeting the scope and condition. If the search command is FIND, SEEK or + * SET RELATION, a match is the first key in the controlling index that + * equals the search argument. If the key value equals the search + * argument, FOUND() is true (.T.); otherwise, it is false (.F.). + * + * The value of FOUND() is retained until another record movement command + * is executed. Unless the command is another search command, FOUND() is + * automatically set to false (.F.). + * + * Each work area has a FOUND() value. This means that if one work area + * has a RELATION set to a child work area, querying FOUND() in the child + * returns true (.T.) if there is a match. + * + * By default, FOUND() operates on the currently selected work area. It + * can be made to operate on an unselected work area by specifying it + * within an aliased expression (see example below). + * + * FOUND() will return false (.F.) if there is no database open in the + * current work area. + * $EXAMPLES$ + * This example illustrates the behavior of FOUND() after a + * record movement command: + * + * USE Sales INDEX Sales + * ? INDEXKEY(0) // Result: SALESMAN + * SEEK "1000" + * ? FOUND() // Result: .F. + * SEEK "100" + * ? FOUND() // Result: .T. + * SKIP + * ? FOUND() // Result: .F. + * + * This example tests a FOUND() value in an unselected work area + * using an aliased expression: + * + * USE Sales INDEX Sales NEW + * USE Customer INDEX Customer NEW + * SET RELATION TO CustNum INTO Sales + * // + * SEEK "Smith" + * ? FOUND(), Sales->(FOUND()) + * + * This code fragment processes all Customer records with the key + * value "Smith" using FOUND() to determine when the key value changes: + * + * USE Customer INDEX Customer NEW + * SEEK "Smith" + * DO WHILE FOUND() + * . + * . + * . + * SKIP + * LOCATE REST WHILE Name == "Smith" + * ENDDO + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * EOF() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HEADER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the current database file header length + * $SYNTAX$ + * HEADER() --> nBytes + * $ARGUMENTS$ + * + * $RETURNS$ + * HEADER() returns the number of bytes in the header of the current + * database file as an integer numeric value. If no database file is in + * use, HEADER() returns a zero (0). + * $DESCRIPTION$ + * HEADER() is a database function that is used with LASTREC(), RECSIZE(), + * and DISKSPACE() to create procedures for backing up files. + * + * By default, HEADER() operates on the currently selected work area. It + * will operate on an unselected work area if you specify it as part of an + * aliased expression (see example below). + * $EXAMPLES$ + * This example determines the header size of the Sales.dbf: + * + * USE Sales NEW + * ? HEADER() // Result: 258 + * + * This example defines a pseudofunction, DbfSize(), that uses + * HEADER() with RECSIZE() and LASTREC() to calculate the size of the + * current database file in bytes: + * + * #define DbfSize() ((RECSIZE() * LASTREC()) + ; + * HEADER() + 1) + * + * Later you can use DbfSize() as you would any function: + * + * USE Sales NEW + * USE Customer NEW + * ? DbfSize() + * ? Sales->(DbfSize()) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DISKSPACE(),LASTREC(),RECSIZE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * INDEXORD() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the order position of the controlling index + * $SYNTAX$ + * INDEXORD() --> nOrder + * $ARGUMENTS$ + * + * $RETURNS$ + * INDEXORD() returns an integer numeric value. The value returned is + * equal to the position of the controlling index in the list of open + * indexes for the current work area. A value of zero indicates that there + * is no controlling index and records are being accessed in natural order. + * If no database file is open, INDEXORD() will also return a zero. + * $DESCRIPTION$ + * INDEXORD() is a database function that determines the position of the + * controlling index in the list of index files opened by the last + * USE...INDEX or SET INDEX TO in the current work area. It is often + * useful to save the last controlling index so it can be restored later. + * + * By default, INDEXORD() operates on the currently selected work area. It + * will operate on an unselected work area if you specify it as part of an + * aliased expression (see example below). + * $EXAMPLES$ + * This example uses INDEXORD() to save the current order. After + * changing to a new order, it uses the saved value to restore the + * original order: + * + * USE Customer INDEX Name, Serial NEW + * nOrder := INDEXORD() // Result: 1 + * SET ORDER TO 2 + * ? INDEXORD() // Result: 2 + * SET ORDER TO nOrder + * ? INDEXORD() // Result: 1 + * + * This example uses an aliased expression to determine the order + * number of the controlling index in an unselected work area: + * + * USE Sales INDEX Salesman, CustNum NEW + * USE Customer INDEX Name, Serial NEW + * ? Sales->(INDEXORD()) // Result: 1 + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * INDEXKEY() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * LASTREC() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine the number of records in the current (.dbf) file + * $SYNTAX$ + * LASTREC() | RECCOUNT()* --> nRecords + * $ARGUMENTS$ + * + * $RETURNS$ + * LASTREC() returns the number of physical records in the current database + * file as an integer numeric value. Filtering commands such as SET FILTER + * or SET DELETED have no effect on the return value. LASTREC() returns + * zero if there is no database file in USE in the current work area. + * $DESCRIPTION$ + * LASTREC() is a database function that determines the number of physical + * records in the current database file. LASTREC() is identical to + * RECCOUNT() which is supplied as a compatibility function. + * + * By default, LASTREC() operates on the currently selected work area. It + * will operate on an unselected work area if you specify it as part of an + * aliased expression (see example below). + * $EXAMPLES$ + * This example illustrates the relationship between LASTREC(), + * RECCOUNT(), and COUNT: + * + * USE Sales NEW + * ? LASTREC(), RECCOUNT() // Result: 84 84 + * // + * SET FILTER TO Salesman = "1001" + * COUNT TO nRecords + * ? nRecords, LASTREC() // Result: 14 84 + * + * This example uses an aliased expression to access the number + * of records in a open database file in an unselected work area: + * + * USE Sales NEW + * USE Customer NEW + * ? LASTREC(), Sales->(LASTREC()) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * EOF() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * LUPDATE() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the last modification date of a (.dbf) file + * $SYNTAX$ + * LUPDATE() --> dModification + * $ARGUMENTS$ + * + * $RETURNS$ + * LUPDATE() returns the date of last change to the open database file in + * the current work area. If there is no database file in USE, LUPDATE() + * returns a blank date. + * + * $DESCRIPTION$ + * LUPDATE() is a database function that determines the date the database + * file in the current work area was last modified and CLOSEd. By default, + * LUPDATE() operates on the currently selected work area. It will operate + * on an unselected work area if you specify it as part of an aliased + * expression as shown in the example below. + * $EXAMPLES$ + * This example demonstrates that the modification date of + * database file is not changed until the database file is closed: + * + * ? DATE() // Result: 09/01/90 + * USE Sales NEW + * ? LUPDATE() // Result: 08/31/90 + * // + * APPEND BLANK + * ? LUPDATE() // Result: 08/31/90 + * CLOSE DATABASES + * // + * USE Sales NEW + * ? LUPDATE() // Result: 09/01/90 + * + * This example uses an aliased expression to access LUPDATE() + * for a database file open in an unselected work area: + * + * USE Sales NEW + * USE Customer NEW + * ? LUPDATE(), Sales->(LUPDATE()) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FIELDNAME(),LASTREC(),RECSIZE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * NETERR() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine if a network command has failed + * $SYNTAX$ + * NETERR([]) --> lError + * $ARGUMENTS$ + * if specified sets the value returned by NETERR() to the + * specified status. can be either true (.T.) or false (.F.). + * Setting NETERR() to a specified value allows the runtime error handler + * to control the way certain file errors are handled. For more + * information, refer to Errorsys.prg. + * + * $RETURNS$ + * NETERR() returns true (.T.) if a USE or APPEND BLANK fails. The initial + * value of NETERR() is false (.F.). If the current process is not running + * under a network operating system, NETERR() always returns false (.F.). + * $DESCRIPTION$ + * 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. + * $EXAMPLES$ + * 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 + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FLOCK(),RLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDBAGEXT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the default Order Bag RDD extension + * $SYNTAX$ + * ORDBAGEXT() --> cBagExt + * $ARGUMENTS$ + * + * $RETURNS$ + * ORDBAGEXT() returns a character expression. + * $DESCRIPTION$ + * ORDBAGEXT() is an Order management function that returns a character + * expression that is the default Order Bag extension of the current or + * aliased work area. cBagExt is determined by the RDD active in the + * current work area. + * + * ORDBAGEXT() supersedes the INDEXEXT() and is not recommended. + * + * $EXAMPLES$ + * USE sample VIA "DBFNTX" + * ? ORDBAGEXT() // Returns .ntx + * + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * INDEXEXT(),ORDBAGNAME() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDBAGNAME() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the Order Bag name of a specific Order + * $SYNTAX$ + * ORDBAGNAME( | ) --> cOrderBagName + * $ARGUMENTS$ + * is an integer that identifies the position in the Order + * List of the target Order whose Order Bag name is sought. + * + * is a character string that represents the name of the + * target Order whose Order Bag name is sought. + * + * $RETURNS$ + * ORDBAGNAME() returns a character string, the Order Bag name of the + * specific Order. + * $DESCRIPTION$ + * ORDBAGNAME() is an Order management function that lets you access the + * name of the Order Bag in which resides. You may identify + * the Order as a character string or with an integer that represents its + * position in the Order List. In case of duplicate names, ORDBAGNAME() + * only recognizes the first matching name. + * $EXAMPLES$ + * The following example uses ORDBAGNAME() with the default + * DBFNTX driver: + * + * USE Customer VIA "DBFNTX" NEW + * SET INDEX TO CuAcct, CuName, CuZip + * ORDBAGNAME( 2 ) // Returns: CuName + * ORDBAGNAME( 1 ) // Returns: CuAcct + * ORDBAGNAME( 3 ) // Returns: CuZip + * + * + * In this example, Customer.cdx contains three orders named + * CuAcct, CuName, CuZip: + * + * USE Customer VIA "DBFCDX" NEW + * SET INDEX TO Customer + * ORDBAGNAME( "CuAcct" ) // Returns: Customer + * ORDBAGNAME( "CuName" ) // Returns: Customer + * ORDBAGNAME( "CuZip" ) // Returns: Customer + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * ORDBAGEXT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDCONDSET() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set the Condition and scope for an order + * $SYNTAX$ + * ORDCONSET([], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * [], + * []) + * $ARGUMENTS$ + * is a string that specifies the FOR condition for the + * order. + * is a code block that defines a FOR condition that + * each record within the scope must meet in order to be processed. If + * a record does not meet the specified condition,it is ignored and the + * next record is processed.Duplicate keys values are not added to the + * index file when a FOR condition is Used. + * $RETURNS$ + * + * $DESCRIPTION$ + * + * $EXAMPLES$ + * + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * ORDCONDSET() is CA-Clipper compliant + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDCREATE() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Create an Order in an Order Bag + * $SYNTAX$ + * ORDCREATE(,[], , + * [], []) --> NIL + * $ARGUMENTS$ + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or extension. If you do not include the extension as part + * of HARBOUR uses the default extension of the current + * RDD. + * + * is the name of the Order to be created. + * + * Note: Although both and are both + * optional, at least one of them must be specified. + * + * is an expression that returns the key value to place in + * the Order for each record in the current work area. can + * represent a character, date, logical, or numeric data type. The maximum + * length of the index key expression is determined by the database driver. + * + * is a code block that evaluates to a key value that is + * placed in the Order for each record in the current work area. If you do + * not supply , it is macro-compiled from . + * + * is an optional logical value that specifies whether a + * unique Order is to be created. If is omitted, the current + * global _SET_UNIQUE setting is used. + * $RETURNS$ + * ORDCREATE() always returns NIL. + * $DESCRIPTION$ + * ORDCREATE() is an Order management function that creates an Order in the + * current work area. It works like DBCREATEINDEX() except that it lets + * you create Orders in RDDs that recognize multiple-Order Bags. + * ORDCREATE() supersedes the DBCREATEINDEX() function because of this + * capability, and is the preferred function. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX and the DBFNDX drivers only support single-Order Bags, + * while other RDDs may support multiple-Order Bags (e.g., the DBFCDX and + * DBFMDX drivers). + * + * In RDDs that support production or structural indexes (e.g., DBFCDX, + * DBFMDX), if you specify a Tag but do not specify an Order Bag, the Tag is + * created and added to the index. If no production or structural index + * exists, it will be created and the Tag will be added to it. When using + * RDDs that support multiple Order Bags, you must explicitly SET ORDER (or + * ORDSETFOCUS()) to the desired controlling Order. If you do not specify + * a controlling Order, the data file will be viewed in natural Order. + * + * If does not exist, it is created in accordance with the + * RDD in the current or specified work area. + * + * If exists and the RDD specifies that Order Bags can only + * contain a single Order, is erased and the new Order is + * added to the Order List in the current or specified work area. + * + * If exists and the RDD specifies that Order Bags can + * contain multiple Tags, is created if it does not already + * exist, otherwise is replaced in and the + * Order is added to the Order List in the current or specified work area. + * $EXAMPLES$ + * The following example demonstrates ORDCREATE() with the DBFNDX + * driver: + * + * USE Customer VIA "DBFNDX" NEW + * ORDCREATE( "CuAcct",, "Customer->Acct" ) + * + * + * The following example demonstrates ORDCREATE() with the + * default DBFNTX driver: + * + * USE Customer VIA "DBFNTX" NEW + * ORDCREATE( "CuAcct", "CuAcct", "Customer->Acct", ; + * {|| Customer->Acct } ) + * + * The following example demonstrates ORDCREATE() with the FoxPro + * driver, DBFCDX: + * + * USE Customer VIA "DBFCDX" NEW + * ORDCREATE( "Customer", "CuAcct", "Customer->Acct" ) + * + * This example creates the Order "CuAcct" and adds it to the + * production index (Order Bag) "Customer". The production index , will + * be created if it doesn't exist: + * + * USE Customer VIA "DBFMDX" NEW + * ORDCREATE( , "CuAcct", "Customer->Acct" ) + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBCREATEINDEX() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDDESTROY() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Remove a specified Order from an Order Bag + * $SYNTAX$ + * ORDDESTROY( [, ]) --> NIL + * $ARGUMENTS$ + * is the name of the Order to be removed from the current + * or specified work area. + * + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * $RETURNS$ + * ORDDESTROY() always returns NIL. + * $DESCRIPTION$ + * ORDDESTROY() is an Order management function that removes a specified + * Order from multiple-Order Bags. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX and the DBFNDX drivers only support single-Order Bags, + * while other RDDs may support multiple-Order Bags (e.g., the DBFCDX and + * DBPX drivers). + * + * Note: RDD suppliers may define specific behaviors for this command. + * + * Warning! ORDDESTROY() is not supported for DBFNDX and DBFNTX. + * $EXAMPLES$ + * This example demonstrates ORDDESTROY() with the FoxPro driver, + * DBFCDX: + * + * USE Customer VIA "DBFCDX" NEW + * SET INDEX TO Customer, CustTemp + * ORDDESTROY( "CuAcct", "Customer" ) + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * ORDCREATE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDFOR() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the FOR expression of an Order + * $SYNTAX$ + * ORDFOR( | + * [, ]) --> cForExp + * + * $ARGUMENTS$ + * is the name of the target Order, whose cForExp is + * sought. + * + * is an integer that identifies the position in the Order + * List of the target Order whose cForExp is sought. + * + * is the name of an Order Bag containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * $RETURNS$ + * ORDFOR() returns a character expression, cForExp, that represents the + * FOR condition of the specified Order. If the Order was not created + * using the FOR clause the return value will be an empty string (""). If + * the database driver does not support the FOR condition, it may either + * return an empty string ("") or raise an "unsupported function" error, + * depending on the driver. + * $DESCRIPTION$ + * ORDFOR() is an Order management function that returns the character + * string, cForExp, that represents the logical FOR condition of the Order, + * or . + * $EXAMPLES$ + * This example retrieves the FOR condition from an Order: + * + * USE Customer NEW + * INDEX ON Customer->Acct ; + * TO Customer ; + * FOR Customer->Acct > "AZZZZZ" + * + * ORDFOR( "Customer" ) // Returns: Customer->Acct > "AZZZZZ" + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * ORDKEY(),ORDCREATE(),ORDNAME(),ORDNUMBER() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDKEY() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the key expression of an Order + * $SYNTAX$ + * ORDKEY( | + * [, ]) --> cExpKey + * $ARGUMENTS$ + * is the name of an Order, a logical ordering of a + * database. + * + * is an integer that identifies the position in the Order + * List of the target Order whose cExpKey is sought. + * + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * $RETURNS$ + * Returns a character string, cExpKey. + * $DESCRIPTION$ + * ORDKEY() is an Order management function that returns a character + * expression, cExpKey, that represents the key expression of the specified + * Order. + * + * You may specify the Order by name or with a number that represents its + * position in the Order List. Using the Order name is the preferred + * method. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX and the DBFNDX drivers only support single-Order Bags, + * while other RDDs may support multiple-Order Bags (e.g., the DBFCDX and + * DBFMDX drivers). + * $EXAMPLES$ + * This example retrieves the index expression from an Order: + * + * USE Customer NEW + * INDEX ON Customer->Acct ; + * TO Customer ; + * FOR Customer->Acct > "AZZZZZ" + * + * ORDKEY( "Customer" ) // Returns: Customer->Acct + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * ORDFOR(),ORDNAME(),ORDNUMBER() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDLISTADD() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Add Orders to the Order List + * $SYNTAX$ + * ORDLISTADD( + * [, ]) --> NIL + * $ARGUMENTS$ + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * + * the name of the specific Order from the Order Bag to be + * added to the Order List of the current work area. If you do not specify + * , all orders in the Order Bag are added to the Order List of + * the current work area. + * $RETURNS$ + * ORDLISTADD() always returns NIL. + * $DESCRIPTION$ + * ORDLISTADD() is an Order management function that adds the contents of + * an Order Bag , or a single Order in an Order Bag, to the Order List. + * This function lets you extend the Order List without issuing a SET INDEX + * command that, first, clears all the active Orders from the Order List. + * + * Any Orders already associated with the work area continue to be active. + * If the newly opened Order Bag contains the only Order associated with + * the work area, it becomes the controlling Order; otherwise, the + * controlling Order remains unchanged. + * + * After the new Orders are opened, the work area is positioned to the + * first logical record in the controlling Order. + * + * ORDLISTADD() is similar to the SET INDEX command or the INDEX clause of + * the USE command, except that it does not clear the Order List prior to + * adding the new order(s). + * + * ORDLISTADD() supersedes the DBSETINDEX() function. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX and the DBFNDX drivers only support single-Order Bags, + * while other RDDs may support multiple-Order Bags (e.g., the DBFCDX and + * DBPX drivers). When using RDDs that support multiple Order Bags, you + * must explicitly SET ORDER (or ORDSETFOCUS()) to the desired controlling + * Order. If you do not specify a controlling Order, the data file will be + * viewed in natural Order. + * $EXAMPLES$ + * In this example Customer.cdx contains three orders, CuAcct, + * CuName, and CuZip. ORDLISTADD() opens Customer.cdx but only uses the + * order named CuAcct: + * + * USE Customer VIA "DBFCDX" NEW + * ORDLISTADD( "Customer", "CuAcct" ) + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBSETINDEX() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDLISTCLEAR() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Clear the current Order List + * $SYNTAX$ + * ORDLISTCLEAR() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * ORDLISTCLEAR() always returns NIL. + * $DESCRIPTION$ + * ORDLISTCLEAR() is an Order management function that removes all Orders + * from the Order List for the current or aliased work area. When you are + * done, the Order List is empty. + * + * This function supersedes the function DBCLEARINDEX(). + * + * $EXAMPLES$ + * USE Sales NEW + * SET INDEX TO SaRegion, SaRep, SaCode + * . + * . < statements > + * . + * ORDLISTCLEAR() // Closes all the current indexes + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBCLEARINDEX() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDLISTREBUILD() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Rebuild all Orders in the Order List of the current work area + * $SYNTAX$ + * ORDLISTREBUILD() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * ORDLISTREBUILD() always returns NIL. + * $DESCRIPTION$ + * ORDLISTREBUILD() is an Order management function that rebuilds all the + * orders in the current or aliased Order List. + * + * To only rebuild a single Order use the function ORDCREATE(). + * + * Unlike ORDCREATE(), this function rebuilds all Orders in the Order List. + * It is equivalent to REINDEX. + * + * $EXAMPLES$ + * USE Customer NEW + * SET INDEX TO CuAcct, CuName, CuZip + * ORDLISTREBUILD() // Causes CuAcct, CuName, CuZip to + * // be rebuilt + * + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * ORDCREATE() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDNAME() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the name of an Order in the Order List + * $SYNTAX$ + * ORDNAME([,]) + * --> cOrderName + * $ARGUMENTS$ + * is an integer that identifies the position in the Order + * List of the target Order whose database name is sought. + * + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * $RETURNS$ + * ORDNAME() returns the name of the specified Order in the current Order + * List or the specified Order Bag if opened in the Current Order list. + * $DESCRIPTION$ + * ORDNAME() is an Order management function that returns the name of the + * specified Order in the current Order List. + * + * If is an Order Bag that has been emptied into the + * current Order List, only those Orders in the Order List that correspond + * to Order Bag are searched. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX and the DBFNDX drivers only support single-Order Bags, + * while other RDDs may support multiple-Order Bags (e.g., the DBFCDX and + * DBPX drivers). + * $EXAMPLES$ + * This example retrieves the name of an Order using its position + * in the order list: + * + * USE Customer NEW + * SET INDEX TO CuAcct, CuName, CuZip + * ORDNAME( 2 ) // Returns: CuName + * + * This example retrieves the name of an Order given its position + * within a specific Order Bag in the Order List: + * + * USE Customer NEW + * SET INDEX TO Temp, Customer + * // Assume Customer contains CuAcct, CuName, CuZip + * ORDNAME( 2, "Customer" ) // Returns: CuName + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * ORDFOR(),ORDKEY(),ORDNUMBER() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDNUMBER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the position of an Order in the current Order List + * $SYNTAX$ + * ORDNUMBER( + * [, ]) --> nOrderNo + * $ARGUMENTS$ + * the name of the specific Order whose position in the + * Order List is sought. + * + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * $RETURNS$ + * Returns nOrderNo, an integer that represents the position of the + * specified Order in the Order List. + * $DESCRIPTION$ + * ORDNUMBER() is an Order management function that lets you determine the + * position in the current Order List of the specified Order. ORDNUMBER() + * searches the Order List in the current work area and returns the + * position of the first Order that matches . If + * is the name of an Order Bag newly emptied into the + * current Order List, only those orders in the Order List that have been + * emptied from are searched. + * + * If is not found ORDNUMBER() raises a recoverable runtime + * error. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX driver only supports single-Order Bags, while other RDDs + * may support multiple-Order Bags (e.g., the DBFCDX and DBPX drivers). + * $EXAMPLES$ + * USE Customer VIA "DBFNTX" NEW + * SET INDEX TO CuAcct, CuName, CuZip + * ORDNUMBER( "CuName" ) // Returns: 2 + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * INDEXORD() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ORDSETFOCUS() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set focus to an Order in an Order List + * $SYNTAX$ + * ORDSETFOCUS([ | ] + * [,]) --> cPrevOrderNameInFocus + * + * $ARGUMENTS$ + * is the name of the selected Order, a logical ordering + * of a database. ORDSETFOCUS() ignores any invalid values of + * . + * + * is a number representing the position in the Order List of + * the selected Order. + * + * is the name of a disk file containing one or more + * Orders. You may specify as the filename with or without + * the pathname or appropriate extension. If you do not include the + * extension as part of HARBOUR uses the default + * extension of the current RDD. + * $RETURNS$ + * ORDSETFOCUS() returns the Order Name of the previous controlling Order. + * $DESCRIPTION$ + * ORDSETFOCUS() is an Order management function that returns the Order + * Name of the previous controlling Order and optionally sets the focus to + * an new Order. + * + * If you do not specify or , the name of the + * currently controlling order is returned and the controlling order + * remains unchanged. + * + * All Orders in an Order List are properly updated no matter what + * is the controlling Order. After a change of controlling + * Orders, the record pointer still points to the same record. + * + * The active RDD determines the Order capacity of an Order Bag. The + * default DBFNTX driver only supports single-Order Bags, while other RDDs + * may support multiple-Order Bags (e.g., the DBFCDX and DBPX drivers). + * + * ORDSETFOCUS() supersedes INDEXORD(). + * $EXAMPLES$ + * + * USE Customer VIA "DBFNTX" NEW + * SET INDEX TO CuAcct, CuName, CuZip + * ? ORDSETFOCUS( "CuName" ) // Displays: "CuAcct" + * ? ORDSETFOCUS() // Displays: "CuName" + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RDDLIST() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return an array of the available Replaceable Database Drivers + * $SYNTAX$ + * RDDLIST([]) --> aRDDList + * $ARGUMENTS$ + * is an integer that represents the type of the RDD you + * wish to list. The constants RDT_FULL and RDT_TRANSFER represent the two + * types of RDDs currently available. + * + * RDDType Summary + * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ + * Constant Value Meaning + * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ + * RDT_FULL 1 Full RDD implementation + * RDT_TRANSFER 2 Import/Export only driver + * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ + * + * RDT_FULL identifies full-featured RDDs that have all the capabilities + * associated with an RDD. + * + * RDT_TRANSFER identifies RDDs of limited capability. They can only + * transfer records between files. You cannot use these limited RDD + * drivers to open a file in a work area. The SDF and DELIM drivers are + * examples of this type of RDD. They are only used in the implementation + * of APPEND FROM and COPY TO with SDF or DELIMITED files. + * $RETURNS$ + * RDDLIST() returns a one-dimensional array of the RDD names registered + * with the application as . + * $DESCRIPTION$ + * RDDLIST() is an RDD function that returns a one-dimensional array that + * lists the available RDDs. + * + * If you do not supply , all available RDDs, regardless of type, + * are returned. + * $EXAMPLES$ + * In this example RDDLIST() returns an array containing the + * character strings, "DBF", "SDF", "DELIM", "DBFCDX", and "DBFNTX": + * + * REQUEST DBFCDX + * + * . + * . < statements > + * . + * + * aRDDs := RDDLIST() + * + * // Returns {"DBF", SDF", "DELIM", "DBFCDX", "DBFNTX" } + * + * In this example, RDDLIST() returns an array containing the + * character strings, "SDF" and "DELIM": + * + * #include "rddsys.ch" + * . + * . < statements > + * . + * aImpExp := RDDLIST( RDT TRANSFER ) + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $INCLUDE$ + * RDDSYS.CH + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RDDNAME() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the name of the currently active RDD + * $SYNTAX$ + * RDDNAME() --> cRDDName + * $ARGUMENTS$ + * + * $RETURNS$ + * Returns a character string, cRDDName, the registered name of the active + * RDD in the current or specified work area. + * $DESCRIPTION$ + * RDDNAME() is an RDD function that returns a character string, cRDDName, + * the name of the active RDD in the current or specified work area. + * + * You can specify a work area other than the currently active work area by + * aliasing the function. + * $EXAMPLES$ + * USE Customer VIA "DBFNTX" NEW + * USE Sales VIA "DBFCDX" NEW + * + * ? RDDNAME() // Returns: DBFCDX + * ? Customer->( RDDNAME() ) // Returns: DBFNTX + * ? Sales->( RDDNAME() ) // Returns: DBFCDX + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * RDDLIST() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RDDSETDEFAULT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set or return the default RDD for the application + * $SYNTAX$ + * RDDSETDEFAULT([]) + * --> cPreviousDefaultRDD + * + * $ARGUMENTS$ + * is a character string, the name of the RDD that is + * to be made the new default RDD in the application. + * $RETURNS$ + * RDDSETDEFAULT() returns a character string, cPreviousDefaultRDD, the + * name of the previous default driver. The default driver is the driver + * that HARBOUR uses if you do not explicitly specify an RDD with the + * VIA clause of the USE command. + * $DESCRIPTION$ + * RDDSETDEFAULT() is an RDD function that sets or returns the name of the + * previous default RDD driver and, optionally, sets the current driver to + * the new RDD driver specified by cNewDefaultRDD. If + * is not specified, the current default driver name is returned and + * continues to be the current default driver. + * + * This function replaces the DBSETDRIVER() function. + * $EXAMPLES$ + * // If the default driver is not DBFNTX, make it the default + * + * IF ( RDDSETDEFAULT() != "DBFNTX" ) + * cOldRdd := RDDSETDEFAULT( "DBFNTX" ) + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBSETDRIVER() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RECCOUNT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine the number of records in the current (.dbf) file + * $SYNTAX$ + * RECCOUNT()* | LASTREC() --> nRecords + * $ARGUMENTS$ + * + * $RETURNS$ + * RECCOUNT() returns the number of physical records in the current + * database file as an integer numeric value. Filtering commands such as + * SET FILTER or SET DELETED have no effect on the return value. + * RECCOUNT() returns zero if there is no database file open in the current + * work area. + * + * $DESCRIPTION$* + * RECCOUNT() is a database function that is a synonym for LASTREC(). By + * default, RECCOUNT() operates on the currently selected work area. It + * will operate on an unselected work area if you specify it as part of an + * aliased expression (see example below). + * $EXAMPLES$ + * This example illustrates the relationship between COUNT and + * RECCOUNT(): + * + * USE Sales NEW + * ? RECCOUNT() // Result: 84 + * // + * SET FILTER TO Salesman = "1001" + * COUNT TO nRecords + * ? nRecords // Result: 14 + * ? RECCOUNT() // Result: 84 + * + * This example uses an aliased expression to access the number + * of records in an unselected work area: + * + * USE Sales NEW + * USE Customer NEW + * ? RECCOUNT(), Sales->(RECCOUNT()) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * EOF(),LASTREC() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RECNO() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the identity at the position of the record pointer + * $SYNTAX$ + * RECNO() --> Identity + * $ARGUMENTS$ + * + * $RETURNS$ + * RECNO() returns the identity found at the position of the record + * pointer. + * $DESCRIPTION$ + * RECNO() is a database function that returns the identity found at the + * current position of the record pointer. Identity is a unique value + * guaranteed by the structure of the data file to reference a specific + * record of data file. The data file need not be a traditional Xbase + * file. Therefore, unlike earlier versions of HARBOUR, the value + * returned need not be a numeric data type. + * + * Under all RDDs, RECNO() returns the value at the position of the record + * pointer; the data type and other characteristics of this value are + * determined by the content of the accessed data and the RDD active in the + * current work area. In an Xbase database this value is the record + * number. + * $EXAMPLES$ + * USE Sales VIA "DBFNTX" + * . + * . < statements > + * . + * DBGOTOP() + * RECNO() // Returns 1 + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBGOTO() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RECSIZE() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine the record length of a database (.dbf) file + * $SYNTAX$ + * RECSIZE() --> nBytes + * $ARGUMENTS$ + * + * $RETURNS$ + * RECSIZE() returns, as a numeric value, the record length, in bytes, of + * the database file open in the current work area. RECSIZE() returns zero + * if no database file is open. + * $DESCRIPTION$ + * RECSIZE() is a database function that determines the length of a record + * by summing the lengths of each field then adding one for the DELETED() + * status flag. When this value is multiplied by LASTREC(), the product is + * the amount of space occupied by the file's records. + * + * RECSIZE() is useful in programs that perform automatic file backup. + * When used in conjunction with DISKSPACE(), the RECSIZE() function can + * assist in ensuring that sufficient free space exists on the disk before a + * file is stored. + * + * By default, RECSIZE() operates on the currently selected work area. It + * will operate on an unselected work area if you specify it as part of an + * aliased expression (see example below). + * $EXAMPLES$ + * The following user-defined function, DbfSize(), uses RECSIZE() + * to calculate the size of the current database file: + * + * FUNCTION DbfSize + * RETURN ((RECSIZE() * LASTREC()) + HEADER() + 1) + * + * This example illustrates the use of RECSIZE() to determine the + * record length of database files open in unselected work areas: + * + * USE Customer NEW + * USE Sales NEW + * // + * ? RECSIZE(), Customer->(RECSIZE()) + * ? DbfSize(), Customer->(DbfSize()) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DISKSPACE(),FIELDNAME(),HEADER(),LASTREC() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Lock the current record in the active work area + * $SYNTAX$ + * RLOCK() --> lSuccess + * $ARGUMENTS$ + * + * $RETURNS$ + * RLOCK() returns true (.T.) if the record lock is obtained; otherwise, it + * returns false (.F.). + * $DESCRIPTION$ + * RLOCK() is a network function that locks the current record, preventing + * other users from updating the record until the lock is released. + * RLOCK() provides a shared lock, allowing other users read-only access to + * the locked record while allowing only the current user to modify it. A + * record lock remains until another record is locked, an UNLOCK is + * executed, the current database file is closed, or an FLOCK() is obtained + * on the current database file. + * + * For each invocation of RLOCK(), there is one attempt to lock the current + * record, and the result is returned as a logical value. An attempt to + * obtain a record lock fails if another user currently has a file or + * record lock, or EXCLUSIVE USE of the database file. An attempt to + * RLOCK() in an empty database returns true (.T.). + * + * By default, RLOCK() operates on the currently selected work area. It + * will operate on an unselected work area if you specify it as part of an + * aliased expression (see example below). This feature is useful since + * RLOCK() does not automatically attempt a record lock for related files. + * + * As a general rule, RLOCK() operates solely on the current record. This + * includes the following commands: + * + * @...GET + * + * DELETE (single record) + * + * RECALL (single record) + * + * REPLACE (single record) + * + * + * Notes + * + * SET RELATION: HARBOUR does not automatically lock all + * records in the relation chain when you lock the current work area + * record. Also, an UNLOCK has no effect on related work areas. + * $EXAMPLES$ + * This example deletes a record in a network environment, using + * RLOCK(): + * + * USE Customer INDEX CustName SHARED NEW + * SEEK "Smith" + * IF FOUND() + * IF RLOCK() + * DELETE + * ? "Smith deleted" + * ELSE + * ? "Record in use by another" + * ENDIF + * ELSE + * ? "Smith not in Customer file" + * ENDIF + * CLOSE + * + * This example specifies RLOCK() as an aliased expression to + * lock a record in an unselected work area: + * + * USE Sales SHARED NEW + * USE Customer SHARED NEW + * // + * IF !Sales->(RLOCK()) + * ? "The current Sales record is in use by another" + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FLOCK() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SELECT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine the work area number of a specified alias + * $SYNTAX$ + * SELECT([]) --> nWorkArea + * $ARGUMENTS$ + * is the target work area alias name. + * $RETURNS$ + * SELECT() returns the work area of the specified alias as a integer + * numeric value. + * $DESCRIPTION$ + * SELECT() is a database function that determines the work area number of + * an alias. The number returned can range from zero to 250. If + * is not specified, the current work area number is returned. If + * is specified and the alias does not exist, SELECT() returns zero. + * + * Note: The SELECT() function and SELECT command specified with an + * extended expression argument look somewhat alike. This shouldn't be a + * problem since the SELECT() function is not very useful on a line by + * itself + * $EXAMPLES$ + * This example uses SELECT() to determine which work area + * USE...NEW selected: + * + * USE Sales NEW + * SELECT 1 + * ? SELECT("Sales") // Result: 4 + * + * To reselect the value returned from the SELECT() function, use + * the SELECT command with the syntax, SELECT (), like this: + * + * USE Sales NEW + * nWorkArea:= SELECT() + * USE Customer NEW + * SELECT (nWorkArea) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * ALIAS(),USED() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * USED() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Determine whether a database file is in USE + * $SYNTAX$ + * USED() --> lDbfOpen + * $ARGUMENTS$ + * + * $RETURNS$ + * USED() returns true (.T.) if there is a database file in USE; otherwise, + * it returns false (.F.). + * $DESCRIPTION$ + * USED() is a database function that determines whether there is a + * database file in USE in a particular work area. By default, USED() + * operates on the currently selected work area. It will operate on an + * unselected work area if you specify it as part of an aliased expression. + * $EXAMPLES$ + * This example determines whether a database file is in USE in + * the current work area: + * + * USE Customer NEW + * ? USED() // Result: .T. + * CLOSE + * ? USED() // Result: .F. + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * ALIAS(),SELECT() + * $INCLUDE$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __RDDSETDEFAULT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set or return the default RDD for the application + * $SYNTAX$ + * __RDDSETDEFAULT([]) + * --> cPreviousDefaultRDD + * + * $ARGUMENTS$ + * is a character string, the name of the RDD that is + * to be made the new default RDD in the application. + * $RETURNS$ + * __RDDSETDEFAULT() returns a character string, cPreviousDefaultRDD, the + * name of the previous default driver. The default driver is the driver + * that HARBOUR uses if you do not explicitly specify an RDD with the + * VIA clause of the USE command. + * $DESCRIPTION$ + * RDDSETDEFAULT() is an RDD function that sets or returns the name of the + * previous default RDD driver and, optionally, sets the current driver to + * the new RDD driver specified by cNewDefaultRDD. If + * is not specified, the current default driver name is returned and + * continues to be the current default driver. + * + * This function replaces the DBSETDRIVER() function. + * $EXAMPLES$ + * // If the default driver is not DBFNTX, make it the default + * + * IF ( __RDDSETDEFAULT() != "DBFNTX" ) + * cOldRdd := __RDDSETDEFAULT( "DBFNTX" ) + * ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBSETDRIVER() + * $INCLUDE$ + * + * $END$ + */ diff --git a/harbour/doc/en/readme.txt b/harbour/doc/en/readme.txt new file mode 100644 index 0000000000..4bdec441b7 --- /dev/null +++ b/harbour/doc/en/readme.txt @@ -0,0 +1,106 @@ +/* + * $Id$ + */ + +/* $DOC$ + * $FUNCNAME$ + * OVERVIEW + * $CATEGORY$ + * Document + * $ONELINER$ + * HARBOUR Read me + * $DESCRIPTION$ + * + * The Harbour project + * + * ************************************************************************ + * * This file contains information on obtaining, installing, and using * + * * Harbour. Please read it *completely* before asking for help. * + * ************************************************************************ + + * Harbour is a free implementation of an xBase language compiler. It is + * designed to be source code compatible with the CA-Clipper(r) compiler. + * That means that if you've got some code that would compile using + * CA-Clipper(r) then it should compile under Harbour. The Harbour-Project + * web page is: + * http://www.Harbour-Project.org/ + * + * + * Status and other information is always available from the web site. + * There is a Harbour mailing list. Harbour is still at a very early + * stage of development, so the mailing list is very much a Developers + * only list, although every body is welcome to join in the discussions. + * + * We would like you to join the Harbour development team. If you are + * interested you may suscribe to our mailing list and start contributing + * to this free public project. + * + * Please feel free to report all questions, ideas, suggestions, fixes, + * code, etc. you may need and want. With the help of all of you, the Harbour + * compiler and runtime libraries will become a reality very soon. + * + * + * What this distribution contains + * =============================== + * + * This distribution is a Source code only distribution. It does not contain + * any executable files. Executable versions of Harbour are available from + * the web site. Executable versions of Harbour DO NOT create runable + * programs. Harbour at the moment produces C output code, which must be + * compiled with the Harbour Virtual Machine and the support libraries + * in order to create a functioning program. + * Please test running Harbour against your Clipper source code and report + * any problems that might occur. + * + * Very important: The preprocessor functionality is not built in yet. So + * you may test only Clipper language without preprocessor commands, etc. + * + * + * Installation + * ------------ + * + * 1. Unzip with Harbour zip file using pkunzip or equivalent. + * E.G. pkunzip -d build72.zip + * This will create Harbour/ directory and all the relevant sub + * directories. + * + * 2. Compile Harbour using your C compiler. Make files for different + * platforms are included in the directory. + * + * + * --- COPYRIGHT --- + * + * What copyright information do we have + * + * + * --- LICENCE --- + * + * Information about the License for usage of Harbour is available in the + * file LICENCE.TXT (when we have a license) + * + * --- DISCLAIMER --- + * + * Participants of The Harbour Project assume no responsibility for errors or + * omissions in these materials. + * + * THESE MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. + * + * Participants of The Harbour Project further do not warrant the accuracy or + * completeness of the code, information, text, output or any other items + * contained within these materials. Participants of The Harbour Project + * shall not be liable for any special, direct, indirect, incidental, or + * consequential damages, including without limitation, lost revenues or + * lost profits, which may result from the use or mis-use of these materials. + * + * The information in The Harbour Project is subject to change without notice + * and does not represent any future commitment by the participants of The + * Harbour Project. + * + * The Harbour Project + * + * $SEEALSO$ + * License + * $END$ + */ diff --git a/harbour/doc/en/set.txt b/harbour/doc/en/set.txt new file mode 100644 index 0000000000..1a26022084 --- /dev/null +++ b/harbour/doc/en/set.txt @@ -0,0 +1,683 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 David G. Holm + * SET() + * __SETCENTURY() + * + * Copyright 1999 A White + * SETKEY() + * HB_SetKeyGet() + * HB_SETKEYSAVE() + * HB_SetKeyCheck() + * SET KEY + * + * Copyright 1999 Chen Kedem + * __SetFunction() documentation + * + * Copyright 1999 Jose Lalin + * SETTYPEAHEAD() + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * __SETCENTURY() + * $CATEGORY$ + * Environment + * $ONELINER$ + * Set the Current Century + * $SYNTAX$ + * __SETCENTURY([ | ] ) --> lPreviousValue + * $ARGUMENTS$ + * optional or (not case sensitive) + * .T. or "ON" to enable the century setting (4-digit years) + * .F. or "OFF" to disable the century setting (2-digit years) + * $RETURNS$ + * Either the current or previous century setting as a logical value + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SET() + * $CATEGORY$ + * Environment + * $ONELINER$ + * Changes or evaluated enviromental settings + * $SYNTAX$ + * Set [, [, ] ] ) --> xPreviousSetting + * $ARGUMENTS$ + * + * _SET_ALTERNATE | + * If enabled, QOUT() and QQOUT() write to the screen and to + * a file, provided that a file has been opened or created + * with _SET_ALTFILE. If disabled, which is the default, + * QOUT() and QQOUT() only write to the screen (and/or to + * the PRINTFILE). Defaults to disabled. + * _SET_ALTFILE + * When set, creates or opens file to write QOUT() and + * QQOUT() output to. If is TRUE and the file + * already exists, the file is opened and positioned at end + * of file. Otherwise, the file is created. If a file is + * already opened, it is closed before the new file is + * opened or created (even if it is the same file). The + * default file extension is ".txt". There is no default + * file name. Call with an empty string to close the file. + * _SET_AUTOPEN | + * TODO: Document + * _SET_AUTORDER | + * TODO: Document + * _SET_AUTOSHARE | + * TODO: Document + * _SET_BELL | + * When enabled, the bell sounds when the last position of + * a GET is reached and/or when a GET validation fails. + * Disabled by default. + * _SET_CANCEL | + * When enabled, which is the default, pressing Alt+C or + * Ctrl+Break terminates the program. When disabled, both + * keystrokes can be read by INKEY(). Note: SET KEY has + * precedence over SET CANCEL. + * _SET_COLOR + * Sets the current color scheme, using color pairs in the + * sequence ",,,, + * ". Each color pair uses the format + * "/". The color codes are space + * or "N" for black, "B" for blue, "G" for green, "BG" for + * Cyan, "R" for red, "RB" for magenta, "GR" for brown, "W" + * for white, "N+" for gray, "B+" for bright blue, "G+" for + * bright green, "BG+" for bright cyan, "R+" for bright red, + * "RB+" for bright magenta, "GR+" for yellow, and "W+" for + * bright white. Special codes are "I" for inverse video, + * "U" for underline on a monochrome monitor (blue on a + * color monitor), and "X" for blank. The default color is + * "W/N,N/W,N,N,N/W". + * _SET_CONFIRM | + * If enabled, an exit key must be pressed to leave a GET. + * If disabled, which is the default, typing past the end + * will leave a GET. + * _SET_CONSOLE | + * If enabled, which is the default, all screen output goes + * to the screen. When disabled, screen output is suppressed + * (Note: This setting does not affect OUTSTD() or OUTERR()). + * _SET_CURSOR + * If enabled, which is the default, the cursor is displayed + * on screen. If disabled, the screen cursor is hidden. + * _SET_DATEFORMAT + * Sets the default date format for display, date input, and + * date conversion. Defaults to American ("mm/dd/yy"). Other + * formats include ANSI ("yy.mm.dd"), British ("dd/mm/yy"), + * French ("dd/mm/yy"), German ("dd.mm.yy"), Italian + * ("dd-mm-yy"), Japan ("yy/mm/dd"), and USA ("mm-dd-yy"). + * SET CENTURY modifies the date format. SET CENTURY ON + * replaces the "y"s with "YYYY". SET CENTURY OFF replaces + * the "y"s with "YY". + * _SET_DEBUG + * When set to .t., pressing Alt+D activates the debugger. + * When set to .f., which is the default, Alt+D can be read + * by INKEY(). (Also affected by AltD(1) and AltD(0)) + * _SET_DECIMALS + * Sets the number of decimal digits to use when displaying + * printing numeric values when SET FIXED is ON. Defaults to + * 2. If SET FIXED is OFF, then SET DECIMALS is only used to + * determine the number of decimal digits to use after using + * EXP(), LOG(), SQRT(), or division. Other math operations + * may adjust the number of decimal digits that the result + * will display. Note: This never affects the precision of + * a number. Only the display format is affected. + * _SET_DEFAULT + * Sets the default directory in which to open, create and + * check for files. Defaults to current directory (blank). + * _SET_DELETED | + * If enabled, deleted records will be processed. If + * disabled, which is the default, deleted records will + * be ignored. + * _SET_DELIMCHARS + * Sets the GET delimiter characters. Defaults to "::". + * _SET_DELIMITERS | + * If enabled, GETs are delimited on screen. If disabled, + * which is the default, no GET delimiters are used. + * _SET_DEVICE + * Selects the output device for DEVOUT(). When set to + * "PRINTER", all output is sent to the printer device or + * file set by _SET_PRINTFILE. When set to anything else, + * all output is sent to the screen. Defaults to "SCREEN". + * _SET_EPOCH + * Determines how to handle the conversion of 2-digit years + * to 4 digit years. When a 2-digit year is greater than or + * equal to the year part of the epoch, the century part of + * the epoch is added to the year. When a 2-digit year is + * less than the year part of the epoch, the century part + * of the epoch is incremented and added to the year. The + * default epoch is 1900, which converts all 2-digit years + * to 19xx. Example: If the epoch is set to 1950, 2-digit + * years in the range from 50 to 99 get converted to 19xx + * and 2-digit years in the range 00 to 49 get converted + * to 20xx. + * _SET_ESCAPE | + * When enabled, which is the default, pressing Esc will + * exit a READ. When disabled, pressing Esc during a READ + * is ignored, unless the Esc key has been assigned to a + * function using SET KEY. + * _SET_EVENTMASK + * Determines which events INKEY() will respond to. + * INKEY_MOVE allows mouse movement events. INKEY_LDOWN + * allows the left mouse button down click. INKEY_LUP + * allows the left mouse button up click. INKEY_RDOWN + * allows the right mouse button down click. INKEY_RUP + * allows the right mouse button up clock. INKEY_KEYBOARD + * allows keyboard keystrokes. INKEY_ALL allows all of the + * preceding events. Events may be combined (e.g., using + * INKEY_LDOWN + INKEY_RUP will allow left mouse button + * down clicks and right mouse button up clicks). The + * default is INKEY_KEYBOARD. + * _SET_EXACT | + * When enabled, all string comparisons other than "==" + * exclude trailing spaces when checking for equality. + * When disabled, which is the default, all string + * comparisons other than "==" treat two strings as + * equal if the right hand string is "" or if the right + * hand string is shorter than or the same length as the + * left hand string and all of the characters in the right + * hand string match the corresponding characters in the + * left hand string. + * _SET_EXCLUSIVE | + * When enabled, which is the default, all database files + * are opened in exclusive mode. When disabled, all + * database files are opened in shared mode. Note: The + * EXCLUSIVE and SHARED clauses of the USE command can be + * used to override this setting. + * _SET_EXIT | + * Toggles the use of Uparrow and Dnarrow as READ exit keys. + * Specifying true (.T.) enables them as exit keys, and + * false (.F.) disables them. Used internally by the + * ReadExit() function. + * _SET_EXTRA | + * QUESTION: What is this for? + * It does not affect _SET_EXTRAFILE in Clipper! + * _SET_EXTRAFILE + * When set, creates or opens file to write QOUT() and + * QQOUT() output to. If is TRUE and the file + * already exists, the file is opened and positioned at end + * of file. Otherwise, the file is created. If a file is + * already opened, it is closed before the new file is + * opened or created (even if it is the same file). The + * default file extension is ".prn". There is no default + * file name. Call with an empty string to close the file. + * _SET_FIXED | + * When enabled, all numeric values will be displayed + * and printed with the number of decimal digits set + * by SET DECIMALS, unless a PICTURE clause is used. + * When disabled, which is the default, the number + * of decimal digits that are displayed depends upon + * a variety of factors. See _SET_DECIMALS for more. + * _SET_INSERT | + * When enabled, characters typed in a GET or MEMOEDIT + * are inserted. When disabled, which is the default, + * characters typed in a GET or MEMOEDIT overwrite. + * Note: This setting can also be toggled between on and + * off by pressing the Insert key during a GET or MEMOEDIT. + * _SET_INTENSITY | + * When enabled, which is the default, GETs and PROMPTs + * are displayed using the enhanced color setting. When + * disabled, GETs and PROMPTs are displayed using the + * standard color setting. + * _SET_MARGIN + * Sets the left margin for all printed output. The default + * value is 0. Note: PCOL() reflects the printer's column + * position including the margin (e.g., SET MARGIN TO 5 + * followed by DEVPOS(5, 10) makes PCOL() return 15). + * _SET_MBLOCKSIZE + * TODO: Document + * _SET_MCENTER | + * If enabled, display PROMPTs centered on the MESSAGE row. + * If disabled, which is the default, display PROMPTS at + * column position 0 on the MESSAGE row. + * _SET_MESSAGE + * If set to 0, which is the default, PROMPTs are always + * suppressed. Otherwise, PROMPTs are displayed on the + * set row. Note: It is not possible to display prompts + * on the top-most screen row, because row 0 is reserved + * for the SCOREBOARD, if enabled. + * _SET_MFILEEXT + * TODO: Document + * _SET_OPTIMIZE | + * TODO: Document + * _SET_PATH + * Specifies a path of directories to search through to + * locate a file that can't be located in the DEFAULT + * directory. Defaults to no path (""). Directories must + * be separated by a semicolon (e.g., "C:\DATA;C:\MORE"). + * _SET_PRINTER | + * If enabled, QOUT() and QQOUT() write to the screen and to + * a file, provided that a file has been opened or created + * with _SET_ALTFILE. If disabled, which is the default, + * QOUT() and QQOUT() only write to the screen (and/or to + * the ALTFILE). + * _SET_PRINTFILE + * When set, creates or opens file to write QOUT(), QQOUT() + * and DEVOUT() output to. If is TRUE and the + * file already exists, the file is opened and positioned + * at end of file. Otherwise, the file is created. If a + * file is already opened, it is closed before the new file + * is opened or created (even if it is the same file). The + * default file extension is ".prn". The default file name + * is "PRN", which maps to the default printer device. Call + * with an empty string to close the file. + * _SET_SCOREBOARD | + * When enabled, which is the default, READ and MEMOEDIT + * display status messages on screen row 0. When disabled, + * READ and MEMOEDIT status messages are suppressed. + * _SET_SCROLLBREAK | + * QUESTION: What is this flag for? + * _SET_SOFTSEEK | + * When enabled, a SEEK that fails will position the record + * pointer to the first key that is higher than the sought + * after key or to LASTREC() + 1 if there is no higher key. + * When disabled, which is the default, a SEEK that fails + * will position the record pointer to LASTREC()+1. + * _SET_STRICTREAD | + * TODO: Document + * _SET_TYPEAHEAD + * Sets the size of the keyboard typeahead buffer. Defaults + * to 50. The minimum is 16 and the maximum is 4096. + * _SET_UNIQUE | + * When enabled, indexes are not allowed to have duplicate + * keys. When disabled, indexes are allowed duplicate keys. + * _SET_VIDEOMODE + * TODO: Document + * _SET_WRAP | + * When enabled, lightbar menus can be navigated from the + * last position to the first and from the first position + * to the last. When disabled, which is the default, there + * is a hard stop at the first and last positions. + * $RETURNS$ + * The current or previous setting + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __SetFunction() + * $CATEGORY$ + * Environment + * $ONELINER$ + * Assign a character string to a function key + * $SYNTAX$ + * __SetFunction( , [] ) --> NIL + * $ARGUMENTS$ + * is a number in the range 1..40 that represent the + * function key to be assigned. + * + * is a character string to set. If is not + * specified, the function key is going to be set to NIL releasing by + * that any previous __SetFunction() or SETKEY() for that function. + * $RETURNS$ + * __SetFunction() always return NIL. + * $DESCRIPTION$ + * __SetFunction() assign a character string with a function key, when + * this function key is pressed, the keyboard is stuffed with this + * character string. __SetFunction() has the effect of clearing any + * SETKEY() previously set to the same function number and vice versa. + * + * nFunctionKey Key to be set + * ------------ ------------- + * 1 .. 12 F1 .. F12 + * 13 .. 20 Shift-F3 .. Shift-F10 + * 21 .. 30 Ctrl-F1 .. Ctrl-F10 + * 31 .. 40 Alt-F1 .. Alt-F10 + * + * SET FUNCTION command is preprocessed into __SetFunction() function + * during compile time. + * $EXAMPLES$ + * // Set F1 with a string + * CLS + * __SetFunction( 1, "I Am Lazy" + CHR( 13 ) ) + * cTest := SPACE( 20 ) + * @ 10, 0 SAY "type something or F1 for lazy mode " GET cTest + * READ + * ? cTest + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * Harbour use 11 and 12 to represent F11 and F12, while CA-Clipper use + * 11 and 12 to represent Shift-F1 and Shift-F2. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * INKEY(),SETKEY(),__Keyboard(),SET KEY + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SET FUNCTION + * $CATEGORY$ + * Command + * $ONELINER$ + * Assign a character string to a function key + * $SYNTAX$ + * SET FUNCTION TO [] + * $ARGUMENTS$ + * is a number in the range 1..40 that represent the + * function key to be assigned. + * + * is a character string to set. If is not + * specified, the function key is going to be set to NIL releasing by + * that any previous Set Function or SETKEY() for that function. + * $RETURNS$ + * $DESCRIPTION$ + * Set Function assign a character string with a function key, when + * this function key is pressed, the keyboard is stuffed with this + * character string. Set Function has the effect of clearing any + * SETKEY() previously set to the same function number and vice versa. + * + * nFunctionKey Key to be set + * ------------ ------------- + * 1 .. 12 F1 .. F12 + * 13 .. 20 Shift-F3 .. Shift-F10 + * 21 .. 30 Ctrl-F1 .. Ctrl-F10 + * 31 .. 40 Alt-F1 .. Alt-F10 + * + * SET FUNCTION command is preprocessed into __SetFunction() function + * during compile time. + * $EXAMPLES$ + * // Set F1 with a string + * CLS + * Set Function 1 to "I Am Lazy" + CHR( 13 ) + * cTest := SPACE( 20 ) + * @ 10, 0 SAY "type something or F1 for lazy mode " GET cTest + * READ + * ? cTest + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * Harbour use 11 and 12 to represent F11 and F12, while CA-Clipper use + * 11 and 12 to represent Shift-F1 and Shift-F2. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * INKEY(),SETKEY(),__Keyboard() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SETKEY() + * $CATEGORY$ + * Events + * $ONELINER$ + * Assign an action block to a key + * $SYNTAX$ + * SETKEY( [, [, ] ] ) + * $ARGUMENTS$ + * is either a numeric key value, or an array of such values + * is an optional code-block to be assigned + * is an optional condition code-block + * $RETURNS$ + * Current assigned action-block + * $DESCRIPTION$ + * The SetKey() function returns the current code-block assigned to a + * key when called with only the key value. If the action block (and + * optionally the condition block) are passed, the current block is + * returned, and the new code block and condition block are stored. + * A group of keys may be assigned the same code block/condition block + * by using an array of key values in place on the first parameter. + * $EXAMPLES$ + * local bOldF10 := setKey( K_F10, {|| Yahoo() } ) + * ... // some other processing + * SetKey( K_F10, bOldF10 ) + * ... // some other processing + * bBlock := SetKey( K_SPACE ) + * if bBlock != NIL ... + * + * // make F10 exit current get, but only if in a get - ignores other + * // wait-states such as menus, achoices, etc... + * SetKey( K_F10, {|| GetActive():State := GE_WRITE },; + * {|| GetActive() != NIL } ) + * $TESTS$ + * None definable + * $STATUS$ + * R + * $COMPLIANCE$ + * SETKEY() is mostly CA-Clipper compliant. The only difference is the + * addition of the condition code-block parameter, allowing set-keys to + * be conditionally turned off or on. This condition-block cannot be + * returned once set - see SetKeyGet() + * $SEEALSO$ + * HB_SETKEYSAVE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_SetKeyGet() + * $CATEGORY$ + * Events + * $ONELINER$ + * Determine a set-key code block & condition-block + * $SYNTAX$ + * HB_SETKEYGET( [, ] ) + * $ARGUMENTS$ + * is an numeric key value + * is an optional return-parameter + * $RETURNS$ + * Current assigned action-block + * $DESCRIPTION$ + * The HB_SetKeyGet() function returns the current code-block assigned to + * a key, and optionally assignes the condition-block to the + * return-parameter + * $EXAMPLES$ + * local bOldF10, bOldF10Cond + * bOldF10 := HB_SetKeyGet( K_F10, @bOldF10Cond ) + * ... // some other processing + * SetKey( K_F10, bOldF10, bOldF10Cond ) + * $TESTS$ + * See test code above + * $STATUS$ + * R + * $COMPLIANCE$ + * HB_SETKEYGET() is a new function and hence not CA-Clipper compliant. + * $SEEALSO$ + * SETKEY(),HB_SETKEYSAVE(),HB_SETKEYCHECK() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_SETKEYSAVE() + * $CATEGORY$ + * Events + * $ONELINER$ + * Returns a copy of internal set-key list, optionally overwriting + * $SYNTAX$ + * HB_SETKEYSAVE( [ ] ) + * $ARGUMENTS$ + * is an optional set-key list from a previous call to + * HB_SetKeySave(), or NIL to clear current set-key list + * $RETURNS$ + * Current set-key list + * $DESCRIPTION$ + * HB_SetKeySave() is designed to act like the set() function which + * returns the current state of an environment setting, and optionally + * assigning a new value. In this case, the "environment setting" is the + * internal set-key list, and the optional new value is either a value + * returned from a previous call to SetKeySave() - to restore that list, + * or the value of NIL to clear the current list. + * $EXAMPLES$ + * local aKeys := HB_SetKeySave( NIL ) // removes all current set=keys + * ... // some other processing + * HB_SetKeySave( aKeys ) + * $TESTS$ + * None definable + * $STATUS$ + * R + * $COMPLIANCE$ + * HB_SETKEYSAVE() is new. + * $SEEALSO$ + * SETKEY() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_SetKeyCheck() + * $CATEGORY$ + * Events + * $ONELINER$ + * Impliments common hot-key activation code + * $SYNTAX$ + * HB_SetKeyCheck( [, ][, ][, ] ) + * $ARGUMENTS$ + * is a numeric key value to be tested + * code-block, if executed + * .. are optional parameters that will be passed to the code-block + * $RETURNS$ + * True if there is a hot-key associated with and it was executed; + * otherwise False + * If there is a hot-key association (before checking any condition): + * - if there is a condition-block, it is passed one parameter - + * - when the hot-key code-block is called, it is passed 1 to 4 parameters, + * depending on the parameters passed to HB_SetKeyCheck(). Any + * parameters so passed are directly passed to the code-block, with an + * additional parameter being + * $DESCRIPTION$ + * HB_SetKeyCheck() is intended as a common interface to the SetKey() + * functionality for such functions as ACHOICE(), DBEDIT(), MEMOEDIT(), + * ACCEPT, INPUT, READ, and WAIT + * $EXAMPLES$ + * // within ReadModal() + * if HB_SetKeyCheck( K_ALT_X, GetActive() ) + * ... // some other processing + * endif + * // within TBrowse handler + * case HB_SetKeyCheck( nInkey, oTBrowse ) + * return + * case nInKey == K_ESC + * ... // some other processing + * $TESTS$ + * None definable + * $STATUS$ + * R + * $COMPLIANCE$ + * HB_SETKEYCHECK() is new. + * $SEEALSO$ + * SETKEY(),HB_SETKEYSAVE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SET KEY + * $CATEGORY$ + * Command + * $ONELINER$ + * Assign an action block to a key + * $SYNTAX$ + * SET KEY to p] [when ] ) + * $ARGUMENTS$ + * is either a numeric key value, or an array of such values + * is an optional code-block to be assigned + * is an optional condition code-block + * $RETURNS$ + * + * $DESCRIPTION$ + * The Set Key Command function is translated to the SetKey() function + * witch returns the current code-block assigned to a + * key when called with only the key value. If the action block (and + * optionally the condition block) are passed, the current block is + * returned, and the new code block and condition block are stored. + * A group of keys may be assigned the same code block/condition block + * by using an array of key values in place on the first parameter. + * $EXAMPLES$ + * local bOldF10 := setKey( K_F10, {|| Yahoo() } ) + * ... // some other processing + * Set Key K_F10 to bOldF10) + * ... // some other processing + * bBlock := SetKey( K_SPACE ) + * if bBlock != NIL ... + * + * // make F10 exit current get, but only if in a get - ignores other + * // wait-states such as menus, achoices, etc... + * SetKey( K_F10, {|| GetActive():State := GE_WRITE },; + * {|| GetActive() != NIL } ) + * $TESTS$ + * None definable + * $STATUS$ + * R + * $COMPLIANCE$ + * SET KEY is mostly CA-Clipper compliant. The only difference is the + * addition of the condition code-block parameter, allowing set-keys to + * be conditionally turned off or on. This condition-block cannot be + * returned once set - see SetKeyGet() + * $SEEALSO$ + * HB_SETKEYSAVE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SETTYPEAHEAD() + * $CATEGORY$ + * Environment + * $ONELINER$ + * Sets the typeahead buffer to given size. + * $SYNTAX$ + * SETTYPEAHEAD( ) --> + * $ARGUMENTS$ + * is a valid typeahead size. + * $RETURNS$ + * The previous state of _SET_TYPEAHEAD + * $DESCRIPTION$ + * This function sets the typeahead buffer to a valid given size as is + * Set( _SET_TYPEAHEAD ) where used. + * $EXAMPLES$ + * // Sets typeahead to 12 + * SetTypeahead( 12 ) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * SETTYPEAHEAD() is fully CA-Clipper compliant. + * $SEEALSO$ + * __ACCEPT(),__INPUT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __XHELP() + * $CATEGORY$ + * Internal + * $ONELINER$ + * Looks if a Help() user defined function exist. + * $SYNTAX$ + * __XHELP() --> + * $ARGUMENTS$ + * None + * $RETURNS$ + * This function returns aleatory values. + * $DESCRIPTION$ + * This is an internal undocumented Clipper function, which will + * try to call the user defined function HELP() if it's defined + * in the current application. This is the default SetKey() handler + * for the F1 key. + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * __XHELP() is fully CA-Clipper compliant. + * $SEEALSO$ + * + * $END$ + */ diff --git a/harbour/doc/en/string.txt b/harbour/doc/en/string.txt new file mode 100644 index 0000000000..e654268ab4 --- /dev/null +++ b/harbour/doc/en/string.txt @@ -0,0 +1,717 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Jose Lalin + * DESCEND() documentation + * + * Copyright 2000 Luiz Rafael Culik + * HB_OEMTOANSI() Documentation + * HB_ANSITOOEM() Documentation + * ISALPHA() Documentation + * ISDIGIT() Documentation + * ISUPPER() Documentation + * ISLOWER() Documentation + * LTRIM() Documentation + * AT() Documentation + * RAT() Documentation + * LEFT() Documentation + * RIGHT() Documentation + * SUBSTR() Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * ISALPHA() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Checks if leftmost character in a string is an alphabetic character + * $SYNTAX$ + * ISALPHA() --> lAlpha + * $ARGUMENTS$ + * Any character string + * $RETURNS$ + * lAlpha Logical true (.T.) or false (.F.). + * $DESCRIPTION$ + * This function return a logical true (.T.) if the first character + * in is an alphabetic character.If not, the function will + * return a logical false (.F.). + * $EXAMPLES$ + * QOUT( "isalpha( 'hello' ) = ", isalpha( 'hello' ) ) + * QOUT( "isalpha( '12345' ) = ", isalpha( '12345' ) ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * ISDIGIT(),ISLOWER(),ISUPPER(),LOWER(),UPPER() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISDIGIT() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Checks if leftmost character is a digit character + * $SYNTAX$ + * ISDIGIT() --> lDigit + * $ARGUMENTS$ + * Any character string + * $RETURNS$ + * lDigit Logical true (.T.) or false (.F.). + * $DESCRIPTION$ + * This function takes the caracter string and checks to + * see if the leftmost character is a digit,from 1 to 9.If so, the + * function will return a logical true (.T.);otherwise, it will + * return a logical false (.F.). + * $EXAMPLES$ + * QOUT( "isdigit( '12345' ) = ", isdigit( '12345' ) ) + * QOUT( "isdigit( 'abcde' ) = ", isdigit( 'abcde' ) ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * ISALPHA(),ISLOWER(),ISUPPER(),LOWER(),UPPER() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISUPPER() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Checks if leftmost character is an uppercased letter. + * $SYNTAX$ + * ISUPPER() --> lUpper + * $ARGUMENTS$ + * Any character string + * $RETURNS$ + * lUpper Logical true (.T.) or false (.F.). + * $DESCRIPTION$ + * This function takes the caracter string and checks to + * see if the leftmost character is a uppercased letter.If so, the + * function will return a logical true (.T.);otherwise, it will + * return a logical false (.F.). + * $EXAMPLES$ + * QOUT( "isupper( 'Abcde' ) = ", isupper( 'Abcde' ) ) + * QOUT( "isupper( 'abcde' ) = ", isupper( 'abcde' ) ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * ISALPHA(),ISLOWER(),ISDIGIT(),LOWER(),UPPER() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ISLOWER() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Checks if leftmost character is an lowercased letter. + * $SYNTAX$ + * ISLOWER() --> lLower + * $ARGUMENTS$ + * Any character string + * $RETURNS$ + * lLower Logical true (.T.) or false (.F.). + * $DESCRIPTION$ + * This function takes the caracter string and checks to + * see if the leftmost character is a lowercased letter.If so, the + * function will return a logical true (.T.);otherwise, it will + * return a logical false (.F.). + * $EXAMPLES$ + * QOUT( "islower( 'Abcde' ) = ", islower( 'Abcde' ) ) + * QOUT( "islower( 'abcde' ) = ", islower( 'abcde' ) ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compliant + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * ISALPHA(),ISDIGIT(),ISUPPER(),LOWER(),UPPER() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * LTRIM() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Removes leading spaces from a string + * $SYNTAX$ + * LTRIM() --> + * $ARGUMENTS$ + * Character expression with leading spaces + * $RETURNS$ + * The same character expression with leading spaces removed + * $DESCRIPTION$ + * This function trims the leading space blanl + * $EXAMPLES$ + * ? QOUT( LTRIM("HELLO ")) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This functions is CA-CLIPPER compatible + * $PLATFORMS$ + * + * $FILES$ + * + * $SEEALSO$ + * TRIM(),RTRIM(),ALLTRIM() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * AT() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Locates the position of a substring in a main string. + * $SYNTAX$ + * AT(,) --> nPos + * $ARGUMENTS$ + * Substring to search for + * Main string + * $RETURNS$ + * AT() return the starting position of the first occurrence of the + * substring in the main string + * $DESCRIPTION$ + * This function searches the string for the characters in + * the first string . If the substring is not contained within + * the second expression,the function will return 0. + * $EXAMPLES$ + * QOUT( "at( 'cde', 'abcdefgfedcba' ) = '" +; + * at( 'cde', 'abcsefgfedcba' ) + "'" ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is CA-Clipper compatible. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * RAT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RAT() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Searches for a substring from the right side of a string. + * $SYNTAX$ + * RAT(,) --> nPos + * $ARGUMENTS$ + * Substring to search for + * Main string + * $RETURNS$ + * RAT() return the location of beginnig position. + * $DESCRIPTION$ + * This function searches througt for the first existence + * of .The search operation is performed from the right side + * of to the left. If the function is unable to find any + * occurence of in ,the value of the function will be 0. + * $EXAMPLES$ + * QOUT( "rat( 'cde', 'abcdefgfedcba' ) = '" +; + * rat( 'cde', 'abcsefgfedcba' ) + "'" ) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * Will not work with a search string > 64 KB on some platforms + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * AT(),SUBSTR(),RIGHT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * LEFT() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Extract the leftmost substring of a character expression + * $SYNTAX$ + * LEFT(,) --> + * $ARGUMENTS$ + * Main character to be parsed + * Number of bytes to return beggining at the leftmost position + * $RETURNS$ + * Substring of evaluation + * $DESCRIPTION$ + * This functions returns the leftmost characters of . + * It is equivalent to the following programing expression: + * SUBSTR(,1, + * $EXAMPLES$ + * ? QOUT(LEFT('HELLO HARBOUR',5)) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This functions is CA CLIPPER compatible + * $PLATFORMS$ + * + * $FILES$ + * + * $SEEALSO$ + * SUBSTR(),RIGHT(),AT(),RAT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RIGHT() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Extract the rightmost substring of a character expression + * $SYNTAX$ + * SUBSTR(,) --> + * $ARGUMENTS$ + * Character expression to be parsed + * Number of bytes to return beggining at the rightmost position + * $RETURNS$ + * Substring of evaluation + * $DESCRIPTION$ + * This functions returns the rightmost characters of . + * + * $EXAMPLES$ + * ? QOUT(RIGHT('HELLO HARBOUR',5)) + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This functions is CA CLIPPER compatible + * $PLATFORMS$ + * + * $FILES$ + * + * $SEEALSO$ + * SUBSTR(),LEFT(),AT(),RAT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SUBSTR() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Returns a substring from a main string + * $SYNTAX$ + * SUBSTR(,[,)] --> + * $ARGUMENTS$ + * Character expression to be parsed + * Start position + * Number of characters to return + * $RETURNS$ + * Substring of evaluation + * $DESCRIPTION$ + * This functions returns a character string formed from , + * starting at the position of and continuing on for a + * lenght of characters. If is not specified, the value + * will be all remaining characters from the position of . + * The value of may be negative. If it is, the direction of + * operation is reversed from a default of left-to-right to right-to-left + * for the number of characters specified in . + * $EXAMPLES$ + * FUNCTION MAIN() + * LOCAL X:=REPLICATE('ABCD',70000) + * + * ? QOUT(SUBSTR(X,65519,200) + * + * RETURN NIL + * $TESTS$ + * ? QOUT(SUBSTR('HELLO HARBOUR',5) + * $STATUS$ + * R + * $COMPLIANCE$ + * This functions is CA CLIPPER compatible with the execption that + * CA CLIPPER will generate an error if the passed string is >65519 bytes + * and Harbour depends of plataform. + * $PLATFORMS$ + * + * $FILES$ + * + * $SEEALSO$ + * LEFT(),AT(),RIGHT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * STR() + * $CATEGORY$ + * Run-time Library, Strings + * $ONELINER$ + * Convert a numeric expression to a character string. + * $SYNTAX$ + * STR(, [], []) --> cNumber + * $ARGUMENTS$ + * is the numeric expression to be converted to a character + * string. + * is the length of the character string to return, including + * decimal digits, decimal point, and sign. + * is the number of decimal places to return. + * $RETURNS$ + * STR() returns formatted as a character string. If the + * optional length and decimal arguments are not specified, STR() + * returns the character string according to the following rules: + * + * Results of STR() with No Optional Arguments + * --------------------------------------------------------------- + * Expression Return Value Length + * --------------------------------------------------------------- + * Field Variable Field length plus decimals + * Expressions/constants Minimum of 10 digits plus decimals + * VAL() Minimum of 3 digits + * MONTH()/DAY() 3 digits + * YEAR() 5 digits + * RECNO() 7 digits + * --------------------------------------------------------------- + * $DESCRIPTION$ + * STR() is a numeric conversion function that converts numeric values + * to character strings. It is commonly used to concatenate numeric values + * to character strings. STR() has applications displaying numbers, + * creating codes such as part numbers from numeric values, and creating + * index keys that combine numeric and character data. + * + * STR() is like TRANSFORM(), which formats numeric values as character + * strings using a mask instead of length and decimal specifications. + * + * The inverse of STR() is VAL(), which converts character numbers to + * numerics. + * + * * If is less than the number of whole number digits in + * , STR() returns asterisks instead of the number. + * + * * If is less than the number of decimal digits + * required for the decimal portion of the returned string, Harbour + * rounds the number to the available number of decimal places. + * + * * If is specified but is omitted (no + * decimal places), the return value is rounded to an integer. + * $EXAMPLES$ + * ? STR( 10, 6, 2 ) // " 10.00" + * ? STR( -10, 8, 2 ) // " -10.00" + * $TESTS$ + * see the regression test suit for comprehensive tests. + * $STATUS$ + * R + * $COMPLIANCE$ + * CA-Clipper compatible. + * $SEEALSO$ + * STRZERO(),VAL() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * STRZERO() + * $CATEGORY$ + * Run-time Library, Strings + * $ONELINER$ + * Convert a numeric expression to a character string, zero padded. + * $SYNTAX$ + * STRZERO(, [], []) --> cNumber + * $ARGUMENTS$ + * is the numeric expression to be converted to a character + * string. + * is the length of the character string to return, including + * decimal digits, decimal point, and sign. + * is the number of decimal places to return. + * $RETURNS$ + * STRZERO() returns formatted as a character string. If the + * optional length and decimal arguments are not specified, STRZERO() + * returns the character string according to the following rules: + * + * Results of STRZERO() with No Optional Arguments + * --------------------------------------------------------------- + * Expression Return Value Length + * --------------------------------------------------------------- + * Field Variable Field length plus decimals + * Expressions/constants Minimum of 10 digits plus decimals + * VAL() Minimum of 3 digits + * MONTH()/DAY() 3 digits + * YEAR() 5 digits + * RECNO() 7 digits + * --------------------------------------------------------------- + * $DESCRIPTION$ + * STRZERO() is a numeric conversion function that converts numeric values + * to character strings. It is commonly used to concatenate numeric values + * to character strings. STRZERO() has applications displaying numbers, + * creating codes such as part numbers from numeric values, and creating + * index keys that combine numeric and character data. + * + * STRZERO() is like TRANSFORM(), which formats numeric values as character + * strings using a mask instead of length and decimal specifications. + * + * The inverse of STRZERO() is VAL(), which converts character numbers to + * numerics. + * + * * If is less than the number of whole number digits in + * , STR() returns asterisks instead of the number. + * + * * If is less than the number of decimal digits + * required for the decimal portion of the returned string, Harbour + * rounds the number to the available number of decimal places. + * + * * If is specified but is omitted (no + * decimal places), the return value is rounded to an integer. + * $EXAMPLES$ + * ? STRZERO( 10, 6, 2 ) // "010.00" + * ? STRZERO( -10, 8, 2 ) // "-0010.00" + * $TESTS$ + * see the regression test suit for comprehensive tests. + * $STATUS$ + * R + * $COMPLIANCE$ + * CA-Clipper compatible (it was not mentioned in the docs though). + * $SEEALSO$ + * STR(),VAL() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_VALTOSTR() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Converts any scalar type to a string. + * $SYNTAX$ + * HB_VALTOSTR( ) + * $ARGUMENTS$ + * is any scalar argument. + * $RETURNS$ + * A string representation of using default conversions. + * $DESCRIPTION$ + * HB_VALTOSTR can be used to convert any scalar value to a string. + * $EXAMPLES$ + * ? HB_VALTOSTR( 4 ) + * ? HB_VALTOSTR( "String" ) + * $TESTS$ + * ? HB_VALTOSTR( 4 ) == " 4" + * ? HB_VALTOSTR( 4.0 / 2 ) == " 2.00" + * ? HB_VALTOSTR( "String" ) == "String" + * ? HB_VALTOSTR( CTOD( "01/01/2001" ) ) == "01/01/01" + * ? HB_VALTOSTR( NIL ) == "NIL" + * ? HB_VALTOSTR( .F. ) == ".F." + * ? HB_VALTOSTR( .T. ) == ".T." + * $STATUS$ + * R + * $COMPLIANCE$ + * HB_VALTOSTR() is a Harbour enhancement. + * $SEEALSO$ + * STR(),VAL() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * LEN() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Returns size of a string or size of an array. + * $SYNTAX$ + * LEN( | ) --> + * $ARGUMENTS$ + * is a character string or the array to check. + * $RETURNS$ + * The length of the string or the number of elements that contains + * an array. + * $DESCRIPTION$ + * This function returns the string length or the size of an array. If + * it is used with a multidimensional array it returns the size of the + * first dimension. + * $EXAMPLES$ + * ? Len( "Harbour" ) --> 7 + * ? Len( { "One", "Two" } ) --> 2 + * $TESTS$ + * function Test() + * LOCAL cName := "" + * ACCEPT "Enter your name: " TO cName + * ? Len( cName ) + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * LEN() is fully CA-Clipper compliant. + * $SEEALSO$ + * EMPTY(),RTRIM(),LTRIM(),AADD(),ASIZE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * EMPTY() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Checks if the passed argument is empty. + * $SYNTAX$ + * EMPTY( ) --> + * $ARGUMENTS$ + * is any valid expression. + * $RETURNS$ + * A logical value. It is true (.T.) if the passed argument is empty + * otherwise it is false (.F.). + * $DESCRIPTION$ + * This function checks if an expression has empty value and returns a + * logical indicating whether it the expression is empty or not. + * $EXAMPLES$ + * ? Empty( "I'm not empty" ) + * $TESTS$ + * function Test() + * ? Empty( 1 ) --> .f. + * ? Empty( Date() ) --> .f. + * ? Empty( .f. ) --> .t. + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * EMPTY() is fully CA-Clipper compliant. + * $SEEALSO$ + * LEN() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DESCEND() + * $CATEGORY$ + * Conversion + * $ONELINER$ + * Inverts an expression of string, logical, date or numeric type. + * $SYNTAX$ + * DESCEND( ) --> + * $ARGUMENTS$ + * is any valid expression. + * $RETURNS$ + * Inverted value of the same type as passed. + * $DESCRIPTION$ + * This function converts an expression in his inverted form. It is + * useful to build descending indexes. + * $EXAMPLES$ + * // Seek for Smith in a descending index + * SEEK DESCEND( "SMITH" ) + * $TESTS$ + * DATA->( DBSEEK( DESCEND( "SMITH" ) ) ) + * will seek "SMITH" into a descending index. + * $STATUS$ + * R + * $COMPLIANCE$ + * DESCEND() is fully CA-Clipper compliant. + * $SEEALSO$ + * INDEX,SEEK + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_ANSITOOEM() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Convert a windows Character to a Dos based character + * $SYNTAX$ + * HB_ANSITOOEM() -> cDosString + * $ARGUMENTS$ + * Windows ansi string to convert to DOS oem String + * $RETURNS$ + * cDosString Dos based string + * $DESCRIPTION$ + * This function converts each character in to the corresponding + * character in the MS-DOS (OEM) character set.The character expression + * should contain characters from the ANSI character set. + * If a character in doesn't have a MS-DOS equivalent, the + * character is converted to a similar MS-DOS character. + * $EXAMPLES$ + * ? HB_OEMTOANSI("Harbour") + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is a Harbour extension + * $PLATFORMS$ + * This functions work only on Windows Plataform + * $FILES$ + * + * $SEEALSO$ + * HB_OEMTOANSI() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_OEMTOANSI() + * $CATEGORY$ + * Strings + * $ONELINER$ + * Convert a DOS(OEM) Character to a WINDOWS (ANSI) based character + * $SYNTAX$ + * HB_OEMTOANSI() -> cDosString + * $ARGUMENTS$ + * DOS (OEM) string to convert to WINDOWS (ANSI) String + * $RETURNS$ + * cDosString WINDOWS based string + * $DESCRIPTION$ + * This function converts each character in to the corresponding + * character in the Windows (ANSI) character set.The character expression + * should contain characters from the OEM character set. + * If a character in doesn't have a ANSI equivalent, the + * character is remais the same. + * $EXAMPLES$ + * ? HB_OEMTOANSI("Harbour") + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This function is a Harbour extension + * $PLATFORMS$ + * This functions work only on Windows Plataform + * $FILES$ + * + * $SEEALSO$ + * HB_ANSITOOEM() + * $END$ + */ diff --git a/harbour/doc/en/tclass.txt b/harbour/doc/en/tclass.txt new file mode 100644 index 0000000000..86ecc596fc --- /dev/null +++ b/harbour/doc/en/tclass.txt @@ -0,0 +1,63 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 2000 Brian Hays + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * TClass() + * $CATEGORY$ + * Classes + * $ONELINER$ + * TClass() is used in the creation of all classes + * $SYNTAX$ + * oClass := TClass():New("TMyClass") + * -or- + * TClass() is usually accessed by defining a class with the commands + * defined in hbclass.h: + * CLASS TGetList // Calls TClass() to create the TGetList class + * ... + * ENDCLASS + * $ARGUMENTS$ + * + * $RETURNS$ + * An instance of the TClass Class. This special object's :New() + * method can then create the classes you define. + * $DESCRIPTION$ + * TClass is a class that ... + * The class methods are as follows: + * New() Create a new instance of the class + * $EXAMPLES$ + * FUNCTION TestObject() + * local oObject + * + * oObject := TClass():New("TMyClass") + * oObject:End() + * + * RETURN Nil + * $STATUS$ + * R + * $COMPLIANCE$ + * Object Oriented syntax in Harbour is compatible with CA-CLIPPER. + * But Clipper only allowed creation of objects from a few standard + * classes, and did not let the programmer create new classes. + * In Harbour, you can create your own classes--complete with + * Methods, Instance Variables, Class Variables and Inheritance. + * Entire applications can be designed and coded in Object Oriented + * style. + * $PLATFORMS$ + * All + * $SEEALSO$ + * __objHasData(),Object Oriented Programming,CLASS + * $END$ + */ diff --git a/harbour/doc/en/terminal.txt b/harbour/doc/en/terminal.txt new file mode 100644 index 0000000000..217a47c85c --- /dev/null +++ b/harbour/doc/en/terminal.txt @@ -0,0 +1,556 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Victor Szakats + * HB_HB_COLORINDEX() + * + * Copyright 1999 Jose Lalin + * __WAIT() documentation + * __INPUT() documentation + * + * Copyright 1999 Chen Kedem + * ALERT() documentation + * __NONOALERT() documentation + * __XSaveScreen() documentation + * __XRestScreen() documentation + * __TextSave() documentation + * __TextRestore() documentation + * + * Copyright 1999 David G. Holm + * DEVOUTPICT() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * __XSaveScreen() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Save whole screen image and coordinate to an internal buffer + * $SYNTAX$ + * __XSaveScreen() --> NIL + * $ARGUMENTS$ + * none. + * $RETURNS$ + * __XSaveScreen() always return NIL. + * $DESCRIPTION$ + * __XSaveScreen() save the image of the whole screen into an internal + * buffer, it also save current cursor position. The information could + * later be restored by __XRestScreen(). Each call to __XSaveScreen() + * overwrite the internal buffer. + * + * SAVE SCREEN command is preprocessed into __XSaveScreen() function + * during compile time. Note that SAVE SCREEN TO is preprocessed into + * SAVESCREEN() function. + * + * __XSaveScreen() is a compatibility function, it is superseded by + * SAVESCREEN() which allow you to save part or all the screen into a + * variable. + * $EXAMPLES$ + * // save the screen, display list of files than restore the screen + * SAVE SCREEN + * DIR *.* + * WAIT + * RESTORE SCREEN + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __XSaveScreen() works exactly like CA-Clipper's __XSaveScreen() + * $PLATFORMS$ + * __XSaveScreen() is part of the GT API, and supported only by some + * platforms. + * $FILES$ + * $SEEALSO$ + * RESTORE SCREEN,RESTSCREEN(),SAVESCREEN() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * SAVE SCREEN + * $CATEGORY$ + * Command + * $ONELINER$ + * Save whole screen image and coordinate to an internal buffer + * $SYNTAX$ + * SAVE SCREEN + * $ARGUMENTS$ + * none. + * $RETURNS$ + * SAVE SCREEN always return NIL. + * $DESCRIPTION$ + * SAVE SCREEN save the image of the whole screen into an internal + * buffer, it also save current cursor position. The information could + * later be restored by REST SCREEN. Each call to SAVE SCREEN + * overwrite the internal buffer. + * + * SAVE SCREEN command is preprocessed into __XSaveScreen() function + * during compile time. Note that SAVE SCREEN TO is preprocessed into + * SAVESCREEN() function. + * + * $EXAMPLES$ + * // save the screen, display list of files than restore the screen + * SAVE SCREEN + * DIR *.* + * WAIT + * RESTORE SCREEN + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __XSaveScreen() works exactly like CA-Clipper's __XSaveScreen() + * $PLATFORMS$ + * __XSaveScreen() is part of the GT API, and supported only by some + * platforms. + * $FILES$ + * $SEEALSO$ + * RESTORE SCREEN,__XRESTSCREEN(),__XSAVESCREEN() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __XRestScreen() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Restore screen image and coordinate from an internal buffer + * $SYNTAX$ + * __XRestScreen() --> NIL + * $ARGUMENTS$ + * none. + * $RETURNS$ + * __XRestScreen() always return NIL. + * $DESCRIPTION$ + * __XRestScreen() restore saved image of the whole screen from an + * internal buffer that was saved by __XSaveScreen(), it also restore + * cursor position. After a call to __XRestScreen() the internal buffer + * is cleared. + * + * RESTORE SCREEN command is preprocessed into __XRestScreen() function + * during compile time. Note that RESTORE SCREEN FROM is preprocessed + * into RESTSCREEN() function. + * + * __XRestScreen() is a compatibility function, it is superseded by + * RESTSCREEN() which allow you to restore the screen from a variable. + * $EXAMPLES$ + * // save the screen, display list of files than restore the screen + * SAVE SCREEN + * DIR *.* + * WAIT + * RESTORE SCREEN + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __XRestScreen() works exactly like CA-Clipper's __XRestScreen() + * $PLATFORMS$ + * __XRestScreen() is part of the GT API, and supported only by some + * platforms. + * $FILES$ + * $SEEALSO$ + * __XRESTSCREEN(),SAVE SCREEN,__XSAVESCREEN() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * RESTORE SCREEN + * $CATEGORY$ + * Command + * $ONELINER$ + * Restore screen image and coordinate from an internal buffer + * $SYNTAX$ + * RESTORE SCREEN + * $ARGUMENTS$ + * none. + * $RETURNS$ + * REST SCREEN always return NIL. + * $DESCRIPTION$ + * Rest Screen restore saved image of the whole screen from an + * internal buffer that was saved by Save Screen, it also restore + * cursor position. After a call to Rest Screen the internal buffer + * is cleared. + * + * RESTORE SCREEN command is preprocessed into __XRestScreen() function + * during compile time. Note that RESTORE SCREEN FROM is preprocessed + * into RESTSCREEN() function. + * + * $EXAMPLES$ + * // save the screen, display list of files than restore the screen + * SAVE SCREEN + * DIR *.* + * WAIT + * RESTORE SCREEN + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * Rest Screen() works exactly like CA-Clipper's Rest Screen + * $PLATFORMS$ + * Rest Screen is part of the GT API, and supported only by some + * platforms. + * $FILES$ + * $SEEALSO$ + * __XRESTSCREEN(),SAVE SCREEN,__XSAVESCREEN() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * ALERT() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Display a dialog box with a message + * $SYNTAX$ + * ALERT( , [], [], + * [] ) --> nChoice or NIL + * $ARGUMENTS$ + * Message to display in the dialog box. can be + * of any Harbour type. + * If is an array of Character strings, each element would + * be displayed in a new line. If is a Character + * string, you could split the message to several lines by placing + * a semicolon (;) in the desired places. + * + * Array with available response. Each element should be + * Character string. If omitted, default is { "Ok" }. + * + * Color string to paint the dialog box with. + * If omitted, default color is "W+/R". + * + * Number of seconds to wait to user response before abort. + * Default value is 0, that wait forever. + * $RETURNS$ + * ALERT() return Numeric value representing option number chosen. + * If ESC was pressed, return value is zero. The return value is NIL + * if ALERT() is called with no parameters, or if type is + * not Character and HARBOUR_STRICT_CLIPPER_COMPATIBILITY option was + * used. If seconds had passed without user response, the + * return value is 1. + * $DESCRIPTION$ + * ALERT() display simple dialog box on screen and let the user select + * one option. The user can move the highlight bar using arrow keys or + * TAB key. To select an option the user can press ENTER, SPACE or the + * first letter of the option. + * + * If the program is executed with the //NOALERT command line switch, + * nothing is displayed and it simply returns NIL. This switch could + * be overridden with __NONOALERT(). + * + * If the GT system is linked in, ALERT() display the message using + * the full screen I/O system, if not, the information is printed to + * the standard output using OUTSTD(). + * $EXAMPLES$ + * LOCAL cMessage, aOptions, nChoice + * + * // harmless message + * cMessage := "Major Database Corruption Detected!;" + ; + * "(deadline in few hours);;" + ; + * "where DO you want to go today?" + * + * // define response option + * aOptions := { "Ok", "www.jobs.com", "Oops" } + * + * // show message and let end user select panic level + * nChoice := ALERT( cMessage, aOptions ) + * DO CASE + * CASE nChoice == 0 + * // do nothing, blame it on some one else + * CASE nChoice == 1 + * ? "Please call home and tell them you're gonn'a be late" + * CASE nChoice == 2 + * // make sure your resume is up to date + * CASE nChoice == 3 + * ? "Oops mode is not working in this version" + * ENDCASE + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * This function is sensitive to HARBOUR_STRICT_CLIPPER_COMPATIBILITY + * settings. + * + * ON: accept Character values only and return NIL if other + * types are passed, + * OFF: could be any type, and internally converted to + * Character string. If type is Array, multi-line message is + * displayed. + * + * ON: Only the first four valid are taken. + * OFF: could contain as many as needed options. + * + * is a Harbour extension, or at least un-documented + * in Clipper 5.2 NG. + * + * is a Harbour extension. + * $SEEALSO$ + * @...PROMPT,MENU TO, STDOUT(),__NONOALERT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __NONOALERT() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Override //NOALERT command line switch + * $SYNTAX$ + * __NONOALERT() --> NIL + * $ARGUMENTS$ + * This function takes no arguments. + * $RETURNS$ + * __NONOALERT() always return NIL. + * $DESCRIPTION$ + * The //NOALERT command line switch cause Clipper to ignore calls to + * the ALERT() function, this function override this behavior + * and always display ALERT() dialog box. + * $EXAMPLES$ + * // make sure alert are been displayed + * __NONOALERT() + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __NONOALERT() is an undocumented CA-Clipper function + * $SEEALSO$ + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * HB_OSNEWLINE() + * $CATEGORY$ + * Operating System Specific + * $ONELINER$ + * Returns the newline character(s) to use with the current OS + * $SYNTAX$ + * HB_OSNewLine() --> cString + * $ARGUMENTS$ + * $RETURNS$ + * A character string containing the character or characters required + * to move the screen cursor or print head to the start of a new line. + * The string will hold either CHR( 10 ) or CHR( 13 ) + CHR( 10 ). + * $DESCRIPTION$ + * Returns a character string containing the character or characters + * required to move the screen cursor or print head to the start of a + * new line for the operating system that the program is running on + * (or thinks it is running on, if an OS emulator is being used). + * $EXAMPLES$ + * // Get the newline character(s) for the current OS using defaults. + * STATIC s_cNewLine + * ... + * s_cNewLine := HB_OSNewLine() + * ... + * OutStd( "Hello World!" + s_cNewLine ) + * ... + * $TESTS$ + * valtype( HB_OSNewLine() ) == "C" + * LEN( HB_OSNewLine() ) == 1 + * $STATUS$ + * R + * $COMPLIANCE$ + * This is an add-on Operating System Tool function. + * $SEEALSO$ + * OS(),OUTSTD(),OUTERR() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * hb_ColorIndex() + * $CATEGORY$ + * GT + * $ONELINER$ + * Extract one color from a full Clipper colorspec string. + * $SYNTAX$ + * hb_ColorIndex( , ) + * $ARGUMENTS$ + * is a Clipper color list + * is the position of the color item to be extracted, the first + * position is the zero. + * $RETURNS$ + * The selected color string, or if anything goes wrong, and empty + * string + * $DESCRIPTION$ + * Clipper has a color spec string, which has more than one + * color in it, separated with commas. This function is able to extract + * a given item from this list. You may use the manifest constants + * defined in color.ch to extract common Clipper colors. + * $EXAMPLES$ + * ? hb_ColorIndex( "W/N, N/W", CLR_ENHANCED ) // "N/W" + * $TESTS$ + * see the regression test suit for comprehensive tests. + * $STATUS$ + * R + * $COMPLIANCE$ + * Was not part of CA-Clipper. + * $SEEALSO$ + * ColorSelect() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * DEVOUTPICT() + * $CATEGORY$ + * Terminal + * $ONELINER$ + * Displays a value to a device using a picture template + * $SYNTAX$ + * DEVOUTPICT(,[,]) --> NIL + * $ARGUMENTS$ + * is any valid expression. + * is any picture transformation that TRANSFORM() can use. + * is an optional string that specifies a screen color to + * use in place of the default color when the output goes to the screen. + * $RETURNS$ + * NIL + * $DESCRIPTION$ + * Outputs any expression using a picture transformation instead of + * using the default transformation for the type of expression. + * $EXAMPLES$ + * // Output a negative dollar amount using debit notation. + * DEVOUTPICT( -1.25, "@D$ 99,999.99 ) + * $TESTS$ + * @ 3,1 SAY -1.25 PICTURE "@D$ 99,999.99" + * will display "$( 1.25)" starting on row four, column two of the + * current device (without the double quotation marks, of course). + * $STATUS$ + * R + * $COMPLIANCE$ + * DEVOUTPICT() is mostly CA-Clipper compliant. Any differences are due + * to enhancements in the Harbour TRANSFORM() over CA-Clipper. + * $SEEALSO$ + * DEVOUT(),TRANSFORM() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __INPUT() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Stops application + * $SYNTAX$ + * __INPUT( ) --> + * $ARGUMENTS$ + * is any valid expression. + * $RETURNS$ + * Macroed + * $DESCRIPTION$ + * This function waits for a console input and returns macroed + * expression entered. + * $EXAMPLES$ + * + * + * $TESTS$ + * + * + * $STATUS$ + * S + * $COMPLIANCE$ + * __INPUT() is fully CA-Clipper compliant. + * $SEEALSO$ + * __WAIT(),__ACCEPT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __TextSave() + * $CATEGORY$ + * Internal + * $ONELINER$ + * Redirect console output to printer or file and save old settings + * $SYNTAX$ + * __TextSave( ) --> NIL + * $ARGUMENTS$ + * is either "PRINTER" (note the uppercase) in which console + * output is SET to PRINTER, or a name of a text file with a default + * ".txt" extension, that is used to redirect console output. + * $RETURNS$ + * __TextSave() always return NIL. + * $DESCRIPTION$ + * __TextSave() is used in the preprocessing of the TEXT TO command to + * redirect the console output while saving old settings that can be + * restored later by __TextRestore(). + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __TextSave() is an Undocumented CA-Clipper function + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * SET(),SET ALTERNATE,SET PRINTER,TEXT,__TextRestore() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __TextRestore() + * $CATEGORY$ + * Internal + * $ONELINER$ + * Restore console output settings as saved by __TextSave() + * $SYNTAX$ + * __TextRestore() --> NIL + * $ARGUMENTS$ + * none. + * $RETURNS$ + * __TextRestore() always return NIL. + * $DESCRIPTION$ + * __TextRestore() is used in the preprocessing of the TEXT TO command + * to restore console output settings that were previously saved by + * __TextSave(). + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * __TextRestore() is an Undocumented CA-Clipper function + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * SET(),SET ALTERNATE,SET PRINTER,TEXT,__TextSave() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __WAIT() + * $CATEGORY$ + * Events + * $ONELINER$ + * Stops the application until a key is pressed. + * $SYNTAX$ + * __WAIT( ) --> + * $ARGUMENTS$ + * is a string. + * $RETURNS$ + * Pressed key. + * $DESCRIPTION$ + * This function stops the application until a key is pressed. The key + * must be in the range 32..255. Control keys are not processed. + * $EXAMPLES$ + * // Wait for a key stroke + * __Wait( "Press a key to continue" ) + * $TESTS$ + * do while cKey != "Q" + * cKey := __Wait( "Press 'Q' to continue" ) + * end do + * $STATUS$ + * R + * $COMPLIANCE$ + * __WAIT() is fully CA-Clipper compliant. + * $SEEALSO$ + * __ACCEPT(),__INPUT() + * $END$ + */ + diff --git a/harbour/doc/en/tgetlist.txt b/harbour/doc/en/tgetlist.txt new file mode 100644 index 0000000000..917551b862 --- /dev/null +++ b/harbour/doc/en/tgetlist.txt @@ -0,0 +1,62 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Chen Kedem + * READVAR() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * READVAR() + * $CATEGORY$ + * Data input and output + * $ONELINER$ + * Return variable name of current GET or MENU + * $SYNTAX$ + * READVAR( [] ) --> cOldVarName + * $ARGUMENTS$ + * is a new variable name to set. + * $RETURNS$ + * READVAR() return the old variable name. If no variable previously + * was set, READVAR() return "". + * $DESCRIPTION$ + * READVAR() is set inside a READ or MENU TO command to hold the + * uppercase name of the GET / MENU TO variable, and re-set back to old + * value when those commands finished. You should not normally set a + * variable name but rather use it to retrieve the name of a GET + * variable when executing a VALID or WHEN clause, or during SET KEY + * execution and you are inside a READ or MENU TO. + * $EXAMPLES$ + * // display a menu, press F1 to view the MENU TO variable name + * CLS + * @ 1, 10 PROMPT "blood sucking insect that infect beds " + * @ 2, 10 PROMPT "germ; virus infection " + * @ 3, 10 PROMPT "defect; snag; (source of) malfunctioning" + * @ 4, 10 PROMPT "small hidden microphone " + * @ 6, 10 SAY "(Press F1 for a hint)" + * SET KEY 28 TO ShowVar + * MENU TO What_Is_Bug + * + * PROCEDURE ShowVar + * ALERT( READVAR() ) // WHAT_IS_BUG in red ALERT() box + * $TESTS$ + * $STATUS$ + * $COMPLIANCE$ + * READVAR() works exactly like CA-Clipper's READKEY(), note however, + * that the parameter is not documented and used internally + * by CA-Clipper. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * @...GET,@...PROMPT,MENU TO,READ,SET KEY,__AtPrompt(),__MenuTo() + * $END$ + */ + diff --git a/harbour/doc/en/tlabel.txt b/harbour/doc/en/tlabel.txt new file mode 100644 index 0000000000..84ac8ed4a7 --- /dev/null +++ b/harbour/doc/en/tlabel.txt @@ -0,0 +1,75 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Luiz Rafael Culik + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * LABEL FORM + * $CATEGORY$ + * Command + * $ONELINER$ + * Displays labels to the screen or an alternate device + * $SYNTAX$ + * LABEL FORM [TO PRINTER] [TO FILE ] [] + * [WHILE ] [FOR ] [SAMPLE] [NOCONSOLE] + * $ARGUMENTS$ + * Name of label file + * Name of an alternate I lie + * Expression of a scoping condition + * WHILE condition + * FOR condition + * $RETURNS$ + * + * $DESCRIPTION$ + * + * This command allows labels to be printed based on the format outlined in + * .LBL file specified as . By default, output will go to the + * screen however this output may be rerouted with either the TO PRINTER or + * the TO FILE clause. + * If the TO FILE clause is specified, the name of the ASCII text file + * containing the generated labels will be . + * If no file extension is specified a .TXT extension is added. + * is the scope condition for this command. Valid scopes include + * NEXT (number of records to be displayed, where is the number + * of records), RECORD (a specific record to be printed), REST (all + * records starting from the current record position,and ALL (all records). + * The default is ALL. + * Both logical expression may work ill conjunction with one another where + * is the logical expression for the FOR condition (for records to + * be displayed whitin a given value range) and for the WHILE + * condition (for records to be displayed until they fail to meet the + * condition). + * If the SAMPLE clause is specified, test labels will be generated. + * If the NOCONSOLE clause is specified,the console will be turned off while + * this command is being executed. + * This command follows the search criteria outlined in the SET PATH TO + * command. The path may be specified, along, with (the drive letter, in + * + * $EXAMPLES$ + * FUNCTION MAIN() + * USE Test New + * LABEL FORM EE + * USE + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This command is CA-Clipper compliant. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * REPORT FORM + * $END$ + */ diff --git a/harbour/doc/en/treport.txt b/harbour/doc/en/treport.txt new file mode 100644 index 0000000000..b625669b65 --- /dev/null +++ b/harbour/doc/en/treport.txt @@ -0,0 +1,92 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Luiz Rafael Culik + * Documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * REPORT FORM + * $CATEGORY$ + * Command + * $ONELINER$ + * Display a report + * $SYNTAX$ + * REPORT FORM [TO PRINTER] [TO FILE ] [] + * [WHILE ] [FOR ] [PLAIN |HEADING Name of report file + * Name of alternate file + * Scope + * Logical expression of WHILE condition + * Logical expression of FOR condition + * Report heading + * $RETURNS$ + * NIL + * $DESCRIPTION$ + * This command prints out the report named , which is a standard + * FRM file. The file extension is not required because FRM will be assumed. + * The SET PATH TO and SET DEFAULT TO commands affect the search for the file + * ; unless a drive and path are specified in , REPORT + * will search the path specified in the SET PATH command if it cannot find the + * report form in the current directory. + * The output of the report will be offset based on the setting of the SET MARGIN + * TO value. + * By default, output will go to the console; however, it may be controlled via + * either the TO PRINTER or TO FILE clause. If the output is to go to the file, + * the name of the alternate file is specified in . Unless specified in + * , the default file extension will be .TXT . + * is the scope for this command. Valid scopes include NEXT (where + * is tile number of records), RECORD (a specific record to be + * displayed), REST (all records from the current record position), and ALL + * (all records). The default is ALL. + * Both logical expressions may work in conjuntion with one another, where + * is the logical expression for the FOR condition (for records to be displayed + * within a given range) and for the WHILE condition (for records to be + * displayed until the condition fails). + * If the PLAIN clause is specified, date and page numbers are suppressed. In + * addition, there is no automatic page breaking, and the report title and + * column headings appear only once at the top of the form. + * If the HEADING clause is used, is displayed on the first title + * of each report page. The value of is evaluated only once before + * executing the report; varying the values of is not allowed. The + * PLAIN clause will take precedence over the HEADING clause if both are included. + * If the NOEJECT clause is used, the initial page eject on the report will not be + * issued when the output clause TO PRINTER is specified. Otherwise, this clause has + * no effect. + * If the SUMMARY Clause is specified, the report will contain only groups, subgroups, + * and grand total information. The detailed title item information will be ignored. + * If the NOCONSOLE clause is specified,output to the console will be turned off + * while this command is being executed. + * $EXAMPLES$ + * FUNCTION() MAIN + * + * USE Test New + * + * Report FORM EE + * + * USE + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * This Command is CA-Clipper compliant. + * $PLATFORMS$ + * ALL + * $FILES$ + * $SEEALSO$ + * LABEL FORM + * $END$ + */ diff --git a/harbour/doc/en/var.txt b/harbour/doc/en/var.txt new file mode 100644 index 0000000000..65ebaf84e1 --- /dev/null +++ b/harbour/doc/en/var.txt @@ -0,0 +1,737 @@ +/* + * $Id$ + */ + +/* + * The following parts are Copyright of the individual authors. + * www - http://www.harbour-project.org + * + * Copyright 1999 Ryszard Glab + * __MV*() documentation + * MEMVARBLOCK() documentation + * TYPE() documentation + * + * Copyright 1999 Chen Kedem + * FIELDBLOCK() documentation + * FIELDWBLOCK() documentation + * + * See doc/license.txt for licensing terms. + * + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVPUBLIC() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function creates a PUBLIC variable + * $SYNTAX$ + * __MVPUBLIC( ) + * $ARGUMENTS$ + * = either a string that contains the variable's name or + * an one-dimensional array of strings with variable names + * No skeleton are allowed here. + * $RETURNS$ + * Nothing + * $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 variable. + * If a variable with the same name exists already then the new + * variable is not created - the previous value remains unchanged. + * If it is first variable with this name then the variable is + * initialized with .T. value. + * + * $EXAMPLES$ + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVPRIVATE() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function creates a PRIVATE variable + * $SYNTAX$ + * __MVPRIVATE( ) + * $ARGUMENTS$ + * = either a string that contains the variable's name or + * an one-dimensional array of strings with variable names + * No skeleton are allowed here. + * $RETURNS$ + * Nothing + * $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 variable. + * If a variable with the same name exists already then the value of old + * variable is hidden until the new variable is released. The new variable + * is always initialized to NIL value. + * + * $EXAMPLES$ + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVXRELEASE() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function releases value stored in PRIVATE or PUBLIC variable + * $SYNTAX$ + * __MVXRELEASE( ) + * $ARGUMENTS$ + * = either a string that contains the variable's name or + * an one-dimensional array of strings with variable names + * No skeleton are allowed here. + * $RETURNS$ + * Nothing + * $DESCRIPTION$ + * This function releases values stored in memory variable. It shouldn't + * be called directly, rather it should be placed into RELEASE command. + * If the released variable is a PRIVATE variable then previously hidden + * variable with the same name becomes visible after exit from the + * procedure where released variable was created. If you access + * the released variable in the same function/procedure where it + * was created the the NIL value is returned. You can however assign + * a new value to released variable without any side effects. + * + * It releases variable even if this variable was created in different + * procedure + * $EXAMPLES$ + * + * PROCEDURE MAIN() + * PRIVATE mPrivate + * + * mPrivate :="PRIVATE from MAIN()" + * ? mPrivate //PRIVATE from MAIN() + * Test() + * ? mPrivate //PRIVATE from MAIN() + * + * RETURN + * + * PROCEDURE Test() + * PRIVATE mPrivate + * + * mPrivate :="PRIVATE from Test()" + * ? mPrivate //PRIVATE from TEST() + * RELEASE mPrivate + * ? mPrivate //NIL + * mPrivate :="Again in Test()" + * + * RETURN + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVRELEASE() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function releases PRIVATE variables + * $SYNTAX$ + * __MVRELEASE( , ) + * $ARGUMENTS$ + * = string that contains the wildcard mask for variables' names + * that will be released. Supported wildcards: '*' and '?' + * = logical value that specifies if variables + * that match passed skeleton should be either included in deletion + * (if .T.) or excluded from deletion (if .F.) + * $RETURNS$ + * Nothing + * $DESCRIPTION$ + * This function releases values stored in memory variables. It shouldn't + * be called directly, it should be placed into RELEASE ALL command. + * If the released variable is a PRIVATE variable then previously hidden + * variable with the same name becomes visible after exit from the + * procedure where released variable was created. If you access + * the released variable in the same function/procedure where it + * was created the the NIL value is returned. You can however assign + * a new value to released variable without any side effects. + * PUBLIC variables are not changed by this function. + * $EXAMPLES$ + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVSCOPE() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * If variable exists then returns its scope. + * $SYNTAX$ + * __MVSCOPE( ) + * $ARGUMENTS$ + * = a string with a variable name to check + * $RETURNS$ + * The symbolic values are defined in include/hbmemvar.ch + * HB_MV_NOT_FOUND =variable is not declared (not found in symbol table) + * HB_MV_UNKNOWN =if variable doesn't exist (but found in symbol table) + * HB_MV_ERROR =if information cannot be obtained (memory error + * or argument error) + * HB_MV_PUBLIC =for public variables + * HB_MV_PRIVATE_GLOBAL =for private variables declared outside of current + * function/procedure + * HB_MV_PRIVATE_LOCAL =for private variables declared in current + * function/procedure + * $DESCRIPTION$ + * + * $EXAMPLES$ + * + * PROCEDURE MAIN() + * PUBLIC mPublic + * PRIVATE mPrivateGlobal + * + * CallProc() + * ? __mvScope( "mPrivateLocal" ) //HB_MV_UNKNOWN + * + * RETURN + * + * PROCEDURE CallProc() + * PRIVATE mPrivateLocal + * + * ? __mvScope( "mPublic" ) //HB_MV_PUBLIC + * ? __mvScope( "mPrivateGlobal" ) //HB_MV_PRIVATE_GLOBAL + * ? __mvScope( "mPrivateLocal" ) //HB_MV_PRIVATE_LOCAL + * ? __mvScope( "mFindMe" ) //HB_MV_NOT_FOUND + * + * IF( __mvScope( "mPublic" ) > HB_MV_ERROR ) + * ? "Variable exists" + * ELSE + * ? "Variable not created yet" + * ENDIF + * + * RETURN + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * include/hbmemvar.ch + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVCLEAR() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function releases all PRIVATE and PUBLIC variables + * $SYNTAX$ + * __MVCLEAR() + * $ARGUMENTS$ + * + * $RETURNS$ + * Nothing + * $DESCRIPTION$ + * This function releases all PRIVATE and PUBLIC variables. + * It is used to implement CLEAR MEMORY statement. + * The memory occupied by all visible variables are released - any + * attempt to access the variable will result in a runtime error. + * You have to reuse PRIVATE or PUBLIC statement to create again + * the variable that was cleared by this function. + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVDBGINFO() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function returns the information about the variables for debugger + * $SYNTAX$ + * __MVDBGINFO( [, [, @] ] ) + * $ARGUMENTS$ + * = the scope of variables for which an information is asked + * Supported values (defined in hbmemvar.ch) + * HB_MV_PUBLIC + * HB_MV_PRIVATE (or any other value) + * = the position of asked variable on the list of variables + * with specified scope - it should start from position 1 + * = the value is filled with a variable name if passed by + * reference and is specified + * $RETURNS$ + * The return value depends on the number of arguments passed + * $DESCRIPTION$ + * This function retrieves the information about memvar variables. + * It returns either the number of variables with given scope (when the + * first argument is passed only) or a value of variable identified by its + * position in the variables' list (when second argument is passed). + * It also returns the name of a variable if optional third argument + * is passed by reference. + * + * If requested variable doesn't exist (requested position is + * greater then the number of defined variables) then NIL value is + * returned and variable name is set to "?" + * + * The dynamic symbols table is used to find a PUBLIC variable then + * the PUBLIC variables are always sorted alphabetically. The PRIVATE + * variables are sorted in the creation order. + * + * Note: + * Due to dynamic nature of memvar variables there is no guarantee that + * successive calls to retrieve the value of PUBLIC variable will + * return the value of the same variable. + * $EXAMPLES$ + * + * #include + * + * LOCAL nCount, i, xValue, cName + * + * nCount =_mvDBGINFO( HB_MV_PUBLIC ) + * FOR i:=1 TO nCount + * xValue =__mvDBGINFO( HB_MV_PUBLIC, i, @cName ) + * ? i, cName, xValue + * NEXT + * + * $TESTS$ + * + * #include + * PROCEDURE MAIN() + * + * ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC ) + * ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE ) + * + * PUBLIC cPublic:='cPublic in MAIN' + * + * ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC ) + * ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE ) + * + * PRIVATE cPrivate:='cPrivate in MAIN' + * + * ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC ) + * ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE ) + * + * CountMemvars() + * + * ? 'Back in Main' + * ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC ) + * ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE ) + * + * + * RETURN + * + * PROCEDURE CountMemvars() + * LOCAL i, nCnt, xVal, cName + * PUBLIC ccPublic:='ccPublic' + * PRIVATE ccPrivate:='ccPrivate' + * + * ? 'In CountMemvars' + * ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC ) + * ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE ) + * + * PRIVATE cPublic:='cPublic' + * + * ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC ) + * ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE ) + * + * nCnt =__mvDBGINFO( HB_MV_PRIVATE ) +1 + * FOR i:=1 TO nCnt + * xVal =__mvDBGINFO( HB_MV_PRIVATE, i, @cName ) + * ? i, '=', cName, xVal + * NEXT + * + * nCnt =__mvDBGINFO( HB_MV_PUBLIC ) +1 + * FOR i:=1 TO nCnt + * xVal =__mvDBGINFO( HB_MV_PUBLIC, i, @cName ) + * ? i, '=', cName, xVal + * NEXT + * + * RETURN + * + * $STATUS$ + * R + * $COMPLIANCE$ + * This function should be called from the debugger only. + * $SEEALSO$ + * + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVGET() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function returns value of memory variable + * $SYNTAX$ + * __MVGET( ) + * $ARGUMENTS$ + * - string that specifies the name of variable + * $RETURNS$ + * The value of variable + * $DESCRIPTION$ + * This function returns the value of PRIVATE or PUBLIC variable if + * this variable exists otherwise it generates a runtime error. + * The variable is specified by its name passed as the function parameter. + * $EXAMPLES$ + * FUNCTION MEMVARBLOCK( cMemvar ) + * RETURN {|x| IIF( PCOUNT()==0, __MVGET( cMemvar ),; + * __MVPUT( cMemvar, x ) ) } + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * __MVPUT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * __MVPUT() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * This function set the value of memory variable + * $SYNTAX$ + * __MVGET( [, ] ) + * $ARGUMENTS$ + * - string that specifies the name of variable + * - a value of any type that will be set - if it is not + * specified then NIL is assumed + * $RETURNS$ + * A value assigned to the given variable. + * $DESCRIPTION$ + * This function sets the value of PRIVATE or PUBLIC variable if + * this variable exists otherwise it generates a runtime error. + * The variable is specified by its name passed as the function + * parameter. + * If a value is not specified then the NIL is assumed + * $EXAMPLES$ + * FUNCTION MEMVARBLOCK( cMemvar ) + * RETURN {|x| IIF( PCOUNT()==0, __MVGET( cMemvar ),; + * __MVPUT( cMemvar, x ) ) } + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * __MVPUT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * MEMVARBLOCK() + * $CATEGORY$ + * Variable Management + * $ONELINER$ + * Returns a codeblock that sets/gets a value of memvar variable + * $SYNTAX$ + * MEMVARBLOCK( ) + * $ARGUMENTS$ + * - a string that contains the name of variable + * $RETURNS$ + * a codeblock that sets/get the value of variable + * $DESCRIPTION$ + * This function returns a codeblock that sets/gets the value of + * PRIVATE or PUBLIC variable. When this codeblock is evaluated + * without any parameters passed then it returns the current value + * of given variable. If the second parameter is passed for + * the codeblock evaluation then its value is used to set the new + * value of given variable - the passed value is also returned + * as a value of the codeblock evaluation. + * $EXAMPLES$ + * PROCEDURE MAIN() + * LOCAL cbSetGet + * PUBLIC xPublic + * + * cbSetGet = MEMVARBLOCK( "xPublic" ) + * EVAL( cbSetGet, "new value" ) + * ? "Value of xPublic variable", EVAL( cbSetGet ) + * + * RETURN + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * $SEEALSO$ + * __MVGET(),__MVPUT() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDBLOCK() + * $CATEGORY$ + * Code Block + * $ONELINER$ + * Return a code block that sets/gets a value for a given field + * $SYNTAX$ + * FIELDBLOCK( ) --> bFieldBlock + * $ARGUMENTS$ + * is a string that contain the field name. + * $RETURNS$ + * FIELDBLOCK() return a code block that when evaluate could retrieve + * field value or assigning a new value to the field. If + * is not specified or from type other than character, FIELDBLOCK() + * return NIL. + * $DESCRIPTION$ + * FIELDBLOCK() return a code block that sets/gets the value of field. + * When this code block is evaluated without any parameters passed then + * it returns the current value of the given field. If the code block + * is evaluated with a parameter, than its value is used to set a new + * value to the field, this value is also return by the block. If the + * block is evaluate and there is no field with the name + * in the current work area, the code block return NIL. + * + * Note that FIELDBLOCK() works on the current work area, if you need + * a specific work area code block use FIELDWBLOCK() instead. + * $EXAMPLES$ + * // open a file named Test that have a field named "name" + * LOCAL bField + * bFiled := FIELDBLOCK( "name" ) + * USE Test + * ? 'Original value of field "name" :', EVAL( bField ) + * EVAL( bField, "Mr X new name" ) + * ? 'New value for the field "name" :', EVAL( bField ) + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * If the block is evaluate and there is no field with the name + * in the current work area, the code block return NIL. + * + * CA-Clipper would raise BASE/1003 error if the field does not exist. + * $SEEALSO$ + * EVAL(),FIELDWBLOCK(),MEMVARBLOCK() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * FIELDWBLOCK() + * $CATEGORY$ + * Code Block + * $ONELINER$ + * Return a sets/gets code block for field in a given work area + * $SYNTAX$ + * FIELDWBLOCK( , ) --> bFieldBlock + * $ARGUMENTS$ + * is a string that contain the field name. + * + * is the work area number in which exist. + * $RETURNS$ + * FIELDWBLOCK() return a code block that when evaluate could retrieve + * field value or assigning a new value for a field in a given work + * area. If is not specified or from type other than + * character, or if is not specified or is not numeric + * FIELDWBLOCK() return NIL. + * $DESCRIPTION$ + * FIELDWBLOCK() return a code block that sets/gets the value of field + * from a given work area. When this code block is evaluated without + * any parameters passed then it returns the current value of the given + * field. If the code block is evaluated with a parameter, than its + * value is used to set a new value to the field, this value is also + * return by the block. If the block is evaluate and there is no field + * with the name in work area number , the code + * block return NIL. + * $EXAMPLES$ + * LOCAL bField + * // this block work on the field "name" that exist on work area 2 + * bFiled := FIELDBLOCK( "name", 2 ) + * // open a file named One in work area 1 + * // that have a field named "name" + * SELECT 1 + * USE One + * // open a file named Two in work area 2 + * // it also have a field named "name" + * SELECT 2 + * USE Two + * SELECT 1 + * ? "Original names: ", One->name, Two->name + * ? "Name value for file Two :", EVAL( bField ) + * EVAL( bField, "Two has new name" ) + * ? "and now: ", One->name, Two->name + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * If the block is evaluate and there is no field with the name + * in the given work area, the code block return NIL. + * + * CA-Clipper would raise BASE/1003 error if the field does not exist. + * $SEEALSO$ + * EVAL(),FIELDBLOCK(),MEMVARBLOCK() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * TYPE() + * $CATEGORY$ + * Misc + * $ONELINER$ + * Retrieves the type of an expression + * $SYNTAX$ + * TYPE( ) --> + * $ARGUMENTS$ + * must be a character expression. + * $RETURNS$ + * Returns a string indicating the type of the passed expression. + * + * "A" - array + * "B" - block + * "C" - string + * "D" - date + * "L" - logical + * "M" - memo + * "N" - numeric + * "O" - object + * "U" - NIL, local, or static variable, or not linked-in function + * "UE" - syntax error in the expression or invalid arguments + * "UI" - function with non-reserved name was requested + * $DESCRIPTION$ + * This function returns a string which represents the data type + * of the argument. The argument can be any valid Harbour expression. + * If there is a syntax error in passed expression then "UE" is returned. + * If there is a call for any non-reserved Harbour function then "UI" + * is returned (in other words there is no call for passed UDF function + * during a data type determination - this is Clipper compatible + * behavior). Additionally if requested user defined function is not + * linked into executable then "U" is returned. + * + * The data type of expression is checked by invoking a macro compiler + * and by evaluation of generated code (if there is no syntax errors). + * This causes that TYPE() cannot determine a type of local or static + * variables - only symbols visible at runtime can be checked. + * + * Notice the subtle difference between TYPE and VALTYPE functions. + * VALTYPE() function doesn't call a macro compiler - it simply checks + * the type of passed argument of any type. TYPE() requires a string + * argument with a valid Harbour expression - the data type of this + * expression is returned. + * + * Notes: + * - Incompatibility with Clipper: + * In the following code: + * + * PRIVATE lCond := 0 + * ? TYPE( "IIF( lCond, 'true', MyUDF() )" ) + * + * Clipper will print "UE" - in Harbour the output will be "UI" + * + * - if "UI" is returned then the syntax of the expression is + * correct. However invalid arguments can be passed to + * function/procedure that will cause runtime errors during + * evaluation of expression. + * + * $EXAMPLES$ + * ? TYPE( "{ 1, 2 }" ) //prints "A" + * ? TYPE( "IIF(.T., SUBSTR('TYPE',2,1), .F.)" ) //prints "C" + * ? TYPE( "AT( 'OK', MyUDF())>0" ) //prints "UI" + * ? TYPE( "{ 1, 2 }[ 5 ]" ) //prints "UE" + * + * //-------------------------------------------------------- + * + * LOCAL c + * PRIVATE a:="A", b:="B" + * ? TYPE( "a + b + c" ) //prints: "U" ('C' variable is a local one) + * + * //-------------------------------------------------------- + * + * LOCAL cFilter := SPACE( 60 ) + * ACCEPT "Enter filter expression:" TO cFilter + * IF( TYPE( cFilter ) $ "CDLMN" ) ) + * // this is a valid expression + * SET FILTER TO &cFilter + * ENDIF + * + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * VALTYPE() + * $END$ + */ + +/* $DOC$ + * $FUNCNAME$ + * VALTYPE() + * $CATEGORY$ + * Misc + * $ONELINER$ + * Retrieves the data type of an expression + * $SYNTAX$ + * VALTYPE( ) --> + * $ARGUMENTS$ + * is any valid expression. + * $RETURNS$ + * Returns a character indicating the type of the passed expression. + * $DESCRIPTION$ + * This function returns one character which represents the date type + * of the argument. + * $EXAMPLES$ + * See Test + * $TESTS$ + * function Test() + * ? ValType( Array( 1 ) ) --> "A" + * ? ValType( {|| 1 + 1 } ) --> "B" + * ? ValType( "HARBOUR" ) --> "C" + * ? ValType( Date() ) --> "D" + * ? ValType( .T. ) --> "L" + * ? ValType( 1 ) --> "N" + * ? ValType( TBrowse() ) --> "O" + * ? ValType( NIL ) --> "U" + * return nil + * $STATUS$ + * R + * $COMPLIANCE$ + * VALTYPE() is fully CA-Clipper compliant. + * $SEEALSO$ + * TYPE() + * $END$ + */