dbAppend()
dbClearFilter()
dbCloseAll()
dbCloseArea()
dbCommit()
dbCommitAll()
dbCreate()
dbDelete()
dbEval()
dbF()
dbFilter()
dbGoBottom()
dbGoTo()
dbGoTop()
dbReCall()
dbRLock()
dbRLockList()
dbRUnlock()
dbSeek()
dbSelectArea()
dbSetDriver()
dbSetFilter()
dbSkip()
dbSkipper()
dbStruct()
dbUnlock()
dbUnlockAll()
dbUseArea()
DecToBin()
DecToHexa()
DecToOctal()
Deleted()
Descend()
DevOutPict()
DirChange()
DirRemove()
DiskSpace()
| AFields | Fills referenced arrays with database field information |
| Alias | Returns the alias name of a work area |
| BOF | Test for the beggining-of-file condition |
| dbAppend | Appends a new record to a database file |
| dbClearFilter | Clears the current filter condiction in a work area |
| dbCloseAll | Close all open files in all work areas. |
| dbCloseArea | Close a database file in a work area |
| dbCommit | Updates all index and database buffers for a given workarea |
| dbCommitAll | Flushes the memory buffer and performs a hard-disk write |
| dbCreate | Creates an empty database from a array |
| dbDelete | Mark a record for deletion in a database |
| dbEval | Performs a code block operation on the current Database |
| DBF | Alias name of a work area |
| dbFilter | Return the filter expression in a work area |
| dbGoBottom | Moves the record pointer to the bottom of the database |
| dbGoto | Position the record pointer to a specific location |
| dbGoTop | Moves the record pointer to the top of the database |
| dbRecall | Recalls a record previousy marked for deletion |
| dbSeek | Searches for a value based on an active index |
| dbSelectArea | Change to another work area |
| dbSetDriver | Establishes the RDD name for the selected work area |
| dbSetFilter | Establishes a filter condition for a work area |
| dbSkip | Moves the record pointer in the selected work area |
| dbSkipper | Helper function to skip a database |
| dbStruct | Builds a multidimensional array of a database structure |
| dbUseArea | Opens a work area and uses a database file |
| Deleted | Tests the record’s deletion flag |
| EOF | Test for end-of-file condition |
| FCount | Counts the number of fields in an active database |
| FieldDeci | Determines the number of decimal places of a given numeric field |
| FieldGet | Obtains the value of a specified field |
| FieldName | Return the name of a field at a numeric field location |
| FieldPos | Return the ordinal position of a field |
| FieldPut | Set the value of a field variable |
| FieldSize | Determines the size of a given field |
| FieldType | Determines the type of a given field |
| Found | Determine the success of a previous search operation |
| Header | Return the length of a database file header |
| LastRec | Returns the number of records in an active work area or database |
| LUpdate | Yields the date the database was last updated |
| RecCount | Counts the number of records in a database |
| RecNo | Returns the current record number or identity |
| RecSize | Returns the size of a single record in an active database |
| Select | Returns the work area number for a specified alias |
| Used | Checks whether a database is in use in a work area |
Return the name of a field at a numeric field location.
Syntax
FIELDNAME/FIELD(<nPosition>) --> cFieldName
Arguments
<nPosition> Field order in the database.
Returns
<cFieldName> returns the field name.
Description
This function return the name of the field at the <nPosition>th position. If the numeric value passed to this function does not correspond to an existing field in the designated or selected work area, this function will return a NULL byte.
Examples
PROCEDURE Main()
LOCAL x
USE tests NEW
FOR x := 1 TO tests->( FCOUNT() )
? "Field Name", FieldName( x )
NEXT
USE
RETURN
Compliance
Clipper
Files
Library is rdd
Seealso
DBSTRUCT(), FCOUNT(), LEN(), VALTYPE()
Fills referenced arrays with database field information
Syntax
AFields(<aNames>[,<aTypes>][,<aLen>][,<aDecs>]) --> <nFields>
Arguments
<aNames> Array of field names
<aTypes> Array of field names
<aLens> Array of field names
<aDecs> Array of field names
Returns
<nFields> 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.
AFIELDS() is a compatibility function, it is superseded by DBSTRUCT() which returns one multidimensional array.
NOTE: The destination arrays must be initialized to a given size, usually FCOUNT(), before calling this function.
Examples
PROCEDURE Main()
LOCAL aNames, aTypes, aLens, aDecs, nCount, nFields, i
USE Test
nCount := FCount()
? "Number of fields:", nCount
PrintFields( nCount ) // Information for all fields
PrintFields( 4 ) // Information for first 4 fields
RETURN
PROCEDURE PrintFields( nCount )
LOCAL aNames, aTypes, aLens, aDecs, nFields, i
aNames := Array( nCount )
aTypes := Array( nCount )
aLens := Array( nCount )
aDecs := Array( nCount )
nFields := aFields( aNames, aTypes, aLens, aDecs )
? "Number of items :", nFields
FOR i := 1 TO nFields
? i, PadR( aNames[ i ], 12 ), aTypes[ i ]
?? aLens[ i ], aDecs[ i ]
NEXT
?
RETURN
Compliance
Clipper
Files
Library is rdd
Seealso
DBSTRUCT()
Creates an empty database from a array.
Syntax
DBCREATE( <cDatabase>, <aStruct>, [<cDriver>], [<lOpen>],
[<cAlias>] )
Arguments
<cDatabase> Name of database to be create
<aStruct> Name of a multidimensional array that contains the database structure
<cDriver> Name of the RDD
<lOpenNew> 3-way toggle to Open the file in New or Current workarea:
NIL The file is not opened.
True It is opened in a New area.
False It is opened in the current area.
<cAlias> Name of database Alias
Description
This function creates the database file specified as <cDatabase> from the multidimensional array <aStruct>. If no file extension is use with <cDatabase> the .dbf extension is assumed. The array specified in <aStruct> must follow a few guidelines when being built prior to a call to DBCREATE():
– All subscripts values in the second dimension must be set to proper values
– The fourth subscript value in the second dimension – which contains the decimal value-must he specified. even 1kw nonnumeric fields.
– The second subscript value in the second dimension-which contains the field data type-must contain a proper value: C, D, L, M or N It is possible to use additional letters (or clarity (e.g., ‘Numeric’ for ‘N’): however, the first letter of this array element must be a proper value.
The DBCREATE( ) function does not use the decimal field to calculate the length of a character held longer than 256. Values up to the maximum length of a character field (which is 65, 519 bytes) are stored directly in the database in the length attribute if that database was created via this function. However, a file containing fields longer than 256 bytes is not compatible with any interpreter.
The <cDriver> parameter specifies the name of the Replaceable Database Driver to use to create the database. If it is not specified, then the Replaceable Database Driver in the current work area is used.
The <lOpenNew> parameter specifies if the already created database is to be opened, and where. If NIL, the file is not opened. If True, it is opened in a New area, and if False it is opened in the current area (closing any file already occupying that area). The <cAlias> parameter specifies the alias name for the new opened database.
Examples
PROCEDURE Main()
LOCAL nI, aStruct := { { "CHARACTER", "C", 25, 0 }, ;
{ "NUMERIC", "N", 8, 0 }, ;
{ "DOUBLE", "N", 8, 2 }, ;
{ "DATE", "D", 8, 0 }, ;
{ "LOGICAL", "L", 1, 0 }, ;
{ "MEMO1", "M", 10, 0 }, ;
{ "MEMO2", "M", 10, 0 } }
REQUEST DBFCDX
dbCreate( "testdbf", aStruct, "DBFCDX", .T., "MYALIAS" )
RETURN
Compliance
This function is not CA-Cl*pper compliant
Files
Library is rdd Header is dbstruct.ch
Seealso
AFIELDS()*, DBSTRUCT()
Create new database file from a structure extended file
Syntax
CREATE <xcFileName> FROM <xcFileFrom> [VIA <xcRDDName>];
[NEW] [ALIAS <xcAlias>]
Arguments
<xcFileName> : is the target file name to create and then open. (.dbf) is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses.
<FROM xcFileFrom> : is a structure extended file name from which the target file <xcFileName> is going to be built. It can be specified as literal file name or as a character expression enclosed in parentheses.
<VIA xcRDDName> : is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses.
<NEW> : open the target file name <xcFileName> in the next available unused work-area and making it the current work-area. If omitted open the target file in current work-area.
<ALIAS xcAlias> : is an optional alias to USE the target file with. If not specified, alias is based on the root name of <xcFileName>.
Description
CREATE FROM open a structure extended file <xcFileFrom> where each record contain at least the following fields (in no particular order): FIELD_NAME, FIELD_TYPE, FIELD_LEN and FIELD_DEC. Any other field is ignored. From this information the file <xcFileName> is then created and opened in the current or new work-area (according to the NEW clause), if this is a new work-area it becomes the current.
For prehistoric compatibility reasons, structure extended file Character fields which are longer than 255 characters should be treated in a special way by writing part of the length in the FIELD_DEC according to the following formula:
FIELD->FIELD_DEC := int( nLength / 256 )
FIELD->FIELD_LEN := ( nLength % 256 )
CREATE FROM command is preprocessed into __dbCopyStruct() function during compile time and uses this mode.
Examples
See example in the CREATE command
Compliance
Clipper
Platforms
All
Seealso
COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate()
Create empty structure extended file
Syntax
CREATE <xcFileName> [VIA <xcRDDName>] [ALIAS <xcAlias>]
Arguments
<xcFileName> : is the target file name to create and then open. (.dbf) is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses.
<VIA xcRDDName> :is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses.
<ALIAS xcAlias> : is an optional alias to USE the target file with. If not specified, alias is based on the root name of <xcFileName>.
Description
CREATE a new empty structure extended file with the name <cFileName> and then open it in the current work-area. The new file has the following structure:
Field name Type Length Decimals
------------ ---- ------ --------
FIELD_NAME C 10 0
FIELD_TYPE C 1 0
FIELD_LEN N 3 0
FIELD_DEC N 3 0
CREATE command is preprocessed into __dbCopyStruct() function during compile time and use this mode.
Examples
// CREATE a new structure extended file, append some records and
// then CREATE FROM this file a new database file
CREATE template
APPEND BLANK
FIELD->FIELD_NAME := "CHANNEL"
FIELD->FIELD_TYPE := "N"
FIELD->FIELD_LEN := 2
FIELD->FIELD_DEC := 0
APPEND BLANK
FIELD->FIELD_NAME := "PROGRAM"
FIELD->FIELD_TYPE := "C"
FIELD->FIELD_LEN := 20
FIELD->FIELD_DEC := 0
APPEND BLANK
FIELD->FIELD_NAME := "REVIEW"
FIELD->FIELD_TYPE := "C" // this field is 1000 char long
FIELD->FIELD_LEN := 232 // 1000 % 256 = 232
FIELD->FIELD_DEC := 3 // 1000 / 256 = 3
CLOSE
CREATE TV_Guide FROM template
Compliance
Clipper
Platforms
All
Seealso
COPY STRUCTURE, COPY STRUCTURE EXTENDED, CREATE FROM, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate()
Copy current database structure into a definition file
Syntax
COPY STRUCTURE EXTENDED TO <xcFileName>
Arguments
<xcFileName> The name of the target definition file to create. (.dbf) is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses.
Description
COPY STRUCTURE EXTENDED create a new database named <cFileName> with a pre-defined structure (also called “structure extended file” ) :
Field name Type Length Decimals
----------- ---- ------ ---------
FIELD_NAME C 10 0
FIELD_TYPE C 1 0
FIELD_LEN N 3 0
FIELD_DEC N 3 0
Each record in the new file contains information about one field in the original file. CREATE FROM could be used to create a database from the structure extended file.
For prehistoric compatibility reasons, Character fields which are longer than 255 characters are treated in a special way by writing part of the length in the FIELD_DEC according to the following formula (this is done internally) :
FIELD->FIELD_DEC := int( nLength / 256 )
FIELD->FIELD_LEN := ( nLength % 256 )
Later if you want to calculate the length of a field you can use the following formula:
nLength := iif( FIELD->FIELD_TYPE == "C", ;
FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ;
FIELD->FIELD_LEN )
COPY STRUCTURE EXTENDED command is preprocessed into __dbCopyXStruct() function during compile time.
Examples
// Open a database, then copy its structure to a new file,
// Open the new file and list all its records
USE Test
COPY STRUCTURE EXTENDED TO TestStru
USE TestStru
LIST
Compliance
Clipper
Platforms
All
Seealso
COPY STRUCTURE, CREATE, CREATE FROM, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate()
Create a new database based on current database structure
Syntax
COPY STRUCTURE TO <xcFileName> [FIELDS <field,...>]
Arguments
TO <xcFileName> is the name of the new database file to create. (.dbf) is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses.
FIELDS <field, …> is an optional list of field names to copy from the currently open database in the specified order, the default is all fields. Names could be specified as uppercase or lowercase.
Description
COPY STRUCTURE create a new empty database file with a structure that is based on the currently open database in this work-area.
COPY STRUCTURE can be use to create a sub-set of the currently open database, based on a given field list.
COPY STRUCTURE command is preprocessed into __dbCopyStruct() function during compile time.
Examples
// Create a new file that contains the same structure
USE TEST
COPY STRUCTURE TO MyCopy
// Create a new file that contains part of the original structure
USE TEST
COPY STRUCTURE TO SomePart FIELDS name, address
Compliance
Clipper
Platforms
All
Seealso
COPY STRUCTURE EXTENDED, DBCREATE(), DBSTRUCT(), __dbCopyStruct(), __dbCopyXStruct(), __dbCreate(), __dbStructFilter()
Template
Function
Name
__FLedit()*
Category
API
Subcategory
Database
Oneliner
Filter a database structure array
Syntax
__FLedit( <aStruct>, [<aFieldList>] ) --> aStructFiltered
Arguments
<aStruct> is a multidimensional array with database fields structure, which is usually the output from dbStruct(), where each array element has the following structure:
Position Description dbstruct.ch
-------- ----------- -----------
1 cFieldName DBS_NAME
2 cFieldType DBS_TYPE
3 nFieldLength DBS_LEN
4 nDecimals DBS_DEC
<aFieldList> is an array where each element is a field name. Names could be specified as uppercase or lowercase.
Returns
__FLedit() return a new multidimensional array where each element is in the same structure as the original <aStruct>, but the array is built according to the list of fields in <aFieldList>. If <aFieldList> is empty, __FLedit() return reference to the original <aStruct> array.
Description
__FLedit() can be use to create a sub-set of a database structure, based on a given field list.
Note that field names in <aStruct> MUST be specified in uppercase or else no match would found.
SET EXACT has no effect on the return value.
__FLedit() is a compatibility function and it is synonym for __dbStructFilter() which does exactly the same.
Examples
LOCAL aStruct, aList, aRet
aStruct := { { "CODE", "N", 4, 0 }, ;
{ "NAME", "C", 10, 0 }, ;
{ "PHONE", "C", 13, 0 }, ;
{ "IQ", "N", 3, 0 } }
aList := { "IQ", "NAME" }
aRet := __FLedit( aStruct, aList )
// { { "IQ", "N", 3, 0 }, { "NAME", "C", 10, 0 } }
aRet := __FLedit( aStruct, {} )
? aRet == aStruct // .T.
aList := { "iq", "NOTEXIST" }
aRet := __FLedit( aStruct, aList )
// { { "IQ", "N", 3, 0 } }
aList := { "NOTEXIST" }
aRet := __FLedit( aStruct, aList ) // {}
// Create a new file that contain part of the original structure
LOCAL aStruct, aList, aRet
USE TEST
aStruct := dbStruct()
aList := { "NAME" }
dbCreate( "onlyname.dbf", __FLedit( aStruct, aList ) )
Compliance
CA-Cl*pper has internal undocumented function named __FLedit(), in Harbour we name it __dbStructFilter(). The new name gives a better description of what this function does. In Harbour __FLedit() simply calls __dbStructFilter() and therefor the latter is the recommended function to use.
This function is only visible if src/rdd/dbstrux.prg was compiled with the HB_CLP_UNDOC flag.
Platforms
All
Files
Header file is dbstruct.ch
Library is rdd
Seealso
dbCreate(), dbStruct(), __dbCopyStruct(), __dbStructFilter()
Viva Clipper ! 