diff --git a/harbour/source/rdd/dbcmd.c b/harbour/source/rdd/dbcmd.c index 3994a94f51..966a424664 100644 --- a/harbour/source/rdd/dbcmd.c +++ b/harbour/source/rdd/dbcmd.c @@ -1386,6 +1386,54 @@ void hb_rddShutDown( void ) /* * -- HARBOUR FUNCTIONS -- */ +/* $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$ + */ HARBOUR HB_AFIELDS( void ) { @@ -1458,6 +1506,44 @@ HARBOUR HB_AFIELDS( void ) hb_itemRelease( pItem ); hb_retni( uiArrayLen ); } +/* $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.This function does not differ from the Clipper + * function DBF(), with is a strictly a compatibility function + * $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$ + */ HARBOUR HB_ALIAS( void ) { @@ -1492,8 +1578,9 @@ HARBOUR HB_ALIAS( void ) * $FUNCNAME$ * DBEVAL() * $CATEGORY$ + * DATA BASE * $ONELINER$ - * Performs a code block operation on the current data base + * Performs a code block operation on the current DATA BASE * $SYNTAX$ * DBEVAL( , [], [], [], [], [] ) --> NIL * $ARGUMENTS$ @@ -1506,7 +1593,7 @@ HARBOUR HB_ALIAS( void ) * $RETURNS$ * NIL * $DESCRIPTION$ - * Performs a code block operation on the current data base + * Performs a code block operation on the current DATA BASE * $EXAMPLES$ * FUNCTION Main() * LOCAL nCount @@ -1598,6 +1685,42 @@ HARBOUR HB_DBEVAL( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBEVAL" ); } +/* $DOC$ + * $FUNCNAME$ + * DBF() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Returns the alias name of a work area + * $SYNTAX$ + * Dbf() --> + * $ARGUMENTS$ + * + * $RETURNS$ + * Name of alias + * $DESCRIPTION$ + * This function returns the same alias name of + * the currently selected work area. + * This function is the same as Alias() + * $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$ + * ALIAS() is fully CA-Clipper compliant. + * $SEEALSO$ + * $END$ + */ HARBOUR HB_DBF( void ) { @@ -1622,6 +1745,54 @@ HARBOUR HB_DBF( void ) } hb_retc( "" ); } +/* $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 Test + * + * qOut( BOF(),Recno()) + * qOut(Test->(BOF()),Test->(Recno())) + * skip -1 + * qOut( BOF(),Recno()) + * qOut(Test->(BOF()),Test->(Recno())) + * dbGoBottom() + * qOut( EOF(),Recno()) + * qOut(Test->(BOF()),Test->(Recno()),Test->(BOF())) + * skip + * Test->(dbGoBottom(),LastRec()) + * qOut( EOF(),Recno()) + * Test->(qOut(BOF(),Recno(),BOF())) + * + * RETURN NIL + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * BOF() is fully CA-Clipper compliant. + * $SEEALSO$ + * EOF() FOUND() LASTREC() + * $END$ + */ HARBOUR HB_BOF( void ) { @@ -1631,6 +1802,54 @@ HARBOUR HB_BOF( void ) SELF_BOF( ( AREAP ) pCurrArea->pArea, &bBof ); hb_retl( bBof ); } +/* $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$ + */ HARBOUR HB_DBAPPEND( void ) { @@ -1646,6 +1865,44 @@ HARBOUR HB_DBAPPEND( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBAPPEND" ); } +/* $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$ + */ HARBOUR HB_DBCLEARFILTER( void ) { @@ -1654,11 +1911,88 @@ HARBOUR HB_DBCLEARFILTER( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBCLEARFILTER" ); } +/* $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$ + */ HARBOUR HB_DBCLOSEALL( void ) { hb_rddCloseAll(); } +/* $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$ + */ HARBOUR HB_DBCLOSEAREA( void ) { @@ -1686,6 +2020,73 @@ HARBOUR HB_DBCLOSEAREA( void ) hb_xfree( pCurrArea ); pCurrArea = NULL; } +/* $DOC$ + * $FUNCNAME$ + * DBCOMMIT() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Flush pending updates + * $SYNTAX$ + * DBCOMMIT() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBCOMMIT() always returns NIL. + * $DESCRIPTION$ + * DBCOMMIT() causes all updates to the current work area to be written to + * disk. All updated database and index buffers are written to DOS and a + * DOS COMMIT request is issued for the database (.dbf) file and any index + * files associated with the work area. + * + * DBCOMMIT() performs the same function as the standard COMMIT command + * except that it operates only on the current work area. For more + * information, refer to the COMMIT command. + * + * Notes + * + * ^CFE Network environment: DBCOMMIT() makes database updates visible + * to other processes. To insure data integrity, issue DBCOMMIT() + * before an UNLOCK operation. For more information, refer to the + * Network Programming chapter in the Programming and Utilities guide. + * + * ^CFE DBCOMMIT() uses DOS interrupt 21h function 68h to perform the + * solid-disk write. It is up to the network operating system to + * properly implement this request. Check with the network vendor to + * see if this is supported. + * + * $EXAMPLES$ + * In this example, COMMIT is used to force a write to disk after + * a series of memory variables are assigned to field variables: + * + * USE Sales EXCLUSIVE NEW + * MEMVAR->Name := Sales->Name + * MEMVAR->Amount := Sales->Amount + * // + * @ 10, 10 GET MEMVAR->Name + * @ 11, 10 GET MEMVAR->Amount + * READ + * // + * IF UPDATED() + * APPEND BLANK + * REPLACE Sales->Name WITH MEMVAR->Name + * REPLACE Sales->Amount WITH MEMVAR->Amount + * Sales->( DBCOMMIT() ) + * ENDIF + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * + * $SEEALSO$ + * DBCLOSEALL() DBCOMMITALL() DBUNLOCK() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBCOMMIT( void ) { @@ -1694,6 +2095,75 @@ HARBOUR HB_DBCOMMIT( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBCOMMIT" ); } +/* $DOC$ + * $FUNCNAME$ + * DBCOMMITALL() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Flush pending updates in all work areas + * $SYNTAX$ + * DBCOMMIT() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBCOMMIT() always returns NIL. + * $DESCRIPTION$ + DBCOMMITALL() causes all pending updates to all work areas to be written + to disk. It is equivalent to calling DBCOMMIT() for every occupied work + area. + + For more information, refer to DBCOMMIT(). + + Notes + ^CFE DBCOMMITALL() uses DOS interrupt 21h function 68h to perform + the solid-disk write. It is up to the network operating system to + properly implement this request. Check with the network vendor to + see if this is supported. + * + * $EXAMPLES$ + + ^CFE The following example writes all pending updates to disk: + + cLast := "Winston" + // + DBUSEAREA( .T., "DBFNTX", "Sales", "Sales", .T. ) + DBSETINDEX( "SALEFNAM" ) + DBSETINDEX( "SALELNAM" ) + // + DBUSEAREA( .T., "DBFNTX", "Colls", "Colls", .T. ) + DBSETINDEX( "COLLFNAM" ) + DBSETINDEX( "COLLLNAM" ) + + DBSELECTAREA( "Sales" ) // select "Sales" work area + + IF ( Sales->(DBSEEK(cLast)) ) + IF Sales->( DELETED() ) .AND. Sales( RLOCK() ) + Sales->( DBRECALL() ) + ? "Deleted record has been recalled." + ENDIF + ELSE + ? "Not found" + ENDIF + // + // processing done, write updates to disk and close + DBCOMMITALL() + DBCLOSEALL() + QUIT + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + + * $SEEALSO$ + * DBCLOSEALL() DBCOMMIT() DBUNLOCK() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBCOMMITALL( void ) { @@ -1707,6 +2177,82 @@ HARBOUR HB_DBCOMMITALL( void ) } } +/* $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 + + ^CFE 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$ + ^CFE 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 + + ^CFE 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$ + */ + + HARBOUR HB___DBCONTINUE() { BOOL bEof; @@ -1739,6 +2285,118 @@ HARBOUR HB___DBCONTINUE() } } +/* $DOC$ + * $FUNCNAME$ + * DBCREATE() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Create a database file from a database structure array + * $SYNTAX$ + * DBCREATE(, ,[]) --> NIL + * + * $ARGUMENTS$ + is the name of the new database file, with an optional + drive and directory, specified as a character string. If specified + without an extension (.dbf) is assumed. + + is an array that contains the structure of as + a series of subarrays, one per field. Each subarray contains the + definition of each field's attributes and has the following structure: + + Field Definition Subarray + 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + Position Metasymbol Dbstruct.ch + 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + 1 cName DBS_NAME + 2 cType DBS_TYPE + 3 nLength DBS_LEN + 4 nDecimals DBS_DEC + 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + + specifies the replaceable database driver (RDD) to use to + process the current work area. is name of the RDD specified + as a character expression. If you specify as a literal value, + you must enclose it in quotes. + * + * $RETURNS$ + * DBCREATE() always returns NIL. + * $DESCRIPTION$ + DBCREATE() is a database function that creates a database file from an + array containing the structure of the file. You may create the array + programmatically or by using DBSTRUCT(). DBCREATE() is similar to the + CREATE FROM command which creates a new database file structure from a + structure extended file. Use CREATE or COPY STRUCTURE EXTENDED commands + to create a structure extended file. + + Before using DBCREATE(), you must first create the array and + fill it with the field definition arrays according to the structure in + Field Definition Subarray table (above). There are some specific rules + for creating a field definition array, including: + + ^CFE Specify all field attributes with a value of the proper data + type for the attribute. The decimals attribute must be + specified--even for non-numeric fields. If the field does not have a + decimals attribute, specify zero. + + ^CFE Specify the type attribute using the first letter of the data + type as a minimum. Use longer and more descriptive terms for + readability. For example, both "C" and "Character" can be specified + as the type attribute for character fields. + + ^CFE In CA-Clipper, character fields contain up to 64,000 + characters. Unlike the CREATE FROM command, DBCREATE() does not use + the decimals attribute to specify the high-order part of the field + length. Specify the field length directly, regardless of its + magnitude. + + To make references to the various elements of the field definition + subarray more readable, the header file called Dbstruct.ch is supplied + which contains the #defines to assign a name to the array position for + each field attribute. It is located in \CLIPPER5\INCLUDE. + * + * $EXAMPLES$ + This example creates an empty array and then adds field + definition subarrays using the AADD() function before creating + People.dbf. You might use this technique to add field definitions to + your structure array dynamically: + + aDbf := {} + AADD(aDbf, { "Name", "C", 25, 0 }) + AADD(aDbf, { "Address", "C", 1024, 0 }) + AADD(aDbf, { "Phone", "N", 13, 0 }) + // + DBCREATE("People", aDbf) + + ^CFE This example performs the same types of actions but declares + the structure array as a two-dimensional array, and then uses + subscript addressing to specify the field definitions. It will be + created using the DBFMDX RDD: + + #include "Dbstruct.ch" + // + LOCAL aDbf[1][4] + aDbf[1][ DBS_NAME ] := "Name" + aDbf[1][ DBS_TYPE ] := "Character" + aDbf[1][ DBS_LEN ] := 25 + aDbf[1][ DBS_DEC ] := 0 + // + DBCREATE("Name", aDbf, "DBFMDX") + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + + * + * $SEEALSO$ + * AFIELDS() DBSTRUCT() + * $INCLUDE$ + * "Dbstruct.ch" + * $END$ + */ + HARBOUR HB_DBCREATE( void ) { char * szDriver, * szFileName; @@ -2014,6 +2672,72 @@ HARBOUR HB_DBCREATE( void ) ( ( AREAP ) pCurrArea->pArea )->lpExtendInfo->ulRecCount = ulRecCount; } } +/* $DOC$ + * $FUNCNAME$ + * DBDELETE() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Mark a record for deletion + * $SYNTAX$ + * DBDELETE() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBDELETE() always returns NIL. + * $DESCRIPTION$ + DBDELETE() marks the current record as deleted. Records marked for + deletion can be filtered using SET DELETED or removed from the file + using the PACK command. + + DBDELETE() performs the same function as the standard DELETE command + with a scope of the current record. For more information, refer to the + DELETE command. + + Notes + + ^CFE Logical records: If the global _SET_DELETED status is true + (.T.), deleted records are not logically visible. That is, database + operations which operate on logical records will not consider records + marked for deletion. Note, however, that if _SET_DELETED is true + (.T.) when the current record is marked for deletion, the record + remains visible until it is no longer the current record. + + ^CFE Network environment: For a shared database on a network, + DBDELETE() requires the current record to be locked. For more + information, refer to the Network Programming chapter of the + Programming and Utilities guide. + * + * $EXAMPLES$ + ^CFE The following example deletes a record after a successful + record lock: + + cLast := "Winston" + DBUSEAREA( .T., "DBFNTX", "Sales", "Sales", .T. ) + DBSETINDEX( "LASTNAME" ) + // + IF ( Sales->(DBSEEK(cLast)) ) + IF Sales->( RLOCK() ) + Sales->( DBDELETE() ) + ? "Record deleted: ", Sales( DELETED() ) + ELSE + ? "Unable to lock record..." + ENDIF + ELSE + ? "Not found" + ENDIF + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBRECALL() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBDELETE( void ) { @@ -2022,6 +2746,86 @@ HARBOUR HB_DBDELETE( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBDELETE" ); } +/* $DOC$ + * $FUNCNAME$ + * DBFILTER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the current filter expression as a character string + * $SYNTAX$ + * DBFILTER() --> cFilter + * $ARGUMENTS$ + * + * $RETURNS$ + * DBFILTER() returns the filter condition defined in the current work area + * as a character string. If no FILTER has been SET, DBFILTER() returns a + * null string (""). + * + * $DESCRIPTION$ + * DBFILTER() is a database function used to save and reexecute an active + * filter by returning the filter expression as a character string that can + * be later recompiled and executed using the macro operator (&). This + * function operates like the DBRELATION() and DBRSELECT() functions which + * save and reexecute the linking expression of a relation within a work + * area. + * + * Since each work area can have an active filter, DBFILTER() can return + * the filter expression of any work area. This is done by referring to + * DBFILTER() within an aliased expression as demonstrated below. + * + * Notes + * + * ^CFE Declared variables: A character string returned by DBFILTER() + * may not operate correctly when recompiled and executed using the + * macro operator (&) if the original filter expression contained + * references to local or static variables, or otherwise depended on + * compile-time declarations. + * + * $EXAMPLES$ + * ^CFE This example opens two database files, sets two filters, then + * displays the filter expressions for both work areas: + * + * USE Customer INDEX Customer NEW + * SET FILTER TO Last = "Smith" + * USE Invoices INDEX Invoices NEW + * SET FILTER TO CustId = "Smi001" + * SELECT Customer + * // + * ? DBFILTER() // Result: Last = "Smith" + * ? Invoices->(DBFILTER()) // Result: Custid = "Smi001" + * + * ^CFE This user-defined function, CreateQry(), uses DBFILTER() to + * create a memory file containing the current filter expression in the + * private variable cFilter: + * + * FUNCTION CreateQry( cQryName ) + * + * PRIVATE cFilter := DBFILTER() + * SAVE ALL LIKE cFilter TO (cQryName + ".qwy") + * RETURN NIL + * + * ^CFE You can later RESTORE a query file with this user-defined + * function, SetFilter(): + * + * FUNCTION SetFilter() + * PARAMETER cQryName + * RESTORE FROM &cQryName..qwy ADDITIVE + * SET FILTER TO &cFilter. + * RETURN NIL + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBRELATION() DBRSELECT() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBFILTER( void ) { @@ -2037,6 +2841,71 @@ HARBOUR HB_DBFILTER( void ) else hb_retc( "" ); } +/* $DOC$ + * $FUNCNAME$ + * DBGOBOTTOM() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Move to the last logical record + * $SYNTAX$ + * DBGOBOTTOM() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBGOBOTTOM() always returns NIL. + * $DESCRIPTION$ + * DBGOBOTTOM() moves to last logical record in the current work area. + * + * DBGOBOTTOM() performs the same function as the standard GO BOTTOM + * command. For more information, refer to the GO command. + * + * Notes + * + * ^CFE Logical records: DBGOBOTTOM() operates on logical records. If + * there is an active index, DBGOBOTTOM() moves to the last record in + * indexed order. If a filter is set, only records which meet the + * filter condition are considered. + * + * ^CFE Controlling order: If more than one index is active in the + * work area, the operation is performed using the controlling order as + * set by DBSETORDER() or the SET ORDER command. For more information, + * refer to the SET ORDER command. + * + * ^CFE Network environment: For a shared file on a network, moving to + * a different record may cause updates to the current record to become + * visible to other processes. + * + * $EXAMPLES$ + * ^CFE The following example uses DBGOBOTTOM() to position the record + * pointer on the last logical record: + * + * cLast := "Winston" + * DBUSEAREA( .T., "DBFNTX", "Sales", "Sales", .T. ) + * DBSETINDEX( "LASTNAME" ) + * // + * Sales->( DBGOBOTTOM() ) + * IF ( Sales->Last == "Winston" ) + * IF RLOCK() + * Sales->( DBDELETE() ) + * ? "Record deleted: ", Sales( DELETED() ) + * ELSE + * ? "Unable to lock record..." + * ENDIF + * END + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * BOF() EOF() DBSKIP() DBSEEK() DBGOTOP() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBGOBOTTOM( void ) { @@ -2045,6 +2914,64 @@ HARBOUR HB_DBGOBOTTOM( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBGOBOTTOM" ); } +/* $DOC$ + * $FUNCNAME$ + * DBGOTO() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Move to the record having the specified record number + * $SYNTAX$ + * DBGOTO() --> NIL + * $ARGUMENTS$ + * is a numeric value that specifies the record number + * of the desired record. + * + * $RETURNS$ + * DBGOTO() always returns NIL. + * $DESCRIPTION$ + * DBGOTO() moves to the record whose record number is equal to + * . If no such record exists, the work area is positioned + * to LASTREC() + 1 and both EOF() and BOF() return true (.T.). + * + * DBGOTO() performs the same function as the standard GO command. For + * more information, refer to the GO command. + * + * Notes + * + * ^CFE Logical records: DBGOTO() does not respect logical visibility. + * That is, if the specified record exists, it will become the current + * record regardless of any index or filter condition. + * + * ^CFE Network environment: For a shared file on a network, moving to + * a different record may cause updates to the current record to become + * visible to other processes. + * + * $EXAMPLES$ + * + * ^CFE 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$ + */ HARBOUR HB_DBGOTO( void ) { @@ -2062,6 +2989,64 @@ HARBOUR HB_DBGOTO( void ) else SELF_GOTOID( ( AREAP ) pCurrArea->pArea, pItem ); } +/* $DOC$ + * $FUNCNAME$ + * DBGOTOP() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Move to the first logical record + * $SYNTAX$ + * DBGOTOP() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBGOTOP() always returns NIL. + * $DESCRIPTION$ + * DBGOTOP() moves to last logical record in the current work area. + * + * DBGOTOP() performs the same function as the standard GO TOP + * command. For more information, refer to the GO command. + * + * Notes + * + * ^CFE Logical records: DBGOTOP() operates on logical records. If + * there is an active index, DBGOTOP() moves to the last record in + * indexed order. If a filter is set, only records which meet the + * filter condition are considered. + * + * ^CFE Controlling order: If more than one index is active in the + * work area, the operation is performed using the controlling order as + * set by DBSETORDER() or the SET ORDER command. For more information, + * refer to the SET ORDER command. + * + * ^CFE Network environment: For a shared file on a network, moving to + * a different record may cause updates to the current record to become + * visible to other processes. + * + * $EXAMPLES$ + * + * ^CFE This example demonstrates the typical use of DBGOTOP(): + * + * DBGOTOP() + * WHILE ( !EOF() ) + * ? FIELD->Name + * DBSKIP() + * END + * + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * BOF() EOF() DBSKIP() DBSEEK() DBGOBOTTOM() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBGOTOP( void ) { @@ -2306,6 +3291,71 @@ HARBOUR HB___DBPACK( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "__DBPACK" ); } +/* $DOC$ + * $FUNCNAME$ + * DBRECALL() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Reinstate a record marked for deletion + * $SYNTAX$ + * DBRECALL() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBRECALL() always returns NIL. + * $DESCRIPTION$ + * DBRECALL() causes the current record to be reinstated if it is marked + * for deletion. + * + * DBRECALL() performs the same function as the RECALL command. For more + * information, refer to the DELETE and RECALL commands. + * + * Notes + * + * ^CFE Logical records: Reinstating a deleted record affects the + * record's logical visibility if the global _SET_DELETED status is true + * (.T.). For more information, refer to the DBDELETE() function and + * the DELETE and RECALL commands. + * + * ^CFE Network environment: For a shared database on a network, + * DBRECALL() requires the current record to be locked. + * + * $EXAMPLES$ + * + * ^CFE The following example recalls a record if it is deleted and + * attempts to lock the record if successful: + * + * cLast := "Winston" + * DBUSEAREA( .T., "DBFNTX", "Sales", "Sales", .T. ) + * DBSETINDEX( "LASTNAME" ) + * // + * IF ( Sales->(DBSEEK(cLast)) ) + * IF Sales->( DELETED() ) + * + * IF Sales( RLOCK() ) + * Sales( DBRECALL() ) + * ? "Record recalled" + * ELSE + * ? "Unable to lock record..." + * ENDIF + * ENDIF + * ELSE + * ? "Not found" + * ENDIF + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBDELETE() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBRECALL( void ) { @@ -2314,6 +3364,74 @@ HARBOUR HB_DBRECALL( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBRECALL" ); } +/* $DOC$ + * $FUNCNAME$ + * DBRLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Lock the record at the current or specified identity + * $SYNTAX$ + * DBRLOCK([]) --> lSuccess + * $ARGUMENTS$ + * is a unique value guaranteed by the structure of the + * data file to reference a specific item in a data source (database). In + * a (.dbf) is the record number. In other data formats, + * is the unique primary key value. + * + * $RETURNS$ + * + * DBRLOCK() returns lSuccess, a logical data type that is true (.T.) if + * successful, false (.F.) if unsuccessful. + * + * $DESCRIPTION$ + * DBRLOCK() is a database function that locks the record identified by the + * value . In Xbase, is the record number. + * + * If you do not specify , all record locks are released and the + * current record is locked. If you specify , DBRLOCK() + * attempts to lock it and, if successful, adds it to the locked record + * list. + * + * $EXAMPLES$ + * ^CFE This example shows two different methods for locking multiple + * records: + * + * FUNCTION dbRLockRange( nLo, nHi ) + * + * LOCAL nRec + * FOR nRec := nLo TO nHi + * IF ! DBRLOCK( nRec ) + * DBRUNLOCK() // Failed - unlock everything + * ENDIF + * NEXT + * RETURN DBRLOCKLIST() // Return array of actual locks + * + * FUNCTION dbRLockArray( aList ) + * + * LOCAL nElement, nLen, lRet + * lRet := .T. + * nLen := LEN( aList ) + * FOR nElement := 1 TO nLen + * IF ! DBRLOCK( aList[ nElement ] ) + * DBRUNLOCK() // Failed - unlock everything + * lRet := .F. + * ENDIF + * NEXT + * RETURN DBRLOCKLIST() + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUNLOCK() DBUNLOCKALL() FLOCK() RLOCK() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBRLOCK( void ) { @@ -2331,6 +3449,56 @@ HARBOUR HB_DBRLOCK( void ) hb_retl( pLockInfo.fResult ); } +/* $DOC$ + * $FUNCNAME$ + * DBRLOCKLIST() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return an array of the current Lock List + * $SYNTAX$ + * DBRLOCKLIST() --> aRecordLocks + * $ARGUMENTS$ + * + * $RETURNS$ + * Returns an array of the locked records in the current or aliased work + * area. + * $DESCRIPTION$ + * DBRLOCKLIST() is a database function that returns a one-dimensional + * array that contains the identities of record locks active in the + * selected work area. + * + * $EXAMPLES$ + * PROCEDURE PrintCurLocks() + * + * LOCAL aList + * LOCAL nSize + * LOCAL nCount + * + * aList := DBRLOCKLIST() + * nSize := LEN( aList ) + * + * ? "Currently locked records: " + * FOR nCount := 1 TO nSize + * ?? aList[ nCount ] + * ?? SPACE( 1 ) + * NEXT + * ? + * + * RETURN + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * RLOCK() DBRLOCK() DBRUNLOCK() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBRLOCKLIST( void ) { @@ -2345,6 +3513,51 @@ HARBOUR HB_DBRLOCKLIST( void ) hb_itemReturn( pList ); hb_itemRelease( pList ); } +/* $DOC$ + * $FUNCNAME$ + * DBRUNLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Release all or specified record locks + * $SYNTAX$ + * DBRUNLOCK([]) --> NIL + * $ARGUMENTS$ + * is a unique value guaranteed by the structure of the + * data file to reference a specific item in a data source (database). In + * a (.dbf) is the record number. In other data formats, + * is the unique primary key value. + * $RETURNS$ + * DBRUNLOCK() always returns NIL. + * $DESCRIPTION$ + * DBRUNLOCK() is a database function that releases the lock on + * and removes it from the Lock List. If is not specified, all + * record locks are released. + * + * $EXAMPLES$ + * PROCEDURE dbRUnlockRange( nLo, nHi ) + * + * LOCAL nCounter + * + * // Unlock the records in the range from nLo to nHi + * FOR nCounter := nLo TO nHi + * DBRUNLOCK( nCounter ) + * NEXT + * + * RETURN + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * RLOCK() DBRLOCK() DBRLOCKLIST() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBRUNLOCK( void ) { @@ -2353,6 +3566,85 @@ HARBOUR HB_DBRUNLOCK( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBRUNLOCK" ); } +/* $DOC$ + * $FUNCNAME$ + * DBSEEK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Move to the record having the specified key value + * $SYNTAX$ + * DBSEEK(, [],[]) --> lFound + * $ARGUMENTS$ + * is a value of any type that specifies the key value + * associated with the desired record. + * + * is an optional logical value that specifies whether a + * soft seek is to be performed. This determines how the work area is + * positioned if the specified key value is not found (see below). If + * is omitted, the current global _SET_SOFTSEEK setting is + * used. + * is an optional logical value that set the current + * record position to the last record if successful + * $RETURNS$ + * DBSEEK() returns true (.T.) if the specified key value was found; + * otherwise, it returns false (.F.). + * $DESCRIPTION$ + * DBSEEK() moves to the first logical record whose key value is equal to + * . If such a record is found, it becomes the current record and + * DBSEEK() returns true (.T.). Otherwise, DBSEEK() returns false (.F.) + * and the positioning of the work area is as follows: for a normal (not + * soft) seek, the work area is positioned to LASTREC() + 1 and EOF() + * returns true (.T.); for a soft seek, the work area is positioned to the + * first record whose key value is greater than the specified key value. + * If no such record exists, the work area is positioned to LASTREC() + 1 + * and EOF() returns true (.T.). + * + * For a work area with no active indexes, DBSEEK() has no effect. + * + * DBSEEK() performs the same function as the standard SEEK command. For + * more information, refer to the SEEK command. + * + * Notes + * + * ^CFE Logical records: DBSEEK() operates on logical records. + * Records are considered in indexed order. If a filter is set, only + * records which meet the filter condition are considered. + * + * ^CFE Controlling order: If the work area has more than one active + * index, the operation is performed using the controlling order as set + * by DBSETORDER() or the SET ORDER command. For more information, + * refer to the SET ORDER command. + * + * ^CFE Network environment: For a shared file on a network, moving to + * a different record may cause updates to the current record to become + * visible to other processes. + * + * + * $EXAMPLES$ + * ^CFE In this example, DBSEEK() moves the pointer to the record in + * the database, Employee, in which the value in FIELD 밹Name� matches + * the entered value of cName: + * + * ACCEPT "Employee name: " TO cName + * IF ( Employee->(DBSEEK(cName)) ) + * Employee->(ViewRecord()) + * ELSE + * ? "Not found" + * END + * + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * DBSEEK() is not fully Compatible with CA-Clipper + * $SEEALSO$ + * DBGOBOTTOM() DBGOTOP() DBSKIP() EOF() BOF() FOUND() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBSEEK( void ) { @@ -2379,6 +3671,77 @@ HARBOUR HB_DBSEEK( void ) hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBSEEK" ); hb_retl( FALSE ); } +/* $DOC$ + * $FUNCNAME$ + * DBSELECTAREA() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Change the current work area + * $SYNTAX$ + * DBSELECTAREA( | ) --> NIL + * $ARGUMENTS$ + * is a numeric value between zero and 250, inclusive, that + * specifies the work area being selected. + * + * is a character value that specifies the alias of a + * currently occupied work area being selected. + * + * $RETURNS$ + * DBSELECTAREA() always returns NIL. + * $DESCRIPTION$ + * + * DBSELECTAREA() causes the specified work area to become the current work + * area. All subsequent database operations will apply to this work area + * unless another work area is explicitly specified for an operation. + * DBSELECTAREA() performs the same function as the standard SELECT + * command. For more information, refer to the SELECT command. + * + * Notes + * + * ^CFE Selecting zero: Selecting work area zero causes the lowest + * numbered unoccupied work area to become the current work area. + * + * ^CFE Aliased expressions: The alias operator (->) can temporarily + * select a work area while an expression is evaluated and automatically + * restore the previously selected work area afterward. For more + * information, refer to the alias operator (->). + * + * $EXAMPLES$ + * ^CFE The following example selects a work area via the alias name: + * + * cLast := "Winston" + * DBUSEAREA( .T., "DBFNTX", "Sales", "Sales", .T. ) + * DBSETINDEX( "SALEFNAM" ) + * DBSETINDEX( "SALELNAM" ) + * // + * DBUSEAREA( .T., "DBFNTX", "Colls", "Colls", .T. ) + * DBSETINDEX( "COLLFNAM" ) + * DBSETINDEX( "COLLLNAM" ) + * // + * DBSELECTAREA( "Sales" ) // select "Sales" work area + * // + * IF ( Sales->(DBSEEK(cLast)) ) + * IF Sales->( DELETED() ) .AND. Sales->( RLOCK() ) + * Sales->( DBRECALL() ) + * ? "Deleted record has been recalled." + * ENDIF + * ELSE + * ? "Not found" + * ENDIF + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUSEAREA() SELECT() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBSELECTAREA( void ) { @@ -2427,6 +3790,47 @@ HARBOUR HB_DBSELECTAREA( void ) } pCurrArea = NULL; /* Selected WorkArea is closed */ } +/* $DOC$ + * $FUNCNAME$ + * DBSETDRIVER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the default database driver and optionally set a new driver + * $SYNTAX$ + * DBSETDRIVER([]) --> cCurrentDriver + * $ARGUMENTS$ + * is an optional character value that specifies the name of + * the database driver that should be used to activate and manage new work + * areas when no driver is explicitly specified. + * $RETURNS$ + * DBSETDRIVER() returns the name of the current default driver. + * $DESCRIPTION$ + * DBSETDRIVER() sets the database driver to be used when activating new + * work areas without specifying a driver. If the specified driver is not + * available to the application, the call has no effect. DBSETDRIVER() + * returns the name of the current default driver, if any. + * + * $EXAMPLES$ + * ^CFE This example makes the "DBFNDX" driver the default driver. If + * the driver is unavailable, a message is issued: + * DBSETDRIVER("DBFNDX") + * IF ( DBSETDRIVER() <> "DBFNDX" ) + * * ? "DBFNDX driver not available" + * ENDIF + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUSEAREA() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBSETDRIVER( void ) { @@ -2462,6 +3866,69 @@ HARBOUR HB___DBSETFOUND( void ) ( ( AREAP ) pCurrArea->pArea )->fFound = hb_itemGetL( pFound ); } } +/* $DOC$ + * $FUNCNAME$ + * DBSKIP() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Move relative to the current record + * $SYNTAX$ + * DBSKIP([]) --> NIL + * $ARGUMENTS$ + * is the number of logical records to move, relative to the + * current record. A positive value means to skip forward, and a negative + * value means to skip backward. If is omitted, a value of 1 is + * assumed. + * $RETURNS$ + * DBSKIP() always returns NIL. + * $DESCRIPTION$ + * DBSKIP() moves either forward or backward relative to the current + * record. Attempting to skip forward beyond the last record positions the + * work area to LASTREC() + 1 and EOF() returns true (.T.). Attempting to + * skip backward beyond the first record positions the work area to the + * first record and BOF() returns true (.T.). + * DBSKIP() performs the same function as the standard SKIP command. For + * more information, refer to the SKIP command. + * + * Notes + * + * ^CFE Logical records: DBSKIP() operates on logical records. If + * there is an active index, records are considered in indexed order. + * If a filter is set, only records which meet the filter condition are + * considered. + * + * ^CFE Controlling order: If the work area has more than one active + * index, the skip operation is performed using the controlling order as + * set by DBSETORDER() or the SET ORDER command. For more information, + * refer to the SET ORDER command. + * + * ^CFE Network environment: For a shared file on a network, moving to + * a different record may cause updates to the current record to become + * visible to other processes. + * + * $EXAMPLES$ + * ^CFE This example demonstrates a typical use of the DBSKIP() + * function: + * + * DBGOTOP() + * DO WHILE ( !EOF() ) + * ? FIELD->Name + * DBSKIP() + * ENDDO + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * BOF() DBGOBOTTOM() DBGOTOP() DBSEEK() EOF() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBSKIP( void ) { @@ -2476,6 +3943,83 @@ HARBOUR HB_DBSKIP( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBSKIP" ); } +/* $DOC$ + * $FUNCNAME$ + * DBSETFILTER() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set a filter condition + * $SYNTAX$ + * DBSETFILTER(, []) --> NIL + * $ARGUMENTS$ + * is a code block that expresses the filter condition in + * executable form. + + * is an optional character value that expresses the + * filter condition in textual form. If is omitted, the + * DBSETFILTER() function will return an empty string for the work area. + * + * $RETURNS$ + * DBSETFILTER() always returns NIL. + * $DESCRIPTION$ + * DBSETFILTER() sets a logical filter condition for the current work area. + * When a filter is set, records which do not meet the filter condition are + * not logically visible. That is, database operations which act on + * logical records will not consider these records. + + * The filter expression supplied to DBSETFILTER() evaluates to true (.T.) + * if the current record meets the filter condition; otherwise, it should + * evaluate to false (.F.). + + * The filter expression may be a code block () or both a code + * block and equivalent text (). If both versions are + * supplied, they must express the same condition. If the text version is + * omitted, DBFILTER() will return an empty string for the work area. + + * DBSETFILTER() performs the same function as the standard SET FILTER + * command. For more information, refer to the SET FILTER command. + * + * Notes + * + * ^CFE Logical records: DBSETFILTER() affects the logical visibility + * of records (see above). + * + * ^CFE Side effects: Setting a filter condition is only guaranteed to + * restrict visibility of certain records as described above. The + * filter expression is not necessarily evaluated at any particular + * time, by any particular means, or on any particular record or series + * of records. If the filter expression relies on information external + * to the database file or work area, the effect is unpredictable. If + * the filter expression changes the state of the work area (e.g., by + * moving to a different record or changing the contents of a record), + * the effect is unpredictable. + * + * ^CFE Evaluation context: When the filter expression is evaluated, + * the associated work area is automatically selected as the current + * work area before the evaluation; the previously selected work area is + * automatically restored afterward. + + * $EXAMPLES$ + * ^CFE This example limits data access to records in which the Age + * field value is less than 40: + * + * USE Employee NEW + * DBSETFILTER( {|| Age < 40}, "Age < 40" ) + * DBGOTOP() + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBFILTER() DBCLEARFILTER() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBSETFILTER( void ) { @@ -2501,6 +4045,75 @@ HARBOUR HB_DBSETFILTER( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBSETFILTER" ); } +/* $DOC$ + * $FUNCNAME$ + * DBSTRUCT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Create an array containing the structure of a database file + * $SYNTAX$ + * DBSTRUCT() --> aStruct + * $ARGUMENTS$ + * + * $RETURNS$ + * DBSTRUCT() returns the structure of the current database file in an + * array whose length is equal to the number of fields in the database + * file. Each element of the array is a subarray containing information + * for one field. The subarrays have the following format: + + * DBSTRUCT() Return Array + * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + * Position * Metasymbol * Dbstruct.ch + * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + * 1 * * cName * * DBS_NAME + * 2 * * cType * * DBS_TYPE + * 3 * * nLength * DBS_LEN + * 4 * * nDecimals * DBS_DEC + * 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 + + * If there is no database file in USE in the current work area, DBSTRUCT() + * returns an empty array ({}). + * + * $DESCRIPTION$ + * DBSTRUCT() is a database function that operates like COPY STRUCTURE + * EXTENDED by creating an array of structure information rather than a + * database file of structure information. There is another function, + * DBCREATE(), that can create a database file from the structure array. + + * By default, DBSTRUCT() 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 below. + + * Note, a header file, Dbstruct.ch, located in \HARBOUR\INCLUDE contains + * a series of manifest constants for each field attribute. + * + * $EXAMPLES$ + * ^CFE This example opens two database files then creates an array + * containing the database structure using DBSTRUCT() within an aliased + * expression. The field names are then listed using AEVAL(): + + * #include "Dbstruct.ch" + * // + * LOCAL aStruct + * USE Customer NEW + * USE Invoices NEW + * // + * aStruct := Customer->(DBSTRUCT()) + * AEVAL( aStruct, {|aField| QOUT(aField[DBS_NAME])} ) + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * AFIELDS() + * $INCLUDE$ + * DbStruct.ch + * $END$ + */ HARBOUR HB_DBSTRUCT( void ) { @@ -2582,6 +4195,64 @@ HARBOUR HB_DBTABLEEXT( void ) hb_itemRelease( pItem ); } } +/* $DOC$ + * $FUNCNAME$ + * DBUNLOCK() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Release all locks for the current work area + * $SYNTAX$ + * DBUNLOCK() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBUNLOCK() always returns NIL. + * $DESCRIPTION$ + * DBUNLOCK() releases any record or file locks obtained by the current + * process for the current work area. DBUNLOCK() is only meaningful on a + * shared database in a network environment. + + * DBUNLOCK() performs the same function as the standard UNLOCK command. + * For more information, refer to the UNLOCK command. + + * Notes + + * ^CFE Network environment: Releasing locks may cause updates to the + * database to become visible to other processes. + * + * $EXAMPLES$ + * ^CFE The following example illustrates a basic use of the + * DBUNLOCK() function: + + * cLast := "Winston" + * USE Sales SHARED NEW VIA "DBFNTX" + * DBSETINDEX( "LASTNAME" ) + * // + * IF ( Sales->(DBSEEK(cLast)) ) + * IF Sales->( RLOCK() ) + * Sales->( DBDELETE() ) + * ? "Record deleted: ", Sales( DELETED() ) + * Sales->( DBUNLOCK() ) + * ELSE + * ? "Unable to lock record..." + * ENDIF + * ELSE + * ? "Not found" + * ENDIF + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUNLOCKALL() FLOCK() RLOCK() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBUNLOCK( void ) { @@ -2590,6 +4261,69 @@ HARBOUR HB_DBUNLOCK( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "DBUNLOCK" ); } +/* $DOC$ + * $FUNCNAME$ + * DBUNLOCKALL() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Release all locks for all work areas + * $SYNTAX$ + * DBUNLOCKALL() --> NIL + * $ARGUMENTS$ + * + * $RETURNS$ + * DBUNLOCKALL() always returns NIL. + * $DESCRIPTION$ + * DBUNLOCKALL() releases any record or file locks obtained by the current + * process for any work area. DBUNLOCKALL() is only meaningful on a shared + * database in a network environment. It is equivalent to calling + * DBUNLOCK() on every occupied work area. + + * DBUNLOCKALL() performs the same function as the UNLOCK ALL command. For + * more information, refer to the UNLOCK ALL command. + * + * $EXAMPLES$ + * ^CFE The following example marks a record for deletion if an + * RLOCK() attempt is successful, then clears all locks in all work + * areas: + + * cLast := "Winston" + * USE Sales SHARED NEW VIA "DBFNTX" + * DBSETINDEX( "SALEFNAM" ) + * DBSETINDEX( "SALELNAM" ) + * // + * USE Colls SHARED NEW VIA "DBFNTX" + * DBSETINDEX( "COLLFNAM" ) + * DBSETINDEX( "COLLLNAM" ) + * // + * DBSELECTAREA( "Sales" ) * // select "Sales" work area + * // + * IF ( Colls->(DBSEEK(cLast)) ) + * IF Colls->( DELETED() ) + * ? "Record deleted: ", Colls->( DELETED() ) + * IF Colls->( RLOCK() ) + * Colls->( DBRECALL() ) + * ? "Record recalled..." + * ENDIF + * ENDIF + * ELSE + * ? "Not found" + * DBUNLOCKALL() // remove all locks in + * ENDIF // all work areas + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBUNLOCK() FLOCK() RLOCK() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBUNLOCKALL( void ) { @@ -2602,6 +4336,88 @@ HARBOUR HB_DBUNLOCKALL( void ) pTempArea = pTempArea->pNext; } } +/* $DOC$ + * $FUNCNAME$ + * DBUSEAREA() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Use a database file in a work area + * $SYNTAX$ + * DBUSEAREA( [], [], , [], + * [], []) --> NIL + * $ARGUMENTS$ + * is an optional logical value. A value of true (.T.) + * selects the lowest numbered unoccupied work area as the current work + * area before the use operation. If is false (.F.) or omitted, + * the current work area is used; if the work area is occupied, it is + * closed first. + + * is an optional character value. If present, it specifies + * the name of the database driver which will service the work area. If + * is omitted, the current default driver is used (see note + * below). + + * specifies the name of the database (.dbf) file to be opened. + + * is an optional character value. If present, it specifies + * the alias to be associated with the work area. The alias must + * constitute a valid HARBOUR identifier. A valid may be any + * legal identifier (i.e., it must begin with an alphabetic character and + * may contain numeric or alphabetic characters and the underscore). + * Within a single application, HARBOUR will not accept duplicate + * aliases. If is omitted, a default alias is constructed from + * . + + * is an optional logical value. If present, it specifies + * whether the database (.dbf) file should be accessible to other processes + * on a network. A value of true (.T.) specifies that other processes + * should be allowed access; a value of false (.F.) specifies that the + * current process is to have exclusive access. If is omitted, + * the current global _SET_EXCLUSIVE setting determines whether shared + * access is allowed. + + * is an optional logical value that specifies whether + * updates to the work area are prohibited. A value of true (.T.) + * prohibits updates; a value of false (.F.) permits updates. A value of + * true (.T.) also permits read-only access to the specified database + * (.dbf) file. If is omitted, the default value is false + * (.F.). + * $RETURNS$ + * DBUSEAREA() always returns NIL. + * $DESCRIPTION$ + * DBUSEAREA() associates the specified database (.dbf) file with the + * current work area. + + * DBUSEAREA() performs the same function as the standard USE command. For + * more information, refer to the USE command. + + * Notes + + * ^CFE Current driver: If no driver is specified in the call to + * DBUSEAREA() the default driver is used. If more than one driver is + * available to the application, the default driver is the driver + * specified in the most recent call to DBSETDRIVER(). If DBSETDRIVER() + * has not been called, the name of the default driver is undetermined. + * + * $EXAMPLES$ + * ^CFE This example is a typical use of the DBUSEAREA() function: + + * DBUSEAREA(.T., "DBFNDX", "Employees") + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBCLOSEAREA() DBSETDRIVER() SELECT() envirom.ngo:SET() + * + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DBUSEAREA( void ) { @@ -2805,6 +4621,65 @@ HARBOUR HB___DBZAP( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "__DBZAP" ); } +/* $DOC$ + * $FUNCNAME$ + * DELETED() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the deleted status of the current record + * $SYNTAX$ + * DELETED() --> lDeleted + * $ARGUMENTS$ + * + * $RETURNS$ + * DELETED() returns true (.T.) if the current record is marked for + * deletion; otherwise, it returns false (.F.). If there is no database + * file in USE in the current work area, DELETED() returns false (.F.). + + * $DESCRIPTION$ + * DELETED() is a database function that determines if the current record + * in the active work area is marked for deletion. Since each work area + * with an open database file can have a current record, each work area has + * its own DELETED() value. + + * By default, DELETED() 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). + + * In applications, DELETED() is generally used to query the deleted status + * as a part of record processing conditions, or to display the deleted + * status as a part of screens and reports. + + * $EXAMPLES$ + * ^CFE This example uses DELETED() in the current and in an + * unselected work area: + + * USE Customer NEW + + * USE Sales NEW + * ? DELETED() // Result: .F. + * DELETE + * ? DELETED() // Result: .T. + * ? Customer->(DELETED()) // Result: .F. + + * ^CFE This example uses DELETED() to display a record's deleted + * status in screens and reports: + + * @ 1, 65 SAY IF(DELETED(), "Inactive", "Active") + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_DELETED( void ) { @@ -2815,6 +4690,94 @@ HARBOUR HB_DELETED( void ) hb_retl( bDeleted ); } +/* $DOC$ + * $FUNCNAME$ + * EOF() + * $CATEGORY$ + * DATA BASE + * $ONELINER$ + * Determine when end of file is encountered + * $SYNTAX$ + * EOF() --> + * $ARGUMENTS$ + * + * $RETURNS$ + * + * EOF() returns true (.T.) when an attempt is made to move the record + * pointer beyond the last logical record in a database file; otherwise, it + * returns false (.F.). If there is no database file open in the current + * work area, EOF() returns false (.F.). If the current database file + * contains no records, EOF() returns true (.T.). + + * $DESCRIPTION$ + + * EOF() is a database function used to test for an end of file boundary + * condition when the record pointer is moving forward through a database + * file. Any command that can move the record pointer can set EOF(). + + * The most typical application is as a part of the argument + * of a DO WHILE construct that sequentially processes records in a + * database file. Here would include a test for .NOT. EOF(), + * forcing the DO WHILE loop to terminate when EOF() returns true (.T.). + + * EOF() and FOUND() are often used interchangeably to test whether a SEEK, + * FIND, or LOCATE command failed. With these commands, however, FOUND() + * is preferred. + + * When EOF() returns true (.T.), the record pointer is positioned at + * LASTREC() + 1 regardless of whether there is an active SET FILTER or SET + * DELETED is ON. Further attempts to move the record pointer forward + * return the same result without error. Once EOF() is set to true (.T.), + * it retains its value until there is another attempt to move the record + * pointer. + + * By default, EOF() 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). + + * $EXAMPLES$ + * ^CFE This example demonstrates EOF() by deliberately moving the + * record pointer beyond the last record: + + * USE Sales + * GO BOTTOM + * ? EOF() // Result: .F. + * SKIP + * ? EOF() // Result: .T. + + * ^CFE This example uses aliased expressions to query the value of + * EOF() in unselected work areas: + + * USE Sales NEW + * USE Customer NEW + * ? Sales->(EOF()) + * ? Customer->(EOF()) + + * ^CFE This example illustrates how EOF() can be used as part of a + * condition for sequential database file operations: + + * USE Sales INDEX CustNum NEW + * DO WHILE !EOF() + * nOldCust := Sales->CustNum + * nTotalAmount := 0 + * DO WHILE nOldCust = Sales->CustNum .AND. (!EOF()) + * ? Sales->CustNum, Sales->Description, ; + * Sales->SaleAmount + * nTotalAmount += Sales->SaleAmount + * SKIP + * ENDDO + * ? "Total amount: ", nTotalAmount + * ENDDO + * $TESTS$ + * $STATUS$ + * R + * $COMPLIANCE$ + * EOF() is fully CA-Clipper compliant. + * $SEEALSO$ + * BOF() FOUND() LASTREC() + * $END$ + */ + HARBOUR HB_EOF( void ) { BOOL bEof = TRUE; @@ -2823,6 +4786,65 @@ HARBOUR HB_EOF( void ) SELF_EOF( ( AREAP ) pCurrArea->pArea, &bEof ); hb_retl( bEof ); } +/* $DOC$ + * $FUNCNAME$ + * FCOUNT() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the number of fields in the current (.dbf) file + * $SYNTAX$ + * FCOUNT() --> nFields + * $ARGUMENTS$ + * + * $RETURNS$ + * FCOUNT() returns the number of fields in the database file in the + * current work area as an integer numeric value. If there is no database + * file open, FCOUNT() returns zero. + * $DESCRIPTION$ + * FCOUNT() is a database function. It is useful in applications + * containing data-independent programs that can operate on any database + * file. These include generalized import/export and reporting programs. + * Typically, you use FCOUNT() to establish the upper limit of a FOR...NEXT + * or DO WHILE loop that processes a single field at a time. + + * By default, FCOUNT() operates on the currently selected work area. + * $EXAMPLES$ + * ^CFE This example illustrates FCOUNT(), returning the number of + * fields in the current and an unselected work area: + + * USE Sales NEW + * USE Customer NEW + * ? FCOUNT() // Result: 5 + * ? Sales->(FCOUNT()) // Result: 8 + + * ^CFE This example uses FCOUNT() to DECLARE an array with field + * information: + + * LOCAL aFields := ARRAY(FCOUNT()) + * AFIELDS(aFields) + + * ^CFE This example uses FCOUNT() as the upper boundary of a FOR loop + * that processes the list of current work area fields: + + * LOCAL nField + * USE Sales NEW + * FOR nField := 1 TO FCOUNT() + * ? FIELD(nField) + * NEXT + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FIELDNAME() misc.ngo:TYPE() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_FCOUNT( void ) { @@ -2832,6 +4854,52 @@ HARBOUR HB_FCOUNT( void ) SELF_FIELDCOUNT( ( AREAP ) pCurrArea->pArea, &uiFields ); hb_retni( uiFields ); } +/* $DOC$ + * $FUNCNAME$ + * FIELDGET() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Retrieve the value of a field variable + * $SYNTAX$ + * FIELDGET() --> ValueField + * $ARGUMENTS$ + * is the ordinal position of the field in the record + * structure for the current work area. + * $RETURNS$ + * FIELDGET() returns the value of the specified field. If does + * not correspond to the position of any field in the current database + * file, FIELDGET() returns NIL. + * $DESCRIPTION$ + * FIELDGET() is a database function that retrieves 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 retrieval of field values without use of the + * macro operator. + * $EXAMPLES$ + * ^CFE This example compares FIELDGET() to functionally equivalent + * code that uses the macro operator to retrieve the value of a field: + + * LOCAL nField := 1, FName, FVal + * USE Customer NEW + * // + * // Using macro operator + * FName := FIELD( nField ) // Get field name + * FVal := &FName // Get field value + * // Using FIELDGET() + * FVal := FIELDGET( nField ) // Get field value + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FIELDPUT() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_FIELDGET( void ) { @@ -2847,6 +4915,83 @@ HARBOUR HB_FIELDGET( void ) hb_itemReturn( pItem ); hb_itemRelease( pItem ); } +/* $DOC$ + * $FUNCNAME$ + * FIELDNAME() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return a field name from the current (.dbf) file + * $SYNTAX$ + * FIELDNAME/FIELD() --> cFieldName + * $ARGUMENTS$ + * is the position of a field in the database file + * structure. + * $RETURNS$ + * FIELDNAME() returns the name of the specified field as a character + * string. If does not correspond to an existing field in the + * current database file or if no database file is open in the current work + * area, FIELDNAME() returns a null string (""). + * $DESCRIPTION$ + * FIELDNAME() is a database function that returns a field name using an + * index to the position of the field name in the database structure. Use + * it in data-independent applications where the field name is unknown. If + * information for more than one field is required, use AFIELDS() to create + * an array of field information or COPY STRUCTURE EXTENDED to create a + * database of field information. + + * If you need additional database file structure information, use TYPE() + * and LEN(). To obtain the number of decimal places for a numeric field, + * use the following expression: + + * LEN(SUBSTR(STR(), RAT(".", ; + * STR()) + 1)) + + * By default, FIELDNAME() operates on the currently selected work area as + * shown in the example below. + * + * $EXAMPLES$ + * ^CFE These examples illustrate FIELDNAME() used with several other + * functions: + + * USE Sales + * ? FIELDNAME(1) // Result: BRANCH + * ? FCOUNT() // Result: 5 + * ? LEN(FIELDNAME(0)) // Result: 0 + * ? LEN(FIELDNAME(40)) // Result: 0 + + * ^CFE This example uses FIELDNAME() to list the name and type of + * each field in Customer.dbf: + + * USE Customer NEW + * FOR nField := 1 TO FCOUNT() + * ? PADR(FIELDNAME(nField), 10),; + * VALTYPE(&(FIELDNAME(nField))) + * NEXT + + * ^CFE This example accesses fields in unselected work areas using + * aliased expressions: + + * USE Sales NEW + * USE Customer NEW + * USE Invoices NEW + * // + * ? Sales->(FIELDNAME(1)) // Result: SALENUM + * ? Customer->(FIELDNAME(1)) // Result: CUSTNUM + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * DBSTRUCT() FCOUNT() LEN() misc.ngo:VALTYPE() + * + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_FIELDNAME( void ) { @@ -2871,6 +5016,58 @@ HARBOUR HB_FIELDNAME( void ) } hb_retc( "" ); } +/* $DOC$ + * $FUNCNAME$ + * FIELDPOS() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the position of a field in a work area + * $SYNTAX$ + * FIELDPOS() --> nFieldPos + * $ARGUMENTS$ + * is the name of a field in the current or specified work + * area. + * $RETURNS$ + * FIELDPOS() returns the position of the specified field within the list + * of fields associated with the current or specified work area. If the + * current work area has no field with the specified name, FIELDPOS() + * returns zero. + * $DESCRIPTION$ + * FIELDPOS() is a database function that is the inverse of the FIELDNAME() + * function. FIELDPOS() is most often used with the FIELDPUT() and + * FIELDGET() functions. + + * FIELDPOS() return the names of fields in any unselected work area by + * referring to the function using an aliased expression. See the example + * below. + * $EXAMPLES$ + * ^CFE This example demonstrates a typical specification of the + * FIELDPOS() function: + + * USE Customer NEW + * ? FIELDPOS("Name") * * * * // Result: 1 + * ? FIELDGET(FIELDPOS("Name")) * * // Result: Kate + + * ^CFE This example uses FIELDPOS() to return the position of a + * specified field in a unselected work area: + + * USE Customer NEW + * USE Invoices NEW + * ? Customer->(FIELDPOS("Name")) * // Result: 1 + * ? Customer->(FIELDGET(FIELDPOS("Name"))) // Result: Kate + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * FIELDGET() FIELDPUT() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_FIELDPOS( void ) { @@ -2897,6 +5094,54 @@ HARBOUR HB_FIELDPOS( void ) } hb_retni( 0 ); } +/* $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$ + * ^CFE 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$ + */ HARBOUR HB_FIELDPUT( void ) { @@ -2915,6 +5160,100 @@ HARBOUR HB_FIELDPUT( void ) } hb_ret(); } +/* $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 + * + * ^CFE 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$ + * ^CFE 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 + * + * ^CFE 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$ + */ HARBOUR HB_FLOCK( void ) { @@ -2932,6 +5271,94 @@ HARBOUR HB_FLOCK( void ) hb_retl( pLockInfo.fResult ); } +/* $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$ + * ^CFE 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. + * + * ^CFE 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()) + * + * ^CFE 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$ + */ HARBOUR HB_FOUND( void ) { @@ -2941,6 +5368,59 @@ HARBOUR HB_FOUND( void ) SELF_FOUND( ( AREAP ) pCurrArea->pArea, &bFound ); hb_retl( bFound ); } +/* $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$ + ^CFE This example determines the header size of the Sales.dbf: + + USE Sales NEW + ? HEADER() // Result: 258 + + ^CFE 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$ + */ HARBOUR HB_HEADER( void ) { @@ -2956,6 +5436,62 @@ HARBOUR HB_HEADER( void ) hb_itemRelease( pRecSize ); } } +/* $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$ + ^CFE 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 + + ^CFE 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$ + */ HARBOUR HB_INDEXORD( void ) { @@ -2971,6 +5507,59 @@ HARBOUR HB_INDEXORD( void ) else hb_retni( 0 ); } +/* $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$ + ^CFE 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 + + ^CFE 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$ + */ HARBOUR HB_LASTREC( void ) { @@ -2993,6 +5582,61 @@ HARBOUR HB_LOCK( void ) hb_retl( pLockInfo.fResult ); } +/* $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$ + ^CFE 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 + + ^CFE 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$ + */ HARBOUR HB_LUPDATE( void ) { @@ -3001,6 +5645,73 @@ HARBOUR HB_LUPDATE( void ) else SELF_INFO( ( AREAP ) pCurrArea->pArea, DBI_LASTUPDATE, &hb_stack.Return ); } +/* $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$ + ^CFE 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$ + */ HARBOUR HB_NETERR( void ) { @@ -3009,6 +5720,43 @@ HARBOUR HB_NETERR( void ) hb_retl( bNetError ); } +/* $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$ + */ HARBOUR HB_ORDBAGEXT( void ) { @@ -3060,6 +5808,62 @@ HARBOUR HB_ORDBAGEXT( void ) hb_itemRelease( pInfo.itmResult ); } } +/* $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$ + ^CFE 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 + + + ^CFE 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$ + */ HARBOUR HB_ORDBAGNAME( void ) { @@ -3083,6 +5887,35 @@ HARBOUR HB_ORDBAGNAME( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDBAGNAME" ); } +/* $DOC$ + * $FUNCNAME$ + * ORDCONDSET() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Set the Condition and scope for an order + * $SYNTAX$ + * + * $ARGUMENTS$ + * + * $RETURNS$ + * + * $DESCRIPTION$ + * + * $EXAMPLES$ + * + * $TESTS$ + * + * $STATUS$ + * S + * $COMPLIANCE$ + * ORDCONDSET() is CA-CLIPPER 5.3 Compilant + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ORDCONDSET( void ) { @@ -3150,6 +5983,112 @@ HARBOUR HB_ORDCONDSET( void ) else hb_retl( FALSE ); } +/* $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$ + ^CFE The following example demonstrates ORDCREATE() with the DBFNDX + driver: + + USE Customer VIA "DBFNDX" NEW + ORDCREATE( "CuAcct",, "Customer->Acct" ) + + + ^CFE The following example demonstrates ORDCREATE() with the + default DBFNTX driver: + + USE Customer VIA "DBFNTX" NEW + ORDCREATE( "CuAcct", "CuAcct", "Customer->Acct", ; + {|| Customer->Acct } ) + + ^CFE The following example demonstrates ORDCREATE() with the FoxPro + driver, DBFCDX: + + USE Customer VIA "DBFCDX" NEW + ORDCREATE( "Customer", "CuAcct", "Customer->Acct" ) + + ^CFE 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$ + */ HARBOUR HB_ORDCREATE( void ) { @@ -3177,6 +6116,57 @@ HARBOUR HB_ORDCREATE( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDCREATE" ); } +/* $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$ + ^CFE 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$ + */ HARBOUR HB_ORDDESTROY( void ) { @@ -3191,6 +6181,61 @@ HARBOUR HB_ORDDESTROY( void ) SELF_ORDDESTROY( ( AREAP ) pCurrArea->pArea, &pOrderInfo ); } } +/* $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$ + ^CFE 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$ + */ HARBOUR HB_ORDFOR( void ) { @@ -3215,6 +6260,64 @@ HARBOUR HB_ORDFOR( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDFOR" ); } +/* $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$ + ^CFE 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$ + */ HARBOUR HB_ORDKEY( void ) { @@ -3239,6 +6342,75 @@ HARBOUR HB_ORDKEY( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDKEY" ); } +/* $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$ + ^CFE 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$ + */ HARBOUR HB_ORDLISTADD( void ) { @@ -3258,6 +6430,45 @@ HARBOUR HB_ORDLISTADD( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDLISTADD" ); } +/* $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$ + */ HARBOUR HB_ORDLISTCLEAR( void ) { @@ -3266,6 +6477,46 @@ HARBOUR HB_ORDLISTCLEAR( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDLISTCLEAR" ); } +/* $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$ + */ HARBOUR HB_ORDLISTREBUILD( void ) { @@ -3274,6 +6525,67 @@ HARBOUR HB_ORDLISTREBUILD( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDLISTCLEAR" ); } +/* $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$ + ^CFE 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 + + ^CFE 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$ + */ HARBOUR HB_ORDNAME( void ) { @@ -3296,6 +6608,59 @@ HARBOUR HB_ORDNAME( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDNAME" ); } +/* $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$ + */ HARBOUR HB_ORDNUMBER( void ) { @@ -3318,6 +6683,68 @@ HARBOUR HB_ORDNUMBER( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDNUMBER" ); } +/* $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$ + */ HARBOUR HB_ORDSETFOCUS( void ) { @@ -3337,6 +6764,80 @@ HARBOUR HB_ORDSETFOCUS( void ) else hb_errRT_DBCMD( EG_NOTABLE, 2001, NULL, "ORDSETFOCUS" ); } +/* $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$ + ^CFE 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" } + + ^CFE 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$ + */ HARBOUR HB_RDDLIST( void ) { @@ -3357,6 +6858,45 @@ HARBOUR HB_RDDLIST( void ) } hb_itemRelease( pName ); } +/* $DOC$ + * $FUNCNAME$ + * RDDNAME() + * $CATEGORY$ + * Data Base + * $ONELINER$ + * Return the name of the RDD active in the current or specified work area + * $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$ + */ HARBOUR HB_RDDNAME( void ) { @@ -3399,6 +6939,51 @@ HARBOUR HB_RDDREGISTER( void ) hb_errInternal( 9002, "", "", "" ); } } +/* $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$ + */ HARBOUR HB_RDDSETDEFAULT( void ) { @@ -3423,6 +7008,59 @@ HARBOUR HB_RDDSETDEFAULT( void ) strcpy( szDefDriver, szNewDriver ); } } +/* $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$ + ^CFE 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 + + ^CFE 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$ + */ HARBOUR HB_RECCOUNT( void ) { @@ -3435,6 +7073,52 @@ HARBOUR HB_RECCOUNT( void ) } hb_retnl( ulRecCount ); } +/* $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$ + */ HARBOUR HB_RECNO( void ) { @@ -3446,6 +7130,62 @@ HARBOUR HB_RECNO( void ) hb_itemReturn( pRecNo ); hb_itemRelease( pRecNo ); } +/* $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$ + ^CFE The following user-defined function, DbfSize(), uses RECSIZE() + to calculate the size of the current database file: + + FUNCTION DbfSize + RETURN ((RECSIZE() * LASTREC()) + HEADER() + 1) + + ^CFE 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$ + */ HARBOUR HB_RECSIZE( void ) { @@ -3461,6 +7201,98 @@ HARBOUR HB_RECSIZE( void ) hb_itemRelease( pRecSize ); } } +/* $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: + + ^CFE @...GET + + ^CFE DELETE (single record) + + ^CFE RECALL (single record) + + ^CFE REPLACE (single record) + + Refer to the Network Programming chapter in the Programming and + Utilities guide for more information. + + Notes + + ^CFE 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$ + ^CFE 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 + + ^CFE 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$ + */ HARBOUR HB_RLOCK( void ) { @@ -3482,6 +7314,57 @@ HARBOUR HB_RLOCK( void ) hb_retl( pLockInfo.fResult ); } +/* $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$ + ^CFE This example uses SELECT() to determine which work area + USE...NEW selected: + + USE Sales NEW + SELECT 1 + ? SELECT("Sales") // Result: 4 + + ^CFE 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$ + */ HARBOUR HB_SELECT( void ) { @@ -3498,6 +7381,45 @@ HARBOUR HB_SELECT( void ) else hb_retni( uiCurrArea ); } +/* $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$ + ^CFE 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$ + */ HARBOUR HB_USED( void ) { @@ -3509,6 +7431,51 @@ HARBOUR HB_USED( void ) required in the RDDSYS INIT function, since it's not guaranteed that the RDD is already registered at that point. */ +/* $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$ + HARBOUR HB___RDDSETDEFAULT( void ) { char * szNewDriver; diff --git a/harbour/source/rtl/achoice.prg b/harbour/source/rtl/achoice.prg index e14f687836..6ef9e49a5d 100644 --- a/harbour/source/rtl/achoice.prg +++ b/harbour/source/rtl/achoice.prg @@ -21,6 +21,8 @@ /* $DOC$ * $FUNCNAME$ * ACHOICE() + * $CATEGORY$ + * Array * * $ONELINER$ * Allows selection of an element from an array @@ -34,11 +36,11 @@ * []) --> 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 + * 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 @@ -57,16 +59,16 @@ * 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 + * bUserBlock - a codeblock to be called which may * effect 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 + * nInitialItem - the number of the element to be highlighted as * the current item when the array is initally * displayed. 1 origin. Default 1. - * nWindowRow - the number of the window row on which the initial + * nWindowRow - the number of the window row on which the initial * item is to be displayed. 0 origin. Default 0. * * $RETURNS$ @@ -89,8 +91,7 @@ * ENDIF * * $SEEALSO$ - * ACHOICE() - as supplied in Clipper - * + * * $END$ */ diff --git a/harbour/source/rtl/adir.prg b/harbour/source/rtl/adir.prg index 4d8d164648..270e450f32 100644 --- a/harbour/source/rtl/adir.prg +++ b/harbour/source/rtl/adir.prg @@ -49,7 +49,7 @@ /* $DOC$ * $FUNCNAME$ - * ADIR()* + * ADIR() * $CATEGORY$ * Array * $ONELINER$ @@ -117,8 +117,9 @@ * $COMPLIANCE$ * is going to be fill with long file name and not necessarily * the 8.3 uppercase name. + * * $SEEALSO$ - * ARRAY(), DIRECTORY(), SET DEFAULT + * ARRAY() DIRECTORY() 'SET DEFAULT' * $END$ */ diff --git a/harbour/source/rtl/alert.prg b/harbour/source/rtl/alert.prg index 601974d11c..fa5e505aed 100644 --- a/harbour/source/rtl/alert.prg +++ b/harbour/source/rtl/alert.prg @@ -134,7 +134,7 @@ STATIC s_lNoAlert := NIL * * is an Harbour extension. * $SEEALSO$ - * @...PROMPT, MENU TO, STDOUT(), __NONOALERT() + * 'comm.ngo:@...PROMPT' 'comm.ngo:MENU TO' STDOUT() __NONOALERT() * $END$ */ diff --git a/harbour/source/rtl/arrays.c b/harbour/source/rtl/arrays.c index 301c8e4a61..12819a6eb7 100644 --- a/harbour/source/rtl/arrays.c +++ b/harbour/source/rtl/arrays.c @@ -786,6 +786,63 @@ static void hb_arrayNewRagged( PHB_ITEM pArray, int iDimension ) hb_arrayNewRagged( hb_arrayGetItemPtr( pArray, ulElements-- ), iDimension ); } } +/* $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. + The maximum number of elements in a dimension is 4096. Arrays in + HARBOUR can have an unlimited number of dimensions. + * + * $RETURNS$ + * ARRAY() returns an array of specified dimensions. + * $DESCRIPTION$ + ARRAY() is an array function that returns an uninitialized array with + the specified number of elements and dimensions. If more than one + argument is specified, a multidimensional array is created + with the number of dimensions equal to the number of + arguments specified. Any that is itself an array creates a + nested array. + + In HARBOUR, there are several ways to create an array. You can + declare an array using a declaration statement such as LOCAL or STATIC; + you can create an array using a PRIVATE or PUBLIC statement; you can + assign a literal array to an existing variable; or you can use the + ARRAY() function. ARRAY() has the advantage that it can create arrays + within expressions or code blocks. + * + * $EXAMPLES$ + * + This example creates a one-dimensional array of five elements + using the ARRAY() function, and then shows the equivalent action by + assigning a literal array of NIL values: + + aArray := ARRAY(5) + aArray := { NIL, NIL, NIL, NIL, NIL } + + This example shows three different statements which create the + same multidimensional array: + + aArray := ARRAY(3, 2) + aArray := { {NIL, NIL}, {NIL, NIL}, {NIL, NIL} } + aArray := { ARRAY(2), ARRAY(2), ARRAY(2) } + + This example creates a nested, multidimensional array: + + aArray := ARRAY(3, {NIL,NIL}) + + * $SEEALSO$ + * AADD() ADEL() AFILL() AINS() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ARRAY( void ) { @@ -816,6 +873,65 @@ HARBOUR HB_ARRAY( void ) hb_arrayNewRagged( &hb_stack.Return, 1 ); } } +/* $DOC$ + * $FUNCNAME$ + * AADD() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Add a new element to the end of an array + * $SYNTAX$ + * AADD(, ) --> Value + * $ARGUMENTS$ + * + * is the array to add a new element to. + * + * is the value assigned to the new element. + * + * $RETURNS$ + * + * AADD() evaluates and returns its value. If is not + * specified, AADD() returns NIL. + * + * $DESCRIPTION$ + AADD() is an array function that increases the actual length of the + target array by one. The newly created array element is assigned the + value specified by . + + AADD() is used to dynamically grow an array. It is useful for building + dynamic lists or queues. A good example of this is the GetList array + used by the GET system to hold Get objects. After a READ or CLEAR GETS, + GetList becomes an empty array. Each time you execute an @...GET + command, the GET system uses AADD() to add a new element to the end of + the GetList array, and then assigns a new Get object to the new element. + + AADD() is similar to ASIZE() but only adds one element at a time; + ASIZE() can grow or shrink an array to a specified size. AADD(), + however, has the advantage that it can assign a value to the new + element, while ASIZE() cannot. AADD() may also seem similar to AINS(), + but they are different: AINS() moves elements within an array, but it + does not change the array's length. + + Note: If is another array, the new element in the target + array will contain a reference to the array specified by . + * + * $EXAMPLES$ + These examples demonstrate the effects of multiple invocations + of AADD() to an array: + + aArray := {} // Result: aArray is an empty array + AADD(aArray, 5) // Result: aArray is { 5 } + AADD(aArray, 10) // Result: aArray is { 5, 10 } + AADD(aArray, { 12, 10 }) // Result: aArray is + // { 5, 10, { 12, 10 } } + * + * $SEEALSO$ + * AINS() + * ASIZE() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_AADD( void ) { @@ -844,6 +960,54 @@ HARBOUR HB_AADD( void ) /* NOTE: CA-Cl*pper 5.3 and older will return NIL on bad parameter, 5.3a,b will throw a runtime error. [vszel] */ +/* $DOC$ + * $FUNCNAME$ + * ASIZE() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Grow or shrink an array + * $SYNTAX$ + * ASIZE(, ) --> aTarget + * $ARGUMENTS$ + is the array to grow or shrink. + + is the new size of the array. + * + * $RETURNS$ + * ASIZE() returns a reference to the target array, . + * $DESCRIPTION$ + ASIZE() is an array function that changes the actual length of the + array. The array is shortened or lengthened to match the + specified length. If the array is shortened, elements at the end of the + array are lost. If the array is lengthened, new elements are added to + the end of the array and assigned NIL. + + ASIZE() is similar to AADD() which adds a single new element to the end + of an array and optionally assigns a new value at the same time. Note + that ASIZE() is different from AINS() and ADEL(), which do not actually + change the array's length. + * + * $EXAMPLES$ + ^CFE These examples demonstrate adding new elements and deleting + existing elements: + + 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$ + * + * $SEEALSO$ + * AADD() ADEL() AFILL() AINS() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ASIZE( void ) { @@ -862,6 +1026,46 @@ HARBOUR HB_ASIZE( void ) hb_errRT_BASE( EG_ARG, 2023, NULL, "ASIZE" ); #endif } +/* $DOC$ + * $FUNCNAME$ + * ATAIL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Return the highest numbered element of an array + * $SYNTAX$ + * ATAIL() --> Element + * $ARGUMENTS$ + * is the array. + * $RETURNS$ + ATAIL() returns either a value or a reference to an array or object. + The array is not changed. + * + * $DESCRIPTION$ + ATAIL() is an array function that returns the highest numbered element + of an array. It can be used in applications as shorthand for + [LEN()] when you need to obtain the last element of an + array. + * + * $EXAMPLES$ + ^CFE The following example creates a literal array and returns that + last element of the array: + + aArray := {"a", "b", "c", "d"} + ? ATAIL(aArray) // Result: d + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ATAIL( void ) { @@ -870,6 +1074,60 @@ HARBOUR HB_ATAIL( void ) if( pArray ) hb_arrayLast( pArray, &hb_stack.Return ); } +/* $DOC$ + * $FUNCNAME$ + * AINS() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Insert a NIL element into an array + * $SYNTAX$ + * AINS(, ) --> aTarget + * $ARGUMENTS$ + is the array into which a new element will be inserted. + + is the position at which the new element will be + inserted. + * + * $RETURNS$ + * AINS() returns a reference to the target array, . + * $DESCRIPTION$ + AINS() is an array function that inserts a new element into a specified + array. The newly inserted element is NIL data type until a new value is + assigned to it. After the insertion, the last element in the array is + discarded, and all elements after the new element are shifted down one + position. + + Warning! AINS() must be used carefully with multidimensional + arrays. Multidimensional arrays in HARBOUR are implemented by + nesting arrays within other arrays. Using AINS() in a multidimensional + array discards the last element in the specified target array which, if + it is an array element, will cause one or more dimensions to be lost. + To insert a new dimension into an array, first add a new element to the + end of the array using AADD() or ASIZE() before using AINS(). + * + * $EXAMPLES$ + ^CFE This example demonstrates the effect of using AINS() on an + array: + + LOCAL aArray + aArray := { 1, 2, 3 } // Result: aArray is + // now { 1, 2, 3 } + AINS(aArray, 2) // Result: aArray is + // now { 1, NIL, 2 } + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * AADD() ACOPY() ADEL() AEVAL() AFILL() ASIZE() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_AINS( void ) { @@ -883,6 +1141,57 @@ HARBOUR HB_AINS( void ) hb_itemReturn( pArray ); /* AIns() returns the array itself */ } } +/* $DOC$ + * $FUNCNAME$ + * ADEL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Delete an array element + * $SYNTAX$ + * ADEL(, ) --> aTarget + * $ARGUMENTS$ + is the array to delete an element from. + + is the position of the target array element to delete. + * + * $RETURNS$ + * ADEL() returns a reference to the target array, . + * $DESCRIPTION$ + ADEL() is an array function that deletes an element from an array. The + contents of the specified array element is lost, and all elements from + that position to the end of the array are shifted up one element. The + last element in the array becomes NIL. + + Warning! HARBOUR implements multidimensional arrays by nesting + arrays within other arrays. If the array is a + multidimensional array, ADEL() can delete an entire subarray specified + by , causing to describe an array with a different + structure than the original. + * + * $EXAMPLES$ + ^CFE This example creates a constant array of three elements, and + then deletes the second element. The third element is moved up one + position, and the new third element is assigned a NIL: + + LOCAL aArray + aArray := { 1, 2, 3 } // Result: aArray is + // now { 1, 2, 3 } + ADEL(aArray, 2) // Result: aArray is + // now { 1, 3, NIL } + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * ACOPY() AINS() AFILL() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ADEL( void ) { @@ -896,6 +1205,68 @@ HARBOUR HB_ADEL( void ) hb_itemReturn( pArray ); /* ADel() returns the array itself */ } } +/* $DOC$ + * $FUNCNAME$ + * AFILL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Fill an array with a specified value + * $SYNTAX$ + AFILL(, , + [], []) --> aTarget + * + * $ARGUMENTS$ + is the array to fill. + + is the value to place in each array element. It can be + an expression of any valid data type. + + is the position of the first element to fill. If this + argument is omitted, the default value is one. + + is the number of elements to fill starting with element + . If this argument is omitted, elements are filled from the + starting element position to the end of the array. + * + * $RETURNS$ + * AFILL() returns a reference to . + * $DESCRIPTION$ + AFILL() is an array function that fills the specified array with a + single value of any data type (including an array, code block, or NIL) + by assigning to each array element in the specified range. + + Warning! AFILL() cannot be used to fill multidimensional arrays. + HARBOUR implements multidimensional arrays by nesting arrays within + other arrays. Using AFILL() with a multidimensional array will + overwrite subarrays used for the other dimensions of the array. + * + * $EXAMPLES$ + ^CFE This example, creates a three-element array. The array is + then filled with the logical value, (.F.). Finally, elements in + positions two and three are assigned the new value of true (.T.): + + LOCAL aLogic[3] + // Result: aLogic is { NIL, NIL, NIL } + + AFILL(aLogic, .F.) + // Result: aLogic is { .F., .F., .F. } + + AFILL(aLogic, .T., 2, 2) + // Result: aLogic is { .F., .T., .T. } + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * AADD() AEVAL() DBSTRUCT() DIRECTORY() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_AFILL( void ) { @@ -919,6 +1290,110 @@ HARBOUR HB_AFILL( void ) hb_itemReturn( pArray ); /* AFill() returns the array itself */ } } +/* $DOC$ + * $FUNCNAME$ + * ASCAN() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Scan an array for a value or until a block returns true (.T.) + * $SYNTAX$ + 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. + * + * $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.). + * + * $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. + * + * $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 + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * EVAL() AEVAL() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ASCAN( void ) { @@ -938,6 +1413,62 @@ HARBOUR HB_ASCAN( void ) else hb_retnl( 0 ); } +/* $DOC$ + * $FUNCNAME$ + * AEVAL() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Execute a code block for each element in an array + * $SYNTAX$ + 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. + * + * $RETURNS$ + AEVAL() returns a reference to . + * + * $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. + + * + * $EXAMPLES$ + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_AEVAL( void ) { @@ -959,6 +1490,70 @@ HARBOUR HB_AEVAL( void ) else hb_errRT_BASE( EG_ARG, 2017, NULL, "AEVAL" ); } +/* $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 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. + * + * $RETURNS$ + * ACOPY() returns a reference to the target array, . + * $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. + * + * $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 } + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * ACLONE() ADEL() AEVAL() AFILL() AINS() ASORT() + * $INCLUDE$ + * + * $END$ + */ HARBOUR HB_ACOPY( void ) { @@ -987,6 +1582,50 @@ HARBOUR HB_ACOPY( void ) /* NOTE: Clipper will return NIL if the parameter is not an array. [vszel] */ +/* $DOC$ + * $FUNCNAME$ + * ACLONE() + * $CATEGORY$ + * ARRAY + * $ONELINER$ + * Duplicate a nested or multidimensional array + * $SYNTAX$ + * ACLONE() --> aDuplicate + * $ARGUMENTS$ + * is the array to duplicate. + * $RETURNS$ + * ACLONE() returns a duplicate of . + * $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. + * + * $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} + * + * $TESTS$ + * + * $STATUS$ + * R + * $COMPLIANCE$ + * + * $SEEALSO$ + * ACOPY() ADEL() AINS() ASIZE() + * $INCLUDE$ + * + * $END$ + */ + HARBOUR HB_ACLONE( void ) { PHB_ITEM pSrcArray = hb_param( 1, IT_ARRAY ); diff --git a/harbour/source/rtl/asort.prg b/harbour/source/rtl/asort.prg index bd1a94ccc1..51324c7586 100644 --- a/harbour/source/rtl/asort.prg +++ b/harbour/source/rtl/asort.prg @@ -106,7 +106,7 @@ * Clipper. But this is block calling frequency and order differs from * Clipper anyway, since they use different sorting algorithm. * $SEEALSO$ - * ASCAN(), EVAL(), SORT + * ASCAN() EVAL() SORT * $END$ */ diff --git a/harbour/source/rtl/break.c b/harbour/source/rtl/break.c index 16ff1bd0ae..c16c1124a9 100644 --- a/harbour/source/rtl/break.c +++ b/harbour/source/rtl/break.c @@ -38,9 +38,9 @@ /* $DOC$ * $FUNCNAME$ - * BREAK + * BREAK() * $CATEGORY$ - * + * Error recovery * $ONELINER$ * Exits from a BEGIN SEQUENCE block * $SYNTAX$ @@ -61,7 +61,7 @@ * $COMPLIANCE$ * BREAK() is fully CA-Clipper compliant. * $SEEALSO$ - * BEGIN SEQUENCE + * 'BEGIN SEQUENCE' * $END$ */ diff --git a/harbour/source/rtl/browdb.prg b/harbour/source/rtl/browdb.prg index 47383e295f..929c4a8f22 100644 --- a/harbour/source/rtl/browdb.prg +++ b/harbour/source/rtl/browdb.prg @@ -83,7 +83,7 @@ * $COMPLIANCE$ * TBrowseDB() works exactly like CA-Clipper's TBrowseDB(). * $SEEALSO$ - * BROWSE(), TBColumn class, TBrowse class, TBrowseNew() + * BROWSE() 'TBColumn class' 'TBrowse class' TBrowseNew() * $END$ */ @@ -105,7 +105,7 @@ FUNCTION TBrowseDB( nTop, nLeft, nBottom, nRight ) * $FUNCNAME$ * dbSkipper() * $CATEGORY$ - * Databases + * Data base * $ONELINER$ * Helper function to skip a database * $SYNTAX$ @@ -139,7 +139,7 @@ FUNCTION TBrowseDB( nTop, nLeft, nBottom, nRight ) * This function is only visible if source/rtl/browdb.prg was compiled * with the HB_COMPAT_XPP flag. * $SEEALSO$ - * DBSKIP(), SKIP + * DBSKIP() SKIP * $END$ */ diff --git a/harbour/source/rtl/browse.prg b/harbour/source/rtl/browse.prg index 74d91245fe..06515fdd10 100644 --- a/harbour/source/rtl/browse.prg +++ b/harbour/source/rtl/browse.prg @@ -108,7 +108,7 @@ * $COMPLIANCE$ * * $SEEALSO$ - * DBEDIT(), TBrowse class + * DBEDIT()* 'TBrowse class' * $END$ */ diff --git a/harbour/source/rtl/console.c b/harbour/source/rtl/console.c index 7fa693702a..af1370eefb 100644 --- a/harbour/source/rtl/console.c +++ b/harbour/source/rtl/console.c @@ -182,7 +182,7 @@ char * hb_consoleGetNewLine( void ) /* $DOC$ * $FUNCNAME$ - * HB_OSNewLine + * HB_OSNEWLINE() * $CATEGORY$ * Operating System Specific * $ONELINER$ @@ -215,7 +215,7 @@ char * hb_consoleGetNewLine( void ) * $COMPLIANCE$ * This is an add-on Operating System Tool function. * $SEEALSO$ - * OS(), OUTSTD(), OUTERR() + * dos.ngo:OS() OUTSTD() OUTERR() * $END$ */ @@ -1158,7 +1158,7 @@ HARBOUR HB___ACCEPTSTR( void ) /* $DOC$ * $FUNCNAME$ - * hb_ColorIndex + * hb_ColorIndex() * $CATEGORY$ * GT * $ONELINER$ diff --git a/harbour/source/rtl/dbedit.prg b/harbour/source/rtl/dbedit.prg index c45d30bc09..95cfa29193 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() 'TBrowse class' TRANSFORM() * $END$ */ diff --git a/harbour/source/rtl/descend.c b/harbour/source/rtl/descend.c index e9a17cd0f2..ba1a3e182c 100644 --- a/harbour/source/rtl/descend.c +++ b/harbour/source/rtl/descend.c @@ -35,9 +35,9 @@ /* $DOC$ * $FUNCNAME$ - * DESCEND + * DESCEND() * $CATEGORY$ - * + * Conversion * $ONELINER$ * Inverts an expression of string, logical, date or numeric type. * $SYNTAX$ @@ -60,7 +60,7 @@ * $COMPLIANCE$ * DESCEND() is fully CA-Clipper compliant. * $SEEALSO$ - * INDEX, SEEK + * 'INDEX' 'SEEK' * $END$ */ diff --git a/harbour/source/rtl/devoutp.prg b/harbour/source/rtl/devoutp.prg index 931bbd4170..c39dded063 100644 --- a/harbour/source/rtl/devoutp.prg +++ b/harbour/source/rtl/devoutp.prg @@ -48,7 +48,7 @@ /* $DOC$ * $FUNCNAME$ - * DEVOUTPICT + * DEVOUTPICT() * $CATEGORY$ * Terminal * $ONELINER$ @@ -63,8 +63,8 @@ * $RETURNS$ * NIL * $DESCRIPTION$ - * Outputs any expression using a picture transformation instead of using - * the default transformation for the type of expression. + * 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 ) @@ -78,7 +78,7 @@ * DEVOUTPICT() is mostly CA-Clipper compliant. Any differences are due * to enhancements in the Harbour TRANSFORM() over CA-Clipper. * $SEEALSO$ - * DEVOUT(), TRANSFORM(). + * DEVOUT() TRANSFORM() * $END$ */ diff --git a/harbour/source/rtl/dircmd.prg b/harbour/source/rtl/dircmd.prg index 9f46379335..7e60be4b2f 100644 --- a/harbour/source/rtl/dircmd.prg +++ b/harbour/source/rtl/dircmd.prg @@ -49,15 +49,66 @@ /* $DOC$ * $FUNCNAME$ - * __Dir()* (DIR command) + * __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. * - * or + * 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$ + * array.ngo:ADIR() DIRECTORY() 'SET DEFAULT' + * $END$ + */ +/* $DOC$ + * $FUNCNAME$ + * DIR + * $CATEGORY$ + * Command + * $ONELINER$ + * Display listings of files + * $SYNTAX$ * * DIR [] * $ARGUMENTS$ @@ -102,7 +153,7 @@ * 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 + * array.ngo:ADIR() DIRECTORY() 'SET DEFAULT' * $END$ */ diff --git a/harbour/source/rtl/empty.c b/harbour/source/rtl/empty.c index 83e03e7ccf..4390732578 100644 --- a/harbour/source/rtl/empty.c +++ b/harbour/source/rtl/empty.c @@ -38,9 +38,9 @@ /* $DOC$ * $FUNCNAME$ - * EMPTY + * EMPTY() * $CATEGORY$ - * + * Conversion * $ONELINER$ * Checks if the passed argument is empty. * $SYNTAX$ @@ -66,7 +66,7 @@ * $COMPLIANCE$ * EMPTY() is fully CA-Clipper compliant. * $SEEALSO$ - * LEN + * LEN() * $END$ */ diff --git a/harbour/source/rtl/environ.c b/harbour/source/rtl/environ.c index 30a06ff401..f5727cc457 100644 --- a/harbour/source/rtl/environ.c +++ b/harbour/source/rtl/environ.c @@ -63,6 +63,10 @@ #define VER_PLATFORM_WIN32_WINDOWS 1 #endif +#if defined(__BORLANDC__) && defined(_WINDOWS_) && ! defined(VER_PLATFORM_WIN32_CE) + #define VER_PLATFORM_WIN32_CE 3 +#endif + #include "extend.h" #include "errorapi.h" #include "hbver.h" @@ -90,6 +94,30 @@ #define INT_86 int86 #endif #endif +/* $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 + * Run an external program + * $SEEALSO$ + * $END$ + */ HARBOUR HB_OS( void ) { @@ -136,13 +164,18 @@ HARBOUR HB_OS( void ) /* TODO: add MSVC support but MSVC cannot detect any OS except Windows! */ #if defined(__TURBOC__) || defined(__BORLANDC__) || defined(_MSC_VER) || defined(__MINGW32__) -#if defined(_WINDOWS_) || defined(WINNT) +#if defined(_WINDOWS_) || defined(WINNT) || defined(__BORLANDC__) -/* NOTE: Support for determining the window version by Luiz Rafael Culik - Culik@sl.conex.net +/* NOTE: + Support for determining the window version by Luiz Rafael Culik + Culik@sl.conex.net + + Support for determining many windows flavours by Jose Lalin + dezac@corevia.com */ OSVERSIONINFO osVer; /* for GetVersionEx() */ + LONG lVersion; osVer.dwOSVersionInfoSize = sizeof( osVer ); @@ -153,23 +186,98 @@ HARBOUR HB_OS( void ) case VER_PLATFORM_WIN32_WINDOWS: hb_osmajor = osVer.dwMajorVersion; hb_osminor = osVer.dwMinorVersion; - hb_osletter = osVer.dwBuildNumber; - hb_os = "Windows 95/98"; + hb_osletter = LOWORD(osVer.dwBuildNumber); + + if( hb_osmajor == 4 && hb_osminor == 0 && hb_osletter == 950 ) + hb_os = "Windows 95"; + else if( hb_osmajor == 4 && hb_osminor > 0 && + hb_osletter > 950 && hb_osletter <= 1080 ) + hb_os = "Windows 95 SP1"; + else if( hb_osmajor == 4 && hb_osminor < 10 && + hb_osletter > 1080 ) + hb_os = "Windows 95 OSR2"; /* Formerly: "Windows 95 SP2" */ + else if( hb_osmajor == 4 && hb_osminor == 10 && + hb_osletter == 1998 ) + hb_os = "Windows 98"; + else if( hb_osmajor == 4 && hb_osminor == 10 && + hb_osletter > 1998 && hb_osletter < 2183 ) + hb_os = "Windows 98 SP1"; + else if( hb_osmajor > 4 && hb_osletter >= 2183 ) + hb_os = "Windows 98 SE"; + else + hb_os = "Windows"; + + /* TODO: Can you fix it, please ? + strcat( hb_os, osVer.szCSDVersion ); + + I don't know why in each call this code returns: + - Windows 95 OSR2 B ... + - Windows 95 OSR2 B B ... + - Windows 95 OSR2 B B B ... + + Add this info in the NT section too. + */ break; case VER_PLATFORM_WIN32_NT: hb_osmajor = osVer.dwMajorVersion; hb_osminor = osVer.dwMinorVersion; - hb_osletter = osVer.dwBuildNumber; - hb_os = "Windows NT"; + hb_osletter = LOWORD(osVer.dwBuildNumber); + + if( hb_osmajor == 3 && hb_osminor == 10 ) + hb_os = "Windows NT 3.1"; + else if( hb_osmajor == 3 && hb_osminor == 50 ) + hb_os = "Windows NT 3.5"; + else if( hb_osmajor == 3 && hb_osminor == 51 ) + hb_os = "Windows NT 3.51"; + else if( hb_osmajor == 4 ) + hb_os = "Windows NT 4"; + else if( hb_osmajor == 5 ) + hb_os = "Windows 2000"; + else + hb_os = "Windows NT"; + + /* TODO: szCSDVersion should contain the service pack installed + if( osVer.szCSDVersion ) + { + int i = 0; + WORD wServicePack; + char szBuffer[ 128 ]; + + while( osVer.szCSDVersion[ i ] != '\0' && !isdigit( osVer.szCSDVersion[ i ] ) ) + i++; + wServicePack = (WORD)( atoi( &osVer.szCSDVersion[ i ] ) ); + + sprintf( szBuffer, "%s %i", hb_os, wServicePack ); + strcopy( hb_os, szBuffer ); + } + */ + /* TODO: Add support for: + * NT Stand Alone Server + * NT Enterprise Edition + * NT Terminal Server + * NT Primary Domain Controller + * NT Backup Domain Controller + + It can be done with: + RegOpenKey( "System\CurrentControlSet\Control\ProductOptions", ... ) + RegQueryValueEx( "ProductType", ..., szBuffer ) + */ break; case VER_PLATFORM_WIN32s: hb_osmajor = osVer.dwMajorVersion; hb_osminor = osVer.dwMinorVersion; - hb_osletter = osVer.dwBuildNumber; + hb_osletter = LOWORD(osVer.dwBuildNumber); hb_os = "Windows 32s"; break; + + case VER_PLATFORM_WIN32_CE: + hb_osmajor = osVer.dwMajorVersion; + hb_osminor = osVer.dwMinorVersion; + hb_osletter = LOWORD(osVer.dwBuildNumber); + hb_os = "Windows CE"; + break; } cformat = "%s %d.%02d.%04d"; } @@ -279,12 +387,15 @@ HARBOUR HB_OS( void ) #define HB_VERSION_BUFFER_LEN 80 +/* Support for determining some compiler version/revision by Jose Lalin + dezac@corevia.com +*/ char * hb_version( USHORT uiMode ) { char * pszVersion; - HB_TRACE(HB_TR_DEBUG, ("hb_version(%hu)", uiMode)); +/* HB_TRACE(("hb_version(%hu)", uiMode)); */ pszVersion = ( char * ) hb_xgrab( HB_VERSION_BUFFER_LEN ); @@ -457,9 +568,12 @@ HARBOUR HB_GETE( void ) /* $DOC$ * $FUNCNAME$ - * __RUN + * __RUN() * $SYNTAX$ * __RUN( ) + * $CATEGORY$ + * DOS + * * $ARGUMENTS$ * Command to execute * $DESCRIPTION$ @@ -486,4 +600,3 @@ HARBOUR HB___RUN( void ) hb_errRT_BASE_Ext1( EG_UNSUPPORTED, 9999, NULL, "__RUN", 0, EF_CANDEFAULT ); #endif } - diff --git a/harbour/source/rtl/errorsys.prg b/harbour/source/rtl/errorsys.prg index 09b6fec2fa..5d70e8f889 100644 --- a/harbour/source/rtl/errorsys.prg +++ b/harbour/source/rtl/errorsys.prg @@ -71,7 +71,7 @@ * $COMPLIANCE$ * ERRORSYS() works exactly like CA-Clipper's ERRORSYS(). * $SEEALSO$ - * ERRORBLOCK(), Error class + * ERRORBLOCK() 'Error class' * $END$ */ diff --git a/harbour/source/rtl/fieldbl.prg b/harbour/source/rtl/fieldbl.prg index ba2de97b12..da24b19ed1 100644 --- a/harbour/source/rtl/fieldbl.prg +++ b/harbour/source/rtl/fieldbl.prg @@ -51,7 +51,7 @@ * $FUNCNAME$ * FIELDBLOCK() * $CATEGORY$ - * Code block manipulation / Databases + * Code Block * $ONELINER$ * Return a code block that sets/gets a value for a given field * $SYNTAX$ @@ -90,7 +90,7 @@ * * CA-Clipper would raise BASE/1003 error if the field does not exist. * $SEEALSO$ - * EVAL(), FIELDWBLOCK(), MEMVARBLOCK() + * EVAL() FIELDWBLOCK() mv.ngo:MEMVARBLOCK() * $END$ */ @@ -107,7 +107,7 @@ FUNCTION FIELDBLOCK( cFieldName ) * $FUNCNAME$ * FIELDWBLOCK() * $CATEGORY$ - * Code block manipulation / Databases + * Code Block * $ONELINER$ * Return a sets/gets code block for field in a given work area * $SYNTAX$ @@ -156,7 +156,7 @@ FUNCTION FIELDBLOCK( cFieldName ) * * CA-Clipper would raise BASE/1003 error if the field does not exist. * $SEEALSO$ - * EVAL(), FIELDBLOCK(), MEMVARBLOCK() + * EVAL() FIELDBLOCK() mv.ngo:MEMVARBLOCK() * $END$ */ diff --git a/harbour/source/rtl/harbinit.prg b/harbour/source/rtl/harbinit.prg index 024dff459b..42de2e590d 100644 --- a/harbour/source/rtl/harbinit.prg +++ b/harbour/source/rtl/harbinit.prg @@ -81,7 +81,7 @@ ANNOUNCE CLIPPER530 * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * INIT PROCEDURE + * 'INIT PROCEDURE' * $END$ */ @@ -123,7 +123,7 @@ INIT PROCEDURE ClipInit * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __XHelp(), SET KEY, SETKEY() + * __XHelp() 'SET KEY' Event.ngo:SETKEY() * $END$ */ diff --git a/harbour/source/rtl/hardcr.c b/harbour/source/rtl/hardcr.c index 95e3633e39..294282ceba 100644 --- a/harbour/source/rtl/hardcr.c +++ b/harbour/source/rtl/hardcr.c @@ -35,9 +35,9 @@ /* $DOC$ * $FUNCNAME$ - * HARDCR + * HARDCR() * $CATEGORY$ - * + * STRINGS * $ONELINER$ * Converts soft carriage pair chr(141)/chr(10) into hard carriage chr(13) * $SYNTAX$ @@ -60,7 +60,7 @@ * $COMPLIANCE$ * HARDCR() is fully CA-Clipper compliant. * $SEEALSO$ - * MEMOTRAN(), STRTRAN() + * MEMOTRAN() STRTRAN() * $END$ */ diff --git a/harbour/source/rtl/initexit.c b/harbour/source/rtl/initexit.c index 238f06e2cf..5e53d47a8e 100644 --- a/harbour/source/rtl/initexit.c +++ b/harbour/source/rtl/initexit.c @@ -40,7 +40,7 @@ * $FUNCNAME$ * __QUIT() * $CATEGORY$ - * + * Events * $ONELINER$ * Terminates an application. * $SYNTAX$ @@ -65,7 +65,7 @@ * $COMPLIANCE$ * __QUIT() is fully CA-Clipper compliant. * $SEEALSO$ - * QUIT command + * QUIT * $END$ */ diff --git a/harbour/source/rtl/inkey.c b/harbour/source/rtl/inkey.c index a66e1273e4..1939935e77 100644 --- a/harbour/source/rtl/inkey.c +++ b/harbour/source/rtl/inkey.c @@ -985,7 +985,7 @@ HARBOUR HB_INKEY( void ) /* $DOC$ * $FUNCNAME$ - * __KEYBOARD( [] ) + * __KEYBOARD() * $CATEGORY$ * Console input * $ONELINER$ @@ -1014,7 +1014,7 @@ HARBOUR HB_INKEY( void ) * $COMPLIANCE$ * __KEYBOARD() is compliant with CA-Clipper 5.3 * $SEEALSO$ - * CLEAR TYPEAHEAD, KEYBOARD + * 'CLEAR TYPEAHEAD' 'KEYBOARD' * $END$ */ @@ -1096,7 +1096,7 @@ void hb_inkeyPut( int ch ) * $COMPLIANCE$ * Was not part of Clipper * $SEEALSO$ - * KEYBOARD, CLEAR TYPEAHEAD, INKEY + * 'KEYBOARD' 'CLEAR TYPEAHEAD' INKEY() * $END$ */ @@ -1144,7 +1144,7 @@ HARBOUR HB___KEYPUT( void ) * $COMPLIANCE$ * NEXTKEY() is compliant with CA-Clipper 5.3 * $SEEALSO$ - * INKEY(), LASTKEY() + * INKEY() LASTKEY() * $END$ */ @@ -1184,7 +1184,7 @@ HARBOUR HB_NEXTKEY( void ) * $COMPLIANCE$ * LASTKEY() is compliant with CA-Clipper 5.3 * $SEEALSO$ - * INKEY(), LASTKEY() + * INKEY() LASTKEY() * $END$ */ diff --git a/harbour/source/rtl/input.prg b/harbour/source/rtl/input.prg index 3ea197d4d5..f3a9824c0a 100644 --- a/harbour/source/rtl/input.prg +++ b/harbour/source/rtl/input.prg @@ -35,9 +35,9 @@ /* $DOC$ * $FUNCNAME$ - * __INPUT + * __INPUT() * $CATEGORY$ - * + * Data input and output * $ONELINER$ * Stops application * $SYNTAX$ @@ -60,7 +60,7 @@ * $COMPLIANCE$ * __INPUT() is fully CA-Clipper compliant. * $SEEALSO$ - * __WAIT, __ACCEPT + * event.ngo:__WAIT() __ACCEPT() * $END$ */ diff --git a/harbour/source/rtl/len.c b/harbour/source/rtl/len.c index 03cd46c99a..20c20a4813 100644 --- a/harbour/source/rtl/len.c +++ b/harbour/source/rtl/len.c @@ -39,9 +39,9 @@ /* $DOC$ * $FUNCNAME$ - * LEN + * LEN() * $CATEGORY$ - * + * Strings * $ONELINER$ * Returns size of a string or size of an array. * $SYNTAX$ @@ -69,7 +69,7 @@ * $COMPLIANCE$ * LEN() is fully CA-Clipper compliant. * $SEEALSO$ - * EMPTY, RTRIM, LTRIM, AADD, ASIZE + * Conv.ngo:EMPTY() RTRIM() LTRIM() array.ngo:AADD() array.ngo:ASIZE() * $END$ */ diff --git a/harbour/source/rtl/memvarbl.prg b/harbour/source/rtl/memvarbl.prg index 4af41b0b72..f3d3f1835e 100644 --- a/harbour/source/rtl/memvarbl.prg +++ b/harbour/source/rtl/memvarbl.prg @@ -39,11 +39,11 @@ /* $DOC$ * $FUNCNAME$ - * MEMVARBLOCK + * MEMVARBLOCK() * $CATEGORY$ - * variables management + * Variable Management * $ONELINER$ - * Returns a codeblock that sets/gets a value of memvar variable + * Returns a codeblock that sets/gets a value of memvar variable * $SYNTAX$ * MEMVARBLOCK( ) * $ARGUMENTS$ @@ -75,7 +75,7 @@ * $COMPLIANCE$ * * $SEEALSO$ - * __MVGET, __MVPUT + * __MVGET() __MVPUT() * $END$ */ diff --git a/harbour/source/rtl/memvars.c b/harbour/source/rtl/memvars.c index 75fd896f36..eaaed5ea8e 100644 --- a/harbour/source/rtl/memvars.c +++ b/harbour/source/rtl/memvars.c @@ -88,7 +88,6 @@ static void hb_memvarCreateFromItem( PHB_ITEM, BYTE, PHB_ITEM ); static void hb_memvarCreateFromDynSymbol( PHB_DYNS, BYTE, PHB_ITEM ); static void hb_memvarAddPrivate( PHB_DYNS ); static HB_DYNS_PTR hb_memvarFindSymbol( HB_ITEM_PTR ); - void hb_memvarsInit( void ) { HB_TRACE(HB_TR_DEBUG, ("hb_memvarsInit()")); @@ -514,7 +513,7 @@ void hb_memvarGetRefer( HB_ITEM_PTR pItem, PHB_SYMB pMemvarSymb ) hb_errInternal( 9999, "Invalid symbol item passed as memvar %s", pMemvarSymb->szName, NULL ); } -/* Create a new variable declared as procedure/function PARAMETER +/* */ void hb_memvarNewParameter( PHB_SYMB pSymbol, PHB_ITEM pValue ) { @@ -523,13 +522,6 @@ void hb_memvarNewParameter( PHB_SYMB pSymbol, PHB_ITEM pValue ) hb_memvarCreateFromDynSymbol( pSymbol->pDynSym, HB_MV_PRIVATE, pValue ); } -/* This function returns a string value of memvar variable with passed name. - * If a requested variable does not exist or contains non-string value - * then the NULL pointer is returned. - * NOTE: - * This is a helper function for macro text substitution - * var1 := "&var2.value" - */ char * hb_memvarGetStrValuePtr( char * szVarName, ULONG *pulLen ) { HB_ITEM itName; @@ -566,7 +558,6 @@ char * hb_memvarGetStrValuePtr( char * szVarName, ULONG *pulLen ) return szValue; } - /* * This function creates a value for memvar variable * @@ -891,19 +882,12 @@ static HB_DYNS_PTR hb_memvarFindSymbol( HB_ITEM_PTR pName ) if( pName ) { - ULONG ulLen; - - /* truncate a passed name to maximal allowed symbol name - */ - if( pName->item.asString.length < HB_SYMBOL_NAME_LEN ) - ulLen = pName->item.asString.length; - else - ulLen = HB_SYMBOL_NAME_LEN; + ULONG ulLen = pName->item.asString.length; if( ulLen ) { + char * szName = ( char * ) hb_xgrab( ulLen + 1 ); char * szArg = pName->item.asString.value; - char szName[ HB_SYMBOL_NAME_LEN + 1 ]; szName[ ulLen ] = '\0'; do @@ -913,6 +897,7 @@ static HB_DYNS_PTR hb_memvarFindSymbol( HB_ITEM_PTR pName ) } while( ulLen ); pDynSym = hb_dynsymFind( szName ); + hb_xfree( szName ); } } return pDynSym; @@ -926,7 +911,7 @@ static HB_DYNS_PTR hb_memvarFindSymbol( HB_ITEM_PTR pName ) * $FUNCNAME$ * __MVPUBLIC() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function creates a PUBLIC variable * $SYNTAX$ @@ -1008,7 +993,7 @@ HARBOUR HB___QQPUB( void ) * $FUNCNAME$ * __MVPRIVATE() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function creates a PRIVATE variable * $SYNTAX$ @@ -1079,7 +1064,7 @@ HARBOUR HB___MVPRIVATE( void ) * $FUNCNAME$ * __MVXRELEASE() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function releases value stored in PRIVATE or PUBLIC variable * $SYNTAX$ @@ -1175,7 +1160,7 @@ HARBOUR HB___MVXRELEASE( void ) * $FUNCNAME$ * __MVRELEASE() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function releases PRIVATE variables created in current procedure * $SYNTAX$ @@ -1239,7 +1224,7 @@ HARBOUR HB___MVRELEASE( void ) * $FUNCNAME$ * __MVSCOPE() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * If variable exists then returns its scope. * $SYNTAX$ @@ -1313,7 +1298,7 @@ HARBOUR HB___MVSCOPE( void ) * $FUNCNAME$ * __MVCLEAR() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function releases all PRIVATE and PUBLIC variables * $SYNTAX$ @@ -1347,7 +1332,7 @@ HARBOUR HB___MVCLEAR( void ) * $FUNCNAME$ * __MVDBGINFO() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function returns the information about the variables for debugger * $SYNTAX$ @@ -1514,7 +1499,7 @@ HARBOUR HB___MVDBGINFO( void ) * $FUNCNAME$ * __MVGET() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function returns value of memory variable * $SYNTAX$ @@ -1535,7 +1520,7 @@ HARBOUR HB___MVDBGINFO( void ) * $COMPLIANCE$ * * $SEEALSO$ - * MVPUT() + * __MVPUT() * $END$ */ HARBOUR HB___MVGET( void ) @@ -1607,7 +1592,7 @@ HARBOUR HB___MVGET( void ) * $FUNCNAME$ * __MVPUT() * $CATEGORY$ - * Variable management + * Variable Management * $ONELINER$ * This function set the value of memory variable * $SYNTAX$ @@ -1632,7 +1617,7 @@ HARBOUR HB___MVGET( void ) * $COMPLIANCE$ * * $SEEALSO$ - * MVPUT() + * __MVPUT() * $END$ */ HARBOUR HB___MVPUT( void ) diff --git a/harbour/source/rtl/menuto.prg b/harbour/source/rtl/menuto.prg index feaa46d674..1238f25aff 100644 --- a/harbour/source/rtl/menuto.prg +++ b/harbour/source/rtl/menuto.prg @@ -39,7 +39,7 @@ static s_nPointer := 1 /* $DOC$ * $FUNCNAME$ - * __AtPrompt() (@...PROMPT command) + * __AtPrompt() * $CATEGORY$ * Data input and output * $ONELINER$ @@ -47,9 +47,6 @@ static s_nPointer := 1 * $SYNTAX$ * __AtPrompt( , , , [] ) --> .F. * - * or - * - * @ , PROMPT [MESSAGE ] * $ARGUMENTS$ * is the row number to display the menu . Value could * range from zero to MAXROW(). @@ -100,7 +97,69 @@ static s_nPointer := 1 * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * ACHOICE(), MENU TO, SET MESSAGE, SET INTENSITY, SET WRAP, __MenuTo() + * array.ngo:ACHOICE() comm.ngo:'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$ + * array.ngo:ACHOICE() comm.ngo:'MENU TO' 'SET MESSAGE' 'SET INTENSITY' 'SET WRAP' datai.ngo:__MENUTO() * $END$ */ @@ -132,10 +191,6 @@ function __AtPrompt( nRow, nCol, cPrompt, cMsg ) * Invoked a menu defined by set of @...PROMPT * $SYNTAX$ * __MenuTo( , ) --> nChoice - * - * or - * - * MENU TO * $ARGUMENTS$ * is a set/get code block for variable named . * @@ -208,8 +263,89 @@ function __AtPrompt( nRow, nCol, cPrompt, cMsg ) * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * @...PROMPT, ACHOICE(), SET MESSAGE, SET INTENSITY, SET WRAP, - * __AtPrompt() + * comm.ngo:'@...PROMPT' array.ngo: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$ + * comm.ngo:'@...PROMPT' array.ngo:ACHOICE() 'SET MESSAGE' 'SET INTENSITY' 'SET WRAP' datai.ngo:__ATPROMPT() * $END$ */ diff --git a/harbour/source/rtl/mtran.c b/harbour/source/rtl/mtran.c index 64123e81c6..9b7b312d67 100644 --- a/harbour/source/rtl/mtran.c +++ b/harbour/source/rtl/mtran.c @@ -35,9 +35,9 @@ /* $DOC$ * $FUNCNAME$ - * MEMOTRAN + * MEMOTRAN() * $CATEGORY$ - * + * Strings * $ONELINER$ * Converts hard and soft carriages within strings. * $SYNTAX$ @@ -64,7 +64,7 @@ * $COMPLIANCE$ * MEMOTRAN() is fully CA-Clipper compliant. * $SEEALSO$ - * HARDCR(), STRTRAN() + * HARDCR() STRTRAN() * $END$ */ diff --git a/harbour/source/rtl/natmsg.c b/harbour/source/rtl/natmsg.c index 1b74fdf1bd..5f3b3a1dfd 100644 --- a/harbour/source/rtl/natmsg.c +++ b/harbour/source/rtl/natmsg.c @@ -94,9 +94,9 @@ char * hb_nationGetMsg( USHORT uiMsg ) /* $DOC$ * $FUNCNAME$ - * ISAFFIRM + * ISAFFIRM() * $CATEGORY$ - * + * NATION * $ONELINER$ * Checks if passed char is an affirmation char * $SYNTAX$ @@ -118,7 +118,7 @@ char * hb_nationGetMsg( USHORT uiMsg ) * $COMPLIANCE$ * ISAFFIRM() is fully CA-Clipper compliant. * $SEEALSO$ - * ISNEGATIVE, NATIONMSG + * ISNEGATIVE() NATIONMSG() * $END$ */ @@ -131,9 +131,9 @@ HARBOUR HB_ISAFFIRM( void ) /* $DOC$ * $FUNCNAME$ - * ISNEGATIVE + * ISNEGATIVE() * $CATEGORY$ - * + * NATION * $ONELINER$ * Checks if passed char is a negation char * $SYNTAX$ @@ -155,7 +155,7 @@ HARBOUR HB_ISAFFIRM( void ) * $COMPLIANCE$ * ISNEGATIVE() is fully CA-Clipper compliant. * $SEEALSO$ - * ISAFFIRM, NATIONMSG + * ISAFFIRM() NATIONMSG() * $END$ */ @@ -168,9 +168,9 @@ HARBOUR HB_ISNEGATIVE( void ) /* $DOC$ * $FUNCNAME$ - * NATIONMSG + * NATIONMSG() * $CATEGORY$ - * + * NATION * $ONELINER$ * Returns international strings messages. * $SYNTAX$ @@ -194,7 +194,7 @@ HARBOUR HB_ISNEGATIVE( void ) * $COMPLIANCE$ * NATIONMSG() is fully CA-Clipper compliant. * $SEEALSO$ - * ISAFFIRM, ISNEGATIVE + * ISAFFIRM() ISNEGATIVE() * $END$ */ diff --git a/harbour/source/rtl/objfunc.prg b/harbour/source/rtl/objfunc.prg index ea3203f8cc..57047b1999 100644 --- a/harbour/source/rtl/objfunc.prg +++ b/harbour/source/rtl/objfunc.prg @@ -82,7 +82,7 @@ * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objGetMethodList(), __objGetMsgList(), __objHasMethod() + * __ObjGetMethodLis __objGetMsgList() __objHasMethod() * $END$ */ @@ -127,7 +127,7 @@ return __objHasMsg( oObject, cSymbol ) .and. ; * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objGetMethodList(), __objGetMsgList(), __objHasData() + * __ObjGetMethodLis __objGetMsgList() __objHasData() * $END$ */ @@ -184,8 +184,7 @@ return __objHasMsg( oObject, cSymbol ) .and. ; * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objGetMethodList(), __objGetValueList(), __objHasData(), - * __objHasMethod() + * __ObjGetMethodLis __ObjGetValueList __objHasData() __objHasMethod() * $END$ */ @@ -261,8 +260,7 @@ return aData * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objGetMsgList(), __objGetValueList(), __objHasData(), - * __objHasMethod() + * __objGetMsgList() __ObjGetValueList __objHasData() __objHasMethod() * $END$ */ @@ -314,8 +312,7 @@ return __objGetMsgList( oObject, .F. ) * $FILES$ * Header file is hboo.ch * $SEEALSO$ - * __objGetMethodList(), __objGetMsgList(), __objHasData(), - * __objHasMethod(), __objSetValueList() + * __ObjGetMethodLis __objGetMsgList() __objHasData() __objHasMethod() __ObjSetValueList * $END$ */ @@ -350,22 +347,22 @@ return aData /* $DOC$ * $FUNCNAME$ - * __objSetValueList() + * __ObjSetValueList() * $CATEGORY$ * Object manipulation * $ONELINER$ * Set object with an array of DATA names and values * $SYNTAX$ - * __objSetValueList( , ) --> oObject + * __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 . + * __ObjSetValueList() return a reference to . * $DESCRIPTION$ - * __objSetValueList() is a low level class support function that let + * __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 @@ -382,7 +379,7 @@ return aData * aData[ 3, HB_OO_DATA_VALUE ] = 20 * aData[ 4, HB_OO_DATA_SYMBOL ] = "nRight" * aData[ 4, HB_OO_DATA_VALUE ] = 70 - * __objSetValueList( oB, aData ) + * __ObjSetValueList( oB, aData ) * ? oB:nTop // 1 * ? oB:nLeft // 10 * ? oB:nBottom // 20 @@ -390,16 +387,16 @@ return aData * $TESTS$ * $STATUS$ * $COMPLIANCE$ - * __objSetValueList() is an Harbour extension. + * __ObjSetValueList() is an Harbour extension. * $PLATFORMS$ * $FILES$ * Header file is hboo.ch * $SEEALSO$ - * __objGetValueList() + * __ObjGetValueList * $END$ */ -function __objSetValueList( oObject, aData ) +function __ObjSetValueList( oObject, aData ) if !ISOBJECT( oObject ) __errRT_BASE(EG_ARG, 3101, NIL, ProcName( 0 ) ) @@ -460,9 +457,7 @@ return oObject * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddInline(), __objAddData(), __objDelMethod(), - * __objGetMethodList(), __objGetMsgList(), __objHasMethod(), - * __objModMethod() + * __objAddInline() __objAddData() __objDelMethod() __ObjGetMethodLis __objGetMsgList() __objHasMethod() __objModMethod() * $END$ */ @@ -519,9 +514,7 @@ return oObject * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddData(), __objAddMethod(), __objDelInline(), - * __objGetMethodList(), __objGetMsgList(), __objHasMethod(), - * __objModInline() + * __objAddData() __objAddMethod() __objDelInline() __ObjGetMethodLis __objGetMsgList() __objHasMethod() __objModInline() * $END$ */ @@ -576,9 +569,7 @@ return oObject * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddInline(), __objAddMethod(), __objDelData(), - * __objGetMsgList(), __objGetValueList(), __objHasData(), - * __objSetValueList() + * __objAddInline() __objAddMethod() __objDelData() __objGetMsgList() __ObjGetValueList __objHasData() __ObjSetValueList * $END$ */ @@ -667,8 +658,7 @@ return oObject * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddMethod(), __objDelMethod(), __objGetMethodList(), - * __objGetMsgList(), __objHasMethod() + * __objAddMethod() __objDelMethod() __ObjGetMethodLis __objGetMsgList() __objHasMethod() * $END$ */ @@ -694,7 +684,8 @@ return oObject * $CATEGORY$ * Object manipulation * $ONELINER$ - * Modify (replace) an INLINE method in an already existing class + * Modify (replace) an INLINE method in an already + * existing class * $SYNTAX$ * __objModInline( , , ) --> oObject * $ARGUMENTS$ @@ -730,8 +721,7 @@ return oObject * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddInline(), __objDelInline(), __objGetMethodList(), - * __objGetMsgList(), __objHasMethod() + * __objAddInline() __objDelInline() __ObjGetMethodLis __objGetMsgList() __objHasMethod() * $END$ */ @@ -803,9 +793,7 @@ return oObject * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddInline(), __objAddMethod(), __objGetMethodList(), - * __objGetMsgList(), __objHasMethod(), __objModInline(), - * __objModMethod() + * __objAddInline() __objAddMethod() __ObjGetMethodLis __objGetMsgList() __objHasMethod() __objModInline() __objModMethod() * $END$ */ @@ -823,6 +811,61 @@ function __objDelMethod( oObject, cSymbol ) endif return oObject +/* $DOC$ + * $FUNCNAME$ + * __objDelInline() + * $CATEGORY$ + * Object manipulation + * $ONELINER$ + * Delete a METHOD or INLINE method from class + * $SYNTAX$ + * __objDelMethod( , ) --> oObject + * + * or + * + * __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$ + * __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. If a symbol + * with the name does not exist in a run time error + * will occur. + * + * __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 an Harbour extension. + * $PLATFORMS$ + * $FILES$ + * $SEEALSO$ + * __objAddInline() __objAddMethod() __ObjGetMethodLis __objGetMsgList() __objHasMethod() __objModInline() __objModMethod() + * $END$ + */ function __objDelInline( oObject, cSymbol ) return __objDelMethod( oObject, cSymbol ) // Same story @@ -862,8 +905,8 @@ return __objDelMethod( oObject, cSymbol ) // Same story * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * __objAddData(), __objGetMsgList(), __objGetValueList(), - * __objHasData(), __objSetValueList() + * __objAddData() __objGetMsgList() __ObjGetValueList + * __objHasData() __ObjSetValueList * $END$ */ diff --git a/harbour/source/rtl/pcount.c b/harbour/source/rtl/pcount.c index 37ca6efca5..7dda98762c 100644 --- a/harbour/source/rtl/pcount.c +++ b/harbour/source/rtl/pcount.c @@ -37,9 +37,9 @@ /* $DOC$ * $FUNCNAME$ - * PCOUNT + * PCOUNT() * $CATEGORY$ - * + * Parameter Checks * $ONELINER$ * Retrieves the number of arguments passed to a function. * $SYNTAX$ @@ -67,7 +67,7 @@ * $COMPLIANCE$ * PCOUNT() is fully CA-Clipper compliant. * $SEEALSO$ - * PVALUE + * HB_PVALUE() * $END$ */ diff --git a/harbour/source/rtl/proc.c b/harbour/source/rtl/proc.c index dc7b17670b..4990daca9c 100644 --- a/harbour/source/rtl/proc.c +++ b/harbour/source/rtl/proc.c @@ -48,9 +48,9 @@ /* $DOC$ * $FUNCNAME$ - * PROCNAME + * PROCNAME() * $CATEGORY$ - * + * Misc * $ONELINER$ * Gets the name of the current function on the stack * $SYNTAX$ @@ -79,7 +79,7 @@ * $COMPLIANCE$ * PROCNAME() is fully CA-Clipper compliant. * $SEEALSO$ - * PROCLINE, PROCFILE + * PROCLINE() PROCFILE() * $END$ */ @@ -114,9 +114,9 @@ HARBOUR HB_PROCNAME( void ) /* $DOC$ * $FUNCNAME$ - * PROCLINE + * PROCLINE() * $CATEGORY$ - * + * Misc * $ONELINER$ * Gets the line number of the current function on the stack * $SYNTAX$ @@ -142,7 +142,7 @@ HARBOUR HB_PROCNAME( void ) * $COMPLIANCE$ * PROCLINE() is fully CA-Clipper compliant. * $SEEALSO$ - * PROCNAME, PROCFILE + * PROCNAME() PROCFILE() * $END$ */ @@ -162,9 +162,9 @@ HARBOUR HB_PROCLINE( void ) /* $DOC$ * $FUNCNAME$ - * PROCFILE + * PROCFILE() * $CATEGORY$ - * + * Misc * $ONELINER$ * This function allways returns an empty string. * $SYNTAX$ @@ -189,7 +189,7 @@ HARBOUR HB_PROCLINE( void ) * $COMPLIANCE$ * PROCFILE() is fully CA-Clipper compliant. * $SEEALSO$ - * PROCNAME, PROCLINE + * PROCNAME() PROCLINE() * $END$ */ diff --git a/harbour/source/rtl/pvalue.c b/harbour/source/rtl/pvalue.c index 4eb67bc734..de388f0a5e 100644 --- a/harbour/source/rtl/pvalue.c +++ b/harbour/source/rtl/pvalue.c @@ -39,9 +39,9 @@ /* $DOC$ * $FUNCNAME$ - * HB_PVALUE + * HB_PVALUE() * $CATEGORY$ - * + * Parameter Checks * $ONELINER$ * Retrieves the value of an argument. * $SYNTAX$ @@ -66,7 +66,7 @@ * $COMPLIANCE$ * HB_PVALUE() is a new function and hence not CA-Clipper compliant. * $SEEALSO$ - * PCOUNT + * PCOUNT() * $END$ */ diff --git a/harbour/source/rtl/readkey.prg b/harbour/source/rtl/readkey.prg index 45f82c92fd..acf3d15ebb 100644 --- a/harbour/source/rtl/readkey.prg +++ b/harbour/source/rtl/readkey.prg @@ -93,7 +93,7 @@ * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * @...GET, INKEY(), LASTKEY(), READ, READEXIT(), UPDATED() + * '@...GET' consimpu.ngo:INKEY() consimpu.ngo:LASTKEY() 'READ' READEXIT() UPDATED() * $END$ */ diff --git a/harbour/source/rtl/readvar.prg b/harbour/source/rtl/readvar.prg index be3988d758..dd50b654ce 100644 --- a/harbour/source/rtl/readvar.prg +++ b/harbour/source/rtl/readvar.prg @@ -33,66 +33,8 @@ * */ -/* - * 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. - * - */ - #include "common.ch" -/* $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$ - */ - FUNCTION ReadVar( cVarName ) STATIC s_cVarName := "" diff --git a/harbour/source/rtl/set.c b/harbour/source/rtl/set.c index 4becb0cc33..bb20e8342a 100644 --- a/harbour/source/rtl/set.c +++ b/harbour/source/rtl/set.c @@ -391,11 +391,22 @@ HARBOUR HB_SETCANCEL( void ) } /* $DOC$ - * $FUNCNAME$ __SETCENTURY( [ | ] ) --> lPreviousValue - * $ARGUMENTS$ optional or (not case sensitive) + * $FUNCNAME$ + * __SETCENTURY() + * + * $CATEGORY$ + * Enviroment + * $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 + * $RETURNS$ + Either the current or previous century setting as a logical value * $END$ */ HARBOUR HB___SETCENTURY( void ) @@ -481,8 +492,17 @@ HARBOUR HB___SETCENTURY( void ) } /* $DOC$ - * $FUNCNAME$ SET( [, [, ] ] ) --> xPreviousSetting - * $ARGUMENTS$ + * $FUNCNAME$ + * SET() + * $CATEGORY$ + * Enviroment + * $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 diff --git a/harbour/source/rtl/setfunc.prg b/harbour/source/rtl/setfunc.prg index 867258cf3a..693d63c26e 100644 --- a/harbour/source/rtl/setfunc.prg +++ b/harbour/source/rtl/setfunc.prg @@ -33,76 +33,8 @@ * */ -/* - * The following parts are Copyright of the individual authors. - * www - http://www.harbour-project.org - * - * Copyright 1999 Chen Kedem - * __SetFunction() documentation - * - * See doc/license.txt for licensing terms. - * - */ - #include "inkey.ch" -/* $DOC$ - * $FUNCNAME$ - * __SetFunction() (SET FUNCTION command) - * $CATEGORY$ - * Environment - * $ONELINER$ - * Assign a character string to a function key - * $SYNTAX$ - * __SetFunction( , [] ) --> NIL - * - * or - * - * 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 __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() - * $END$ - */ - PROCEDURE __SetFunction( nFunctionKey, cString ) /* NOTE: CA-Cl*pper will not handle F11 and F12 here. */ diff --git a/harbour/source/rtl/setkey.prg b/harbour/source/rtl/setkey.prg index 8f1328b277..4592c6f23d 100644 --- a/harbour/source/rtl/setkey.prg +++ b/harbour/source/rtl/setkey.prg @@ -54,9 +54,9 @@ static s_aSetKeys := {} // holds array of hot-key id, code-block, activati /* $DOC$ * $FUNCNAME$ - * SetKey + * SETKEY() * $CATEGORY$ - * ? + * Events * $ONELINER$ * Assign an action block to a key * $SYNTAX$ @@ -84,7 +84,8 @@ static s_aSetKeys := {} // holds array of hot-key id, code-block, activati * * // 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 } ) + * SetKey( K_F10, {|| GetActive():State := GE_WRITE },; + * {|| GetActive() != NIL } ) * $TESTS$ * None definable * $STATUS$ @@ -95,7 +96,7 @@ static s_aSetKeys := {} // holds array of hot-key id, code-block, activati * be conditionally turned off or on. This condition-block cannot be * returned once set - see SetKeyGet() * $SEEALSO$ - * SETKEYSAVE() + * HB_SETKEYSAVE() * $END$ */ Function SetKey( anKey, bBlock, bCondition ) @@ -137,9 +138,9 @@ return bReturn /* $DOC$ * $FUNCNAME$ - * HB_SetKeyGet + * HB_SetKeyGet() * $CATEGORY$ - * ? + * Events * $ONELINER$ * Determine a set-key code block & condition-block * $SYNTAX$ @@ -165,7 +166,7 @@ return bReturn * $COMPLIANCE$ * HB_SETKEYGET() is a new function and hence not CA-Clipper compliant. * $SEEALSO$ - * SETKEY(), HB_SETKEYSAVE(), HB_SETKEYCHECK() + * SETKEY() HB_SETKEYSAVE() HB_SETKEYCHECK() * $END$ */ Function HB_SetKeyGet( nKey, bCondition ) @@ -188,11 +189,12 @@ return NIL //bReturn /* $DOC$ * $FUNCNAME$ - * HB_SetKeySave + * HB_SETKEYSAVE() * $CATEGORY$ - * ? + * Events * $ONELINER$ - * Returns a copy of internal set-key list, optionally overwriting + * Returns a copy of internal set-key list, + * optionally overwriting * $SYNTAX$ * HB_SETKEYSAVE( [ ] ) * $ARGUMENTS$ @@ -240,9 +242,9 @@ return aReturn /* $DOC$ * $FUNCNAME$ - * HB_SetKeyCheck + * HB_SetKeyCheck() * $CATEGORY$ - * ? + * Events * $ONELINER$ * Impliments common hot-key activation code * $SYNTAX$ @@ -255,11 +257,11 @@ return aReturn * 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 + * - 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(), @@ -281,7 +283,7 @@ return aReturn * $COMPLIANCE$ * HB_SETKEYCHECK() is new. * $SEEALSO$ - * SETKEY(), HB_SETKEYSAVE() + * SETKEY() HB_SETKEYSAVE() * $END$ */ Function HB_SetKeyCheck( nKey, p1, p2, p3 ) diff --git a/harbour/source/rtl/setta.prg b/harbour/source/rtl/setta.prg index ad3245e6dd..1d032e19fc 100644 --- a/harbour/source/rtl/setta.prg +++ b/harbour/source/rtl/setta.prg @@ -35,9 +35,9 @@ /* $DOC$ * $FUNCNAME$ - * SETTYPEAHEAD + * SETTYPEAHEAD() * $CATEGORY$ - * + * Enviroment * $ONELINER$ * Sets the typeahead buffer to given size. * $SYNTAX$ @@ -59,7 +59,7 @@ * $COMPLIANCE$ * SETTYPEAHEAD() is fully CA-Clipper compliant. * $SEEALSO$ - * __ACCEPT, __INPUT + * __ACCEPT() datai.ngo:__INPUT() * $END$ */ diff --git a/harbour/source/rtl/strings.c b/harbour/source/rtl/strings.c index 02f8d05970..142b8d0e47 100644 --- a/harbour/source/rtl/strings.c +++ b/harbour/source/rtl/strings.c @@ -1197,7 +1197,7 @@ HARBOUR HB_VAL( void ) /* $DOC$ * $FUNCNAME$ - * STR + * STR() * $CATEGORY$ * Run-time Library, Strings * $ONELINER$ @@ -1258,8 +1258,7 @@ HARBOUR HB_VAL( void ) * $COMPLIANCE$ * CA-Clipper compatible. * $SEEALSO$ - * STRZERO() - * VAL() + * STRZERO() VAL() * $END$ */ @@ -1317,7 +1316,7 @@ HARBOUR HB_STR( void ) /* $DOC$ * $FUNCNAME$ - * STRZERO + * STRZERO() * $CATEGORY$ * Run-time Library, Strings * $ONELINER$ @@ -1378,8 +1377,7 @@ HARBOUR HB_STR( void ) * $COMPLIANCE$ * CA-Clipper compatible (it was not mentioned in the docs though). * $SEEALSO$ - * STR() - * VAL() + * runtime.ngo:STR() VAL() * $END$ */ @@ -1470,7 +1468,7 @@ HARBOUR HB_STRZERO( void ) /* $DOC$ * $FUNCNAME$ - * HB_VALTOSTR + * HB_VALTOSTR() * $CATEGORY$ * Strings * $ONELINER$ @@ -1499,7 +1497,7 @@ HARBOUR HB_STRZERO( void ) * $COMPLIANCE$ * HB_VALTOSTR() is a Harbour enhancement. * $SEEALSO$ - * STR(), VAL() + * runtime.ngo:STR() VAL() * $END$ */ diff --git a/harbour/source/rtl/text.prg b/harbour/source/rtl/text.prg index d7fe909e6c..82718d6732 100644 --- a/harbour/source/rtl/text.prg +++ b/harbour/source/rtl/text.prg @@ -58,7 +58,8 @@ STATIC s_cOldExtraFile * $CATEGORY$ * Internal * $ONELINER$ - * Redirect console output to printer or a file and save old settings + * Redirect console output to printer or a file and + * save old settings * $SYNTAX$ * __TextSave( ) --> NIL * $ARGUMENTS$ @@ -79,7 +80,7 @@ STATIC s_cOldExtraFile * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * SET(), SET ALTERNATE, SET PRINTER, TEXT, __TextRestore() + * envirom.ngi:SET() 'SET ALTERNATE' 'SET PRINTER' 'TEXT' __TextRestore() * $END$ */ @@ -121,7 +122,7 @@ PROCEDURE __TextSave( cFile ) * $PLATFORMS$ * $FILES$ * $SEEALSO$ - * SET(), SET ALTERNATE, SET PRINTER, TEXT, __TextSave() + * envirom.ngi:SET() 'SET ALTERNATE' 'SET PRINTER' 'TEXT' __TextSave() * $END$ */ diff --git a/harbour/source/rtl/tone.c b/harbour/source/rtl/tone.c index d07a57a5fa..277a31a9b9 100644 --- a/harbour/source/rtl/tone.c +++ b/harbour/source/rtl/tone.c @@ -90,7 +90,7 @@ * $FUNCNAME$ * TONE() * $CATEGORY$ - * Misc. + * Misc * $ONELINER$ * Sound a tone with a specifies frequency and duration * $SYNTAX$ @@ -130,7 +130,7 @@ * $COMPLIANCE$ * TONE() works exactly like CA-Clipper's TONE(). * $SEEALSO$ - * CHR(), SET BELL + * CHR() 'SET BELL' * $END$ */ diff --git a/harbour/source/rtl/type.c b/harbour/source/rtl/type.c index d7dbc50427..88f84e2909 100644 --- a/harbour/source/rtl/type.c +++ b/harbour/source/rtl/type.c @@ -37,9 +37,9 @@ /* $DOC$ * $FUNCNAME$ - * TYPE + * TYPE() * $CATEGORY$ - * + * Misc * $ONELINER$ * Retrieves the type of an expression * $SYNTAX$ @@ -59,7 +59,7 @@ * $COMPLIANCE$ * TYPE() is * $SEEALSO$ - * VALTYPE + * VALTYPE() * $END$ */ diff --git a/harbour/source/rtl/valtype.c b/harbour/source/rtl/valtype.c index eb4f9e74a9..d58c25ede2 100644 --- a/harbour/source/rtl/valtype.c +++ b/harbour/source/rtl/valtype.c @@ -37,9 +37,9 @@ /* $DOC$ * $FUNCNAME$ - * VALTYPE + * VALTYPE() * $CATEGORY$ - * + * Misc * $ONELINER$ * Retrieves the data type of an expression * $SYNTAX$ @@ -69,7 +69,7 @@ * $COMPLIANCE$ * VALTYPE() is fully CA-Clipper compliant. * $SEEALSO$ - * TYPE + * TYPE() * $END$ */ diff --git a/harbour/source/rtl/wait.prg b/harbour/source/rtl/wait.prg index 1826c7c865..d543e61282 100644 --- a/harbour/source/rtl/wait.prg +++ b/harbour/source/rtl/wait.prg @@ -35,9 +35,9 @@ /* $DOC$ * $FUNCNAME$ - * __WAIT + * __WAIT() * $CATEGORY$ - * + * Events * $ONELINER$ * Stops the application until a key is pressed. * $SYNTAX$ @@ -61,7 +61,7 @@ * $COMPLIANCE$ * __WAIT() is fully CA-Clipper compliant. * $SEEALSO$ - * __ACCEPT, __INPUT + * __ACCEPT() datai.ngo:__INPUT() * $END$ */ diff --git a/harbour/source/rtl/word.c b/harbour/source/rtl/word.c index ed078d75fd..db2af1460c 100644 --- a/harbour/source/rtl/word.c +++ b/harbour/source/rtl/word.c @@ -39,9 +39,9 @@ /* $DOC$ * $FUNCNAME$ - * WORD + * WORD() * $CATEGORY$ - * + * Conversion * $ONELINER$ * Converts double to integer values. * $SYNTAX$ @@ -60,7 +60,7 @@ * $COMPLIANCE$ * WORD() is NOT fully CA-Clipper compliant. * $SEEALSO$ - * CALL command + * 'CALL' * $END$ */ diff --git a/harbour/source/rtl/xsavescr.prg b/harbour/source/rtl/xsavescr.prg index 1d15f63007..41eaf56427 100644 --- a/harbour/source/rtl/xsavescr.prg +++ b/harbour/source/rtl/xsavescr.prg @@ -49,17 +49,13 @@ STATIC s_cScrn /* $DOC$ * $FUNCNAME$ - * __XSaveScreen() (SAVE SCREEN command) + * __XSaveScreen() * $CATEGORY$ * Data input and output * $ONELINER$ * Save whole screen image and coordinate to an internal buffer * $SYNTAX$ * __XSaveScreen() --> NIL - * - * or - * - * SAVE SCREEN * $ARGUMENTS$ * none. * $RETURNS$ @@ -92,7 +88,49 @@ STATIC s_cScrn * platforms. * $FILES$ * $SEEALSO$ - * RESTORE SCREEN, RESTSCREEN(), SAVESCREEN() + * comm.ngo:'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$ + * comm.ngo:'RESTORE SCREEN' RESTSCREEN() SAVESCREEN() * $END$ */ @@ -104,7 +142,7 @@ PROCEDURE __XSAVESCREEN() /* $DOC$ * $FUNCNAME$ - * __XRestScreen() (RESTORE SCREEN command) + * __XRestScreen() * $CATEGORY$ * Data input and output * $ONELINER$ @@ -146,7 +184,48 @@ PROCEDURE __XSAVESCREEN() * platforms. * $FILES$ * $SEEALSO$ - * RESTSCREEN(), SAVE SCREEN, SAVESCREEN() + * RESTSCREEN() comm.ngo:'SAVE SCREEN' SAVESCREEN() + * $END$ + */ +/* $DOC$ + * $FUNCNAME$ + * REST 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$ + * RESTSCREEN() comm.ngo:'SAVE SCREEN' SAVESCREEN() * $END$ */ diff --git a/harbour/source/tools/io.c b/harbour/source/tools/io.c index f65ba1e80e..6c45e42ebc 100644 --- a/harbour/source/tools/io.c +++ b/harbour/source/tools/io.c @@ -16,6 +16,7 @@ * $CATEGORY$ * DOS * $ONELINER$ + * Change the Current Directory * $SYNTAX$ * CD() * $ARGUMENTS$ @@ -34,7 +35,7 @@ * ENDIF * * $SEEALSO$ - * + * MD() RD() * $INCLUDE$ * extend.h dos.h dir.h bios.h * $END$ @@ -55,7 +56,7 @@ HARBOUR HB_CD( void ) * $CATEGORY$ * DOS * $ONELINER$ - * + * Creates a Directory * $SYNTAX$ * MD() * $ARGUMENTS$ @@ -74,7 +75,7 @@ HARBOUR HB_CD( void ) * ENDIF * * $SEEALSO$ - * + * CD() MD() * $INCLUDE$ * extend.h dos.h dir.h bios.h * $END$ @@ -95,7 +96,7 @@ HARBOUR HB_MD(void) * $CATEGORY$ * DOS * $ONELINER$ - * + * Remove a Directory * $SYNTAX$ * RD() * $ARGUMENTS$ @@ -114,7 +115,7 @@ HARBOUR HB_MD(void) * ENDIF * * $SEEALSO$ - * + * CD() MD() * $INCLUDE$ * extend.h dos.h dir.h bios.h * $END$ diff --git a/harbour/source/tools/nconvert.prg b/harbour/source/tools/nconvert.prg index 549db6c3d6..8ad02fdd59 100644 --- a/harbour/source/tools/nconvert.prg +++ b/harbour/source/tools/nconvert.prg @@ -247,7 +247,7 @@ FUNCTION DecToBin(nNumber) * * $INCLUDE$ * - * $EnNumber$ + * $END$ */ FUNCTION DecToOctal(nNumber) @@ -283,7 +283,7 @@ FUNCTION DecToOctal(nNumber) * * $INCLUDE$ * - * $EnNumber$ + * $END$ */ FUNCTION DecToHexa(nNumber) @@ -319,7 +319,7 @@ FUNCTION DecToHexa(nNumber) * * $INCLUDE$ * - * $EnNumber$ + * $END$ */ FUNCTION BinToDec(cString) @@ -355,7 +355,7 @@ FUNCTION BinToDec(cString) * * $INCLUDE$ * - * $EnNumber$ + * $END$ */ FUNCTION OctalToDec(cString) @@ -391,7 +391,7 @@ FUNCTION OctalToDec(cString) * * $INCLUDE$ * - * $EnNumber$ + * $END$ */ FUNCTION HexaToDec(cString)