|
<< Click to Display Table of Contents >> Navigation: Concordance Programming Language Reference > Database Information |
The following topics discuss database information and database fields.
A variety of information can be obtained about a database by using the database handle with the information selector and several keywords. Available information includes the number of documents in the database, the field types, length, and names, and the current query number.
Access the information by following the database handle with a period and one of the keywords listed below.
Keyword |
Description |
|---|---|
access |
User’s access rights to the field, read, write, or read-write. Subscript by field number, i.e., db.access[i]. |
activequery |
Current active query. |
database |
Database name. |
documents |
Number of documents in the database. |
edited |
Non-zero if the database needs reindexing. |
fields |
Number of fields defined in the database. |
image |
True if the field is an image key, db.image[i]. |
key |
True if the field is a key field, db.key[i]. |
length |
The defined length of the subscripted field, this returns the left margin of paragraph fields, and the format of date fields, i.e. ‘Y’, ‘M’, or ‘D’ for yyyy/mm/dd, mm/dd/yyyy, or dd/mm/yyyy respectively. |
name |
The name of the subscripted field, db.name[i]. |
order |
The order in which the subscripted field is used by Load, Unload, Global, and other functions. |
places |
Number of places in numeric fields. |
query |
The number of the last executed query. |
type |
The field type of the subscripted field, either T for text, P for paragraph, D for date, or N for numeric fields. |
The access rights variable must be subscripted by the field’s number, i.e. db.access[i]. It contains the following bit settings:
Bit Setting |
End-user Rights |
|---|---|
0 |
no access to this field |
1 |
read permission is granted |
2 |
write permission is granted |
/* Display the names of each database field */ /* in a menu, return the menu choice selected */ info(int db) { int i; text choices[db.fields+1]; choices[0] = "Field Selection Menu"; for(i = 1; i <= db.fields; i = i + 1) choices[i] = db.name[i]; return(menu(5,35,20,55,choices,1)); } |
The access, name, length, places, type, and order entries must be subscripted by the field’s number, as in the example above.
An interesting feature in the preceding example is the use of a calculation to initialize the number of elements in the choices array. This function guarantees that the array will always be large enough by using the parameter, db.fields+1, to calculate the number of elements. Function parameters become valid variables as soon as they are declared. Using parameters to size arrays builds flexibility into your CPL functions.
Databases consist of individual fields which contain varying types of data, including text, numbers, and dates. Individual fields are accessed with the database handle, the field operator ->, and a field indicator. The database handle is any valid integer returned by a call to the opendb() function. A field indicator can be the field’s number, its name, or a character array or text variable containing its name.
Assuming a database’s second field is called AUTHOR, this program would replace the field contents five times, five different ways.
main() { char string[25]; int i, db; string = "Author"; i = 2; if ((db = opendb("catalog")) <> -1) { db->string = "Marlowe"; db->"author" = "O’Glue"; db->AUTHOR = "Turley"; db->2 = "McGee"; db->i = "Stewart"; closedb(db); } } |
When this program finishes, the value of the AUTHOR field will be Stewart. The variety of ways available to access fields provides a high degree of flexibility that should fit all situations. However, the preferred method is db->AUTHOR, with the field name in upper case.
Care should be taken when using the field name without enclosing it in quotes. Ambiguities can occur when variable names match field names. In the above example, if there were a variable called AUTHOR, Concordance would use it to determine the field name. An error would result if the variable contained something other than a valid field name. Worse yet, the AUTHOR variable could inadvertently contain a valid field name resulting in the replacement of the wrong field.