From e0a82cccea62abe3fa0fe902bba40c0368f6839e Mon Sep 17 00:00:00 2001 From: Luiz Rafael Culik Date: Sun, 2 Jan 2000 19:14:07 +0000 Subject: [PATCH] *** empty log message *** --- harbour/ChangeLog | 22 +++ harbour/source/rtl/arrays.c | 319 ++++++++++++++++---------------- harbour/source/rtl/browse.prg | 2 +- harbour/source/rtl/dbedit.prg | 2 +- harbour/source/rtl/dircmd.prg | 14 +- harbour/source/rtl/filesys.c | 174 ++++++++--------- harbour/source/rtl/inkey.c | 40 +++- harbour/source/rtl/menuto.prg | 4 +- harbour/source/rtl/readvar.prg | 46 +++++ harbour/source/rtl/set.c | 14 +- harbour/source/rtl/setfunc.prg | 103 +++++++++++ harbour/source/rtl/setkey.prg | 53 ++++++ harbour/source/rtl/setta.prg | 2 +- harbour/source/rtl/text.prg | 3 +- harbour/source/rtl/xsavescr.prg | 12 +- 15 files changed, 535 insertions(+), 275 deletions(-) diff --git a/harbour/ChangeLog b/harbour/ChangeLog index e39c931831..aa618892f9 100644 --- a/harbour/ChangeLog +++ b/harbour/ChangeLog @@ -1,3 +1,25 @@ +20000102-17:10:00 GMT+3 Luiz Rafael Culik +* source/rtl/browdb.prg +* source/rtl/text.prg +* source/rtl/browse.prg +* source/rtl/dbedit.prg +* source/rtl/devoutp.prg +* source/rtl/dircmd.prg +* source/rtl/menuto.prg +* source/rtl/xsavescr.prg +* source/rtl/setkey.prg +* source/rtl/inkey.c + +Fixed some see also references for the Norton Guide + +Added documentatio to KEYBOARD and SET FUNCTION and SET KEY COMMAND +* source/rtl/fileysys.c +* source/rtl/array.c + + Updated docs for FCLOSE() FCREATE() FERASE() FERROR() ACLONE() + ACOPY() AEVAL() +* source/rtl/readkey.prg +* source/rtl/readvar.prg +* source/rtl/setfunc.prg + +Added the documentation to this functions since was accidentaly deleted + 20000101-22:50 GMT+3 Luiz Rafael Culik * doc/funclist.txt +Update some function status diff --git a/harbour/source/rtl/arrays.c b/harbour/source/rtl/arrays.c index 12819a6eb7..188ea60ca6 100644 --- a/harbour/source/rtl/arrays.c +++ b/harbour/source/rtl/arrays.c @@ -1298,98 +1298,93 @@ HARBOUR HB_AFILL( void ) * $ONELINER$ * Scan an array for a value or until a block returns true (.T.) * $SYNTAX$ - ASCAN(, , - [], []) --> nStoppedAt + * ASCAN(, , + * [], []) --> nStoppedAt * * $ARGUMENTS$ - is the array to scan. - - is either a simple value to scan for, or a code block. - If is a simple value it can be character, date, logical, or - numeric type. - - is the starting element of the scan. If this argument is - not specified, the default starting position is one. - - is the number of elements to scan from the starting - position. If this argument is not specified, all elements from the - starting element to the end of the array are scanned. - * + * Name of array to be scaned. + * + * Expression to search for withing + * + * Beggining subscript position at witch to start the + * search. + * + * Number of elements to scan with . + * position. If this argument is not specified, all elements from the + * * $RETURNS$ - ASCAN() returns a numeric value representing the array position of the - last element scanned. If is a simple value, ASCAN() returns - the position of the first matching element, or zero if a match is not - found. If is a code block, ASCAN() returns the position of - the element where the block returned true (.T.). + * A numeric value of subscript position where + * was found. * * $DESCRIPTION$ - ASCAN() is an array function that scans an array for a specified value - and operates like SEEK when searching for a simple value. The - value is compared to the target array element beginning with - the leftmost character in the target element and proceeding until there - are no more characters left in . If there is no match, - ASCAN() proceeds to the next element in the array. - - Since ASCAN() uses the equal operator (=) for comparisons, it is - sensitive to the status of EXACT. If EXACT is ON, the target array - element must be exactly equal to the result of to match. - - If the argument is a code block, ASCAN() scans the - array executing the block for each element accessed. As each element is - encountered, ASCAN() passes the element's value as an argument to the - code block, and then performs an EVAL() on the block. The scanning - operation stops when the code block returns true (.T.), or ASCAN() - reaches the last element in the array. + * ASCAN() is an array function that scans an array for a specified value + * and operates like SEEK when searching for a simple value. The + * value is compared to the target array element beginning with + * the leftmost character in the target element and proceeding until there + * are no more characters left in . If there is no match, + * ASCAN() proceeds to the next element in the array. + * + * Since ASCAN() uses the equal operator (=) for comparisons, it is + * sensitive to the status of EXACT. If EXACT is ON, the target array + * element must be exactly equal to the result of to match. + * + * If the argument is a code block, ASCAN() scans the + * array executing the block for each element accessed. As each element is + * encountered, ASCAN() passes the element's value as an argument to the + * code block, and then performs an EVAL() on the block. The scanning + * operation stops when the code block returns true (.T.), or ASCAN() + * reaches the last element in the array. * * $EXAMPLES$ - ^CFE This example demonstrates scanning a three-element array using - simple values and a code block as search criteria. The code block - criteria shows how to perform a case-insensitive search: - - aArray := { "Tom", "Mary", "Sue" } - ? ASCAN(aArray, "Mary") // Result: 2 - ? ASCAN(aArray, "mary") // Result: 0 - // - ? ASCAN(aArray, { |x| UPPER(x) ; - == "MARY" }) // Result: 2 - - ^CFE This example demonstrates scanning for multiple instances of a - search argument after a match is found: - - LOCAL aArray := { "Tom", "Mary", "Sue",; - "Mary" }, nStart := 1 - // - // Get last array element position - nAtEnd := LEN(aArray) - DO WHILE (nPos := ASCAN(aArray, "Mary", ; - nStart)) > 0 - ? nPos, aArray[nPos] - // - // Get new starting position and test - // boundary condition - IF (nStart := ++nPos) > nAtEnd - EXIT - ENDIF - ENDDO - - ^CFE This example scans a two dimensional array using a code block. - Note that the parameter aVal in the code block is an array: - - LOCAL aArr:={} - CLS - AADD(aArr,{"one","two"}) - AADD(aArr,{"three","four"}) - AADD(aArr,{"five","six"}) - ? ASCAN(aArr, {|aVal| aVal[2] == "four"}) // Returns 2 + * ^CFE This example demonstrates scanning a three-element array using + * simple values and a code block as search criteria. The code block + * criteria shows how to perform a case-insensitive search: + * + * aArray := { "Tom", "Mary", "Sue" } + * ? ASCAN(aArray, "Mary") // Result: 2 + * ? ASCAN(aArray, "mary") // Result: 0 + * // + * ? ASCAN(aArray, { |x| UPPER(x) ; + * == "MARY" }) // Result: 2 + * + * ^CFE This example demonstrates scanning for multiple instances of a + * search argument after a match is found: + * + * LOCAL aArray := { "Tom", "Mary", "Sue",; + * "Mary" }, nStart := 1 + * // + * // Get last array element position + * nAtEnd := LEN(aArray) + * DO WHILE (nPos := ASCAN(aArray, "Mary", ; + * nStart)) > 0 + * ? nPos, aArray[nPos] + * // + * // Get new starting position and test + * // boundary condition + * IF (nStart := ++nPos) > nAtEnd + * EXIT + * ENDIF + * ENDDO + * + * ^CFE This example scans a two dimensional array using a code block. + * Note that the parameter aVal in the code block is an array: + * + * LOCAL aArr:={} + * CLS + * AADD(aArr,{"one","two"}) + * AADD(aArr,{"three","four"}) + * AADD(aArr,{"five","six"}) + * ? ASCAN(aArr, {|aVal| aVal[2] == "four"}) // Returns 2 * * $TESTS$ * * $STATUS$ * R * $COMPLIANCE$ - * + * This functions is not CA-Clipper compatible. Clipper ASCAN() is + * affected by the SET EXACT ON/OFF Condition * $SEEALSO$ - * EVAL() AEVAL() + * ACOMP() AEVAL() * $INCLUDE$ * * $END$ @@ -1419,42 +1414,38 @@ HARBOUR HB_ASCAN( void ) * $CATEGORY$ * ARRAY * $ONELINER$ - * Execute a code block for each element in an array + * Evaluated the subscript element of an array * $SYNTAX$ - AEVAL(, , - [], []) --> aArray + * AEVAL(, , + * [], []) --> aArray * * $ARGUMENTS$ - is the array to traverse. - - is a code block to execute for each element encountered. - - is the starting element. If not specified, the default is - element one. - - is the number of elements to process from . If not - specified, the default is all elements to the end of the array. + * Is the array to be evaluated. + * + * Is a code block to evaluate for each element processed. + * + * The beggining array element to evaluate. + * + * The number of elements to process. * * $RETURNS$ - AEVAL() returns a reference to . + * AEVAL() returns an array pointer reference. * * $DESCRIPTION$ - AEVAL() is an array function that evaluates a code block once for each - element of an array, passing the element value and the element index as - block parameters. The return value of the block is ignored. All - elements in are processed unless either the or the - argument is specified. - - AEVAL() makes no assumptions about the contents of the array elements it - is passing to the block. It is assumed that the supplied block knows - what type of data will be in each element. - - AEVAL() is similar to DBEVAL() which applies a block to each record of a - database file. Like DBEVAL(), AEVAL() can be used as a primitive for - the construction of iteration commands for both simple and complex array - structures. - - * + * 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 + * beggining 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 a array is an autonomous unit,AEVAL() is appropriate.If the + * array is to be altered or if elements are to be reevalueted, a + * FOR...NEXT loop is more appropriate. * $EXAMPLES$ * * $TESTS$ @@ -1464,7 +1455,7 @@ HARBOUR HB_ASCAN( void ) * $COMPLIANCE$ * * $SEEALSO$ - * + * EVAL() database.ngo:DBEVAL() * $INCLUDE$ * * $END$ @@ -1498,49 +1489,53 @@ HARBOUR HB_AEVAL( void ) * $ONELINER$ * Copy elements from one array to another * $SYNTAX$ - ACOPY(, , - [], [], []) --> aTarget + * ACOPY(, , + * [], [], []) --> aTarget * * $ARGUMENTS$ - is the array to copy elements from. - - is the array to copy elements to. - - is the starting element position in the array. - If not specified, the default value is one. - - is the number of elements to copy from the array - beginning at the position. If is not specified, all - elements in beginning with the starting element are copied. - - is the starting element position in the array - to receive elements from . If not specified, the default value - is one. + * is the array to copy elements from. + * + * is the array to copy elements to. + * + * is the beggining 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 a reference to the target array, . + * ACOPY() returns an array pointer reference * $DESCRIPTION$ - ACOPY() is an array function that copies elements from the - array to the array. The array must already exist - and be large enough to hold the copied elements. If the array - has more elements, some elements will not be copied. - - ACOPY() copies values of all data types including NIL and code blocks. - If an element of the array is a subarray, the corresponding - element in the array will contain a reference to the subarray. - Thus, ACOPY() will not create a complete duplicate of a multidimensional - array. To do this, use the ACLONE() function. - * + * This function copies array elements from to . + * is the beggining element to be copied from ;the + * default is 1. + * is the number of element to be copied from ;the + * default is the entire array. + * is the subscript number in the target array,, + * to witch 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. + * + * ^bNote + * 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$ - ^CFE This example creates two arrays, each filled with a value. - The first two elements from the source array are then copied into the - target array: - - LOCAL nCount := 2, nStart := 1, aOne, aTwo - aOne := { 1, 1, 1 } - aTwo := { 2, 2, 2 } - ACOPY(aOne, aTwo, nStart, nCount) - // Result: aTwo is now { 1, 1, 2 } + * ^CFE This example creates two arrays, each filled with a value. + * The first two elements from the source array are then copied into the + * target array: + * + * LOCAL nCount := 2, nStart := 1, aOne, aTwo + * aOne := { 1, 1, 1 } + * aTwo := { 2, 2, 2 } + * ACOPY(aOne, aTwo, nStart, nCount) + * // Result: aTwo is now { 1, 1, 2 } * * $TESTS$ * @@ -1588,30 +1583,28 @@ HARBOUR HB_ACOPY( void ) * $CATEGORY$ * ARRAY * $ONELINER$ - * Duplicate a nested or multidimensional array + * Duplicate a multidimensional array * $SYNTAX$ * ACLONE() --> aDuplicate * $ARGUMENTS$ - * is the array to duplicate. + * Name of the array to be cloned. * $RETURNS$ - * ACLONE() returns a duplicate of . + * ACLONE() A new array pointer reference complete with nested array + * values. * $DESCRIPTION$ - ACLONE() is an array function that creates a complete duplicate of the - array. If contains subarrays, ACLONE() creates - matching subarrays and fills them with copies of the values in the - subarrays. ACLONE() is similar to ACOPY(), but ACOPY() does - not duplicate nested arrays. - * + * This function makes a complete copy of the array expressed as + * and return a cloned set of array values.This provides + * a complete * $EXAMPLES$ - ^CFE 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 := { 1, 2, 3 } // Result: aOne is {1, 2, 3} - aTwo := ACLONE(aOne) // Result: aTwo is {1, 2, 3} - aOne[1] := 99 // Result: aOne is {99, 2, 3} - // aTwo is still {1, 2, 3} + * ^CFE 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 := { 1, 2, 3 } // Result: aOne is {1, 2, 3} + * aTwo := ACLONE(aOne) // Result: aTwo is {1, 2, 3} + * aOne[1] := 99 // Result: aOne is {99, 2, 3} + * // aTwo is still {1, 2, 3} * * $TESTS$ * diff --git a/harbour/source/rtl/browse.prg b/harbour/source/rtl/browse.prg index 06515fdd10..5cdcc50ed8 100644 --- a/harbour/source/rtl/browse.prg +++ b/harbour/source/rtl/browse.prg @@ -108,7 +108,7 @@ * $COMPLIANCE$ * * $SEEALSO$ - * DBEDIT()* 'TBrowse class' + * DBEDIT()* tbrow.ngo:'TBrowse class' * $END$ */ diff --git a/harbour/source/rtl/dbedit.prg b/harbour/source/rtl/dbedit.prg index 95cfa29193..972321d1bb 100644 --- a/harbour/source/rtl/dbedit.prg +++ b/harbour/source/rtl/dbedit.prg @@ -239,7 +239,7 @@ * $FILES$ * Header files are dbedit.ch, inkey.ch * $SEEALSO$ - * '@...SAY' BROWSE() 'TBrowse class' TRANSFORM() + * '@...SAY' BROWSE() tbrow.ngo:'TBrowse class' TRANSFORM() * $END$ */ diff --git a/harbour/source/rtl/dircmd.prg b/harbour/source/rtl/dircmd.prg index 7e60be4b2f..e33960b52a 100644 --- a/harbour/source/rtl/dircmd.prg +++ b/harbour/source/rtl/dircmd.prg @@ -98,7 +98,7 @@ * CA-Clipper use 8.3 file name, with Harbour it would probably cut * long file names to feet this template. * $SEEALSO$ - * array.ngo:ADIR() DIRECTORY() 'SET DEFAULT' + * array.ngo:ADIR() DIRECTORY() 'SET DEFAULT' comm.ngo:'DIR' * $END$ */ /* $DOC$ @@ -117,7 +117,7 @@ * 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, @@ -132,16 +132,16 @@ * __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 // information for all DBF files in current directory * - * __Dir( "*.dbf" ) // list all DBF file 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" ) + * Dir "c:\harbour\source\rtl\*.prg" * * // list all files in the public section on a Unix like machine - * __Dir( "/pub" ) + * Dir "/pub" * $TESTS$ * $STATUS$ * $COMPLIANCE$ @@ -153,7 +153,7 @@ * CA-Clipper use 8.3 file name, with Harbour it would probably cut * long file names to feet this template. * $SEEALSO$ - * array.ngo:ADIR() DIRECTORY() 'SET DEFAULT' + * array.ngo:ADIR() DIRECTORY() 'SET DEFAULT' filemana.ngo:__DIR() * $END$ */ diff --git a/harbour/source/rtl/filesys.c b/harbour/source/rtl/filesys.c index ea2ccb5308..a73556bb07 100644 --- a/harbour/source/rtl/filesys.c +++ b/harbour/source/rtl/filesys.c @@ -1437,55 +1437,38 @@ HARBOUR HB_FOPEN( void ) * $CATEGORY$ * LOW LEVEL * $ONELINER$ - * Create and/or truncate a binary file to zero-length + * Creates a file * $SYNTAX$ * FCREATE(, []) --> nHandle * $ARGUMENTS$ - * is the name of the file to create. If the file already - * exists, its length is truncated to zero without warning. + * is the name of the file to create. * - * is one of the binary file attributes shown in the table - * below. If this argument is omitted, the default value is zero. + * 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. * - * Binary File Attributes - * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 - * Value Fileio.ch Attribute Description - * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 - * 0 FC_NORMAL Normal Create normal read/write file (default) - * 1 FC_READONLY Read-only Create read-only file - * 2 FC_HIDDEN Hidden Create hidden file - * 4 FC_SYSTEM System Create system file - * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 - * - * $RETURNS$ - * FCREATE() returns the DOS file handle number of the new binary file in - * the range of zero to 65,535. If an error occurs, FCREATE() returns - * -1 and FERROR() is set to indicate an error code. - * $DESCRIPTION$ - * FCREATE() is a low-level file function that either creates a new file or - * opens and truncates an existing file. If does not exist, it is - * created and opened for writing. If it does exist and can be opened for - * writing, it is truncated to zero-length. If it cannot be opened for - * writing, FCREATE() returns -1 and FERROR() returns the appropriate error - * value. - * - * When FCREATE() successfully creates a new file, the file is left open in - * compatibility sharing mode and read/write access mode. The file - * attribute specified by the argument is applied to the new - * file when it is closed, allowing writing to a newly created read-only - * file. For a list of access modes, see FOPEN(). - * - * Since a file handle is required in order to identify an open file to - * other file functions, always assign the return value from FCREATE() to a - * variable for later use. - * - * Like other file functions, FCREATE() does not use either the DEFAULT or - * PATH settings for its operation. Instead, it writes to the current DOS - * directory unless a path is explicitly stated. - * - * Warning! This function allows low-level access to DOS files and - * devices. It should be used with extreme care and requires a thorough - * knowledge of the operating system. + * ^bValue 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$ * ^CFE This example creates a file called Testfile and opens it for * reading and writing: @@ -1507,7 +1490,7 @@ HARBOUR HB_FOPEN( void ) * $COMPLIANCE$ * This function is CA-CLIPPER compilant * $SEEALSO$ - * FOPEN() FCLOSE() FERROR() + * FCLOSE() FOPEN() FWRITE() FREAD() FERROR() * $INCLUDE$ * * $END$ @@ -1710,12 +1693,14 @@ HARBOUR HB_FWRITE( void ) * $CATEGORY$ * Low Level * $ONELINER$ - * Test for errors after a binary file operation + * Reports the error status of low-level file functions * $SYNTAX$ - * FERROR() --> nErrorCode + * FERROR() --> * $ARGUMENTS$ * - * $RETURNS$ + * $RETURNS$ + * Value of the DOS error last encountered by a + * low-level file function. * FERROR() returns the DOS error from the last file operation as an * integer numeric value. If there is no error, FERROR() returns zero. * @@ -1739,15 +1724,32 @@ HARBOUR HB_FWRITE( void ) * 32 Sharing violation * 33 Lock Violation * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 - * $DESCRIPTION$ - * FERROR() is a low-level file function that indicates a DOS error after a - * file function is used. These functions include FCLOSE(), FCREATE(), - * FERASE(), FOPEN(), FREAD(), FREADSTR(), and FRENAME(). FERROR() retains - * its value until the next execution of a file function. + * $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. + * + * FERROR() Return Values + * Value Reason + * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + * 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 * - * Warning! This function allows low-level access to DOS files and - * devices. It should be used with extreme care and requires a thorough - * knowledge of the operating system. * $EXAMPLES$ * ^CFE This example tests FERROR() after the creation of a binary * file and displays an error message if the create fails: @@ -1781,25 +1783,28 @@ HARBOUR HB_FERROR( void ) * $CATEGORY$ * Low Level * $ONELINER$ - * + * Closesan 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 compilant * $SEEALSO$ - * + * FOPEN() FCREATE() FREAD() FWRITE() FERROR() * $INCLUDE$ * * $END$ @@ -1823,26 +1828,27 @@ HARBOUR HB_FCLOSE( void ) * $CATEGORY$ * Low Level * $ONELINER$ - * Delete a file from disk + * Erase a file from disk * $SYNTAX$ * FERASE() --> nSuccess * $ARGUMENTS$ - * is the name of the file to be deleted from disk, including - * extension, optionally preceded by a drive and/or path specification. + * Name of file to erase. * $RETURNS$ - * FERASE() returns -1 if the operation fails and zero if it succeeds. In - * the case of a failure, FERROR() can be used to determine the nature of - * the error. - * $DESCRIPTION$ - * FERASE() is a file function that deletes a specified file from disk. - * FERASE() is the same as the ERASE command but returns a value and can be - * specified within an expression. When FERASE() is called, is - * deleted from disk only if found in the current DOS directory or in the - * directory explicitly specified as part of the filename. Like the other - * file functions and commands, FERASE() does not use either SET DEFAULT or - * SET PATH to locate . + * 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. * - * Warning! Files must be CLOSEd before removing them with FERASE(). * $EXAMPLES$ * ^CFE This example deletes a set of files matching a wildcard * pattern: @@ -1932,7 +1938,7 @@ HARBOUR HB_FERASE( void ) * $COMPLIANCE$ * This function is CA-Clipper compilant * $SEEALSO$ - * 'ERASE' FERASE() FERROR() FILE() 'RENAME' + * Comm.ngo:'ERASE' FERASE() FERROR() FILE() Comm.ngo:'RENAME' * $INCLUDE$ * * $END$ @@ -2090,7 +2096,7 @@ BOOL hb_fsFile( BYTE * pFilename ) * $CATEGORY$ * Low Level * $ONELINER$ - * Determine if files exists + * Tests for the existence of file(s) * $SYNTAX$ * FILE() --> lExists * $ARGUMENTS$ @@ -2521,7 +2527,7 @@ HARBOUR HB_FSETDEVMOD( void ) * $COMPLIANCE$ * This command is CA-Clipper compatible * $SEEALSO$ - * CURDIR() 'ERASE' FILE() FERASE() FRENAME() + * CURDIR() 'ERASE' lowlevel.ngo:FILE() lowlevel.ngo:FERASE() lowlevel.ngo:FRENAME() * $INCLUDE$ * * $END$ @@ -2531,7 +2537,7 @@ HARBOUR HB_FSETDEVMOD( void ) * $FUNCNAME$ * ERASE * $CATEGORY$ - * Comamnd + * Command * $ONELINER$ * Remove a file from disk * $SYNTAX$ @@ -2573,7 +2579,7 @@ HARBOUR HB_FSETDEVMOD( void ) * $COMPLIANCE$ * This command is CA-Clipper compatible * $SEEALSO$ - * CURDIR() FILE() + * CURDIR() lowlevel.ngo:FILE() * $INCLUDE$ * * $END$ diff --git a/harbour/source/rtl/inkey.c b/harbour/source/rtl/inkey.c index 1939935e77..44ed64359e 100644 --- a/harbour/source/rtl/inkey.c +++ b/harbour/source/rtl/inkey.c @@ -1014,7 +1014,7 @@ HARBOUR HB_INKEY( void ) * $COMPLIANCE$ * __KEYBOARD() is compliant with CA-Clipper 5.3 * $SEEALSO$ - * 'CLEAR TYPEAHEAD' 'KEYBOARD' + 'CLEAR TYPEAHEAD' comm.ngo:'KEYBOARD' * $END$ */ @@ -1224,3 +1224,41 @@ HARBOUR HB_FKMAX( void ) { hb_retni( 40 ); /* IBM specific */ } +/* $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' consimpu.ngo:__KEYBOARD() + * $END$ + */ diff --git a/harbour/source/rtl/menuto.prg b/harbour/source/rtl/menuto.prg index 1238f25aff..0fd2ad1434 100644 --- a/harbour/source/rtl/menuto.prg +++ b/harbour/source/rtl/menuto.prg @@ -184,7 +184,7 @@ function __AtPrompt( nRow, nCol, cPrompt, cMsg ) /* $DOC$ * $FUNCNAME$ - * __MenuTo() (MENU TO command) + * __MenuTo() * $CATEGORY$ * Data input and output * $ONELINER$ @@ -345,7 +345,7 @@ function __AtPrompt( nRow, nCol, cPrompt, cMsg ) * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * comm.ngo:'@...PROMPT' array.ngo:ACHOICE() 'SET MESSAGE' 'SET INTENSITY' 'SET WRAP' datai.ngo:__ATPROMPT() + * comm.ngo:'@...PROMPT' array.ngo:ACHOICE() 'SET MESSAGE' 'SET INTENSITY' 'SET WRAP' datai.ngo:__ATPROMPT() * $END$ */ diff --git a/harbour/source/rtl/readvar.prg b/harbour/source/rtl/readvar.prg index dd50b654ce..51a683cb74 100644 --- a/harbour/source/rtl/readvar.prg +++ b/harbour/source/rtl/readvar.prg @@ -32,6 +32,52 @@ * their web site at http://www.gnu.org/). * */ +/* $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 comm.ngo:'@...PROMPT' comm.ngo:'MENU TO' READ comm.ngo:'SET KEY' datai.ngo:__AtPrompt() datai.ngo:__MenuTo() + * $END$ + */ #include "common.ch" diff --git a/harbour/source/rtl/set.c b/harbour/source/rtl/set.c index bb20e8342a..60866ec6b7 100644 --- a/harbour/source/rtl/set.c +++ b/harbour/source/rtl/set.c @@ -395,7 +395,7 @@ HARBOUR HB_SETCANCEL( void ) * __SETCENTURY() * * $CATEGORY$ - * Enviroment + * Environment * $ONELINER$ * Set the Current Century @@ -406,9 +406,11 @@ HARBOUR HB_SETCANCEL( void ) * .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 + * Either the current or previous century setting as a logical value * $END$ */ + + HARBOUR HB___SETCENTURY( void ) { BOOL old_century_setting = hb_set.hb_set_century; @@ -495,10 +497,9 @@ HARBOUR HB___SETCENTURY( void ) * $FUNCNAME$ * SET() * $CATEGORY$ - * Enviroment + * Environment * $ONELINER$ * Changes or evaluated enviromental settings - * $SYNTAX$ * Set [, [, ] ] ) --> xPreviousSetting * $ARGUMENTS$ @@ -746,9 +747,12 @@ HARBOUR HB___SETCENTURY( void ) * 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 + * $RETURNS$ + * The current or previous setting * $END$ */ + + HARBOUR HB_SET( void ) { BOOL bFlag; diff --git a/harbour/source/rtl/setfunc.prg b/harbour/source/rtl/setfunc.prg index 693d63c26e..34446c9861 100644 --- a/harbour/source/rtl/setfunc.prg +++ b/harbour/source/rtl/setfunc.prg @@ -34,6 +34,58 @@ */ #include "inkey.ch" +/* $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$ + * consimpu.ngo:INKEY() event.ngo:SETKEY() consimpu.ngo:__Keyboard() + * $END$ + */ PROCEDURE __SetFunction( nFunctionKey, cString ) @@ -53,3 +105,54 @@ PROCEDURE __SetFunction( nFunctionKey, cString ) ENDIF RETURN +/* $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$ + * consimpu.ngo:INKEY() event.ngo:SETKEY() consimpu.ngo:__Keyboard() + * $END$ + */ diff --git a/harbour/source/rtl/setkey.prg b/harbour/source/rtl/setkey.prg index de38bde9d2..c51b7a2a25 100644 --- a/harbour/source/rtl/setkey.prg +++ b/harbour/source/rtl/setkey.prg @@ -99,6 +99,7 @@ static s_aSetKeys := {} // holds array of hot-key id, code-block, activati * HB_SETKEYSAVE() * $END$ */ + Function SetKey( anKey, bBlock, bCondition ) local nFound, bReturn, aKey @@ -169,6 +170,7 @@ return bReturn * SETKEY() HB_SETKEYSAVE() HB_SETKEYCHECK() * $END$ */ + Function HB_SetKeyGet( nKey, bCondition ) local nFound @@ -222,6 +224,7 @@ return NIL //bReturn * SETKEY() * $END$ */ + Function HB_SetKeySave( OldKeys ) local aReturn := aClone( s_aSetKeys ) @@ -311,3 +314,53 @@ Function HB_SetKeyCheck( nKey, p1, p2, p3 ) endif return .f. + +/* $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$ + */ + diff --git a/harbour/source/rtl/setta.prg b/harbour/source/rtl/setta.prg index 1d032e19fc..c2c0711df8 100644 --- a/harbour/source/rtl/setta.prg +++ b/harbour/source/rtl/setta.prg @@ -37,7 +37,7 @@ * $FUNCNAME$ * SETTYPEAHEAD() * $CATEGORY$ - * Enviroment + * Environment * $ONELINER$ * Sets the typeahead buffer to given size. * $SYNTAX$ diff --git a/harbour/source/rtl/text.prg b/harbour/source/rtl/text.prg index fb8e47c882..20eeb4f71f 100644 --- a/harbour/source/rtl/text.prg +++ b/harbour/source/rtl/text.prg @@ -58,8 +58,7 @@ STATIC s_cOldExtraFile * $CATEGORY$ * Internal * $ONELINER$ - * Redirect console output to printer or file and save old settings - * + * Redirect console output to printer or file and save old settings * $SYNTAX$ * __TextSave( ) --> NIL * $ARGUMENTS$ diff --git a/harbour/source/rtl/xsavescr.prg b/harbour/source/rtl/xsavescr.prg index 7a20901c79..30ea8d68d1 100644 --- a/harbour/source/rtl/xsavescr.prg +++ b/harbour/source/rtl/xsavescr.prg @@ -99,7 +99,6 @@ STATIC s_cScrn * $ONELINER$ * Save whole screen image and coordinate to an internal buffer * $SYNTAX$ - * * SAVE SCREEN * $ARGUMENTS$ * none. @@ -130,7 +129,7 @@ STATIC s_cScrn * platforms. * $FILES$ * $SEEALSO$ - * comm.ngo:'RESTORE SCREEN' RESTSCREEN() SAVESCREEN() + * comm.ngo:'RESTORE SCREEN' datai.ngo:__XRESTSCREEN() datai.ngo:__XSAVESCREEN() * $END$ */ @@ -149,10 +148,6 @@ PROCEDURE __XSAVESCREEN() * Restore screen image and coordinate from an internal buffer * $SYNTAX$ * __XRestScreen() --> NIL - * - * or - * - * RESTORE SCREEN * $ARGUMENTS$ * none. * $RETURNS$ @@ -184,9 +179,10 @@ PROCEDURE __XSAVESCREEN() * platforms. * $FILES$ * $SEEALSO$ - * RESTSCREEN() comm.ngo:'SAVE SCREEN' SAVESCREEN() + * datai.ngo:__XRESTSCREEN() comm.ngo:'SAVE SCREEN' datai.ngo:__XSAVESCREEN() * $END$ */ + /* $DOC$ * $FUNCNAME$ * RESTORE SCREEN @@ -225,7 +221,7 @@ PROCEDURE __XSAVESCREEN() * platforms. * $FILES$ * $SEEALSO$ - * RESTSCREEN() comm.ngo:'SAVE SCREEN' SAVESCREEN() + * datai.ngo:__XRESTSCREEN() comm.ngo:'SAVE SCREEN' datai.ngo:__XSAVESCREEN() * $END$ */