One of the most powerful abilities in CPL is the ability to read and write information stored in a field.
|
If you are ever going to write a CPL that writes data back to a field, remember to make a back up copy of your database.CPL is a very powerful tool and a simple mistake can cause complex headaches. However, note that Concordance database security is enforced in CPL. If the user running the CPL does not have read privileges to a particular field, instead of retrieving the data, Concordance will return nothing. |
Referencing a database field
The previous section described how to use a period (.) to access database structure information. In order to access the information contained in a field, you must use a notation called a pointer, which is a minus sign (-) followed by a greater-than sign (>).
To access a database using a pointer
1.Start with the database handle.
int db |
2.Place the pointer directly after the database handle.
db-> |
3.Type the name of the field directly after the pointer.
db->OCR |
Note that you can access fields in a variety of ways.
•You can access fields directly by spelling out the field name in ALL CAPS. If the field does not exist, CPL will give you an error. The following examples access the OCR and FIRST_NAME fields.
db->OCR db->FIRST_NAME |
•You can also use an integer value to indicate the numerical order of the field to access. The following example uses an integer variable to access the third field in a database.
int x; x = 3; db->x |
•You can also use text variables. The following example uses the myField string to access a field.
text myField; myField = "OCR"; db->myField; |
Identifying field types
Before you retrieve information out of a field, you must know the type of information the field contains. For example, you would not want to store the information from a text field into an integer variable.
The following sample code shows how to identify the type of information a field contains.
main() { int db, numericVariable; text textVariable;
for (i = 1; i <= db.fields; i = i + 1) { switch(db.type[i]) { case 'P': case 'T': textVariable = db->i; break; case 'N': case 'D': numericVariable = db->i; break; } } } |
1.The first two lines are the variable declarations, which tell the CPL interpreter that you will use these variables:
int db, numericVariable; text textVariable; |
2.The next section is a for-loop.
for (i = 1; i <= db.fields; i = i + 1) |
i.The initialization statement starts i as 1; the test condition checks if i is less than or equal to the number of fields in the database; the loop increments i by one. Recall that database fields start at 1 (rather than 0).
3.The next section of code is a switch-statement, which contains the type of the current field.
switch(db.type[i]) |
4.The next few statements are the case-statements.
i.Note that the code combines the case-statements for paragraph fields and text fields (P and T). This is done by not including the keyword, break, in between the case-statements. Depending on the field type, you set the value of a text variable or numeric variable to the contents of the field.
textVariable = db->i; -or- numericVariable = db->i; |
ii.You use the variable i to grab the contents of field i. If i equals 2, then db->i would equal the contents of field 2. This is an example of assigning a variable to the value of your field.
Assigning a value to a field
Once you have confirmed the type of information that a field contains, you can modify that information.
To set the contents of a field
Use a pointer to reference a field, and then assign a value as you would a variable.
The following example sets the COMPANY text field value to "CloudNine, Inc."
db->COMPANY = "CloudNine, Inc."; |
As with other fields, you can access a field through a numerical variable. The following example modifies the 3rd field in a database:
int n; n = 3; db->n = "CloudNine, Inc."; |
Here are you simply “assigning” a value. Remember the left side of the equals sign is the object you are storing information into. The following example stores the value of x into a field called PAGES.
db->PAGES = x; |
Note you are not storing the letter “x” in the PAGES field. You are also not storing the value stored in the PAGES field into the variable x.
|
You can severely damage your database by assigning a value to it. For example, the following code deletes all data in a field:
|
Current record
The current record refers to the record that Concordance is interacting with. By default, this is usually the record being displayed in the UI. However, accessing multiple records may be more useful than accessing just one. For example, you may want to access all records in a database. In the UI, you would simply press the Next button, and continue with your work. This topic discusses how to access multiple records.
There are several ways to change the current record to a new record, using the following built-in functions:
•next(int db) - Using the database handle, the next command can move CPL to the next record in the database
•prev(int db) - Pass the database handle to this function to move CPL to the previous record in the database.
•goto(int db, document) - Pass a database handle along with a document number in the current query to move CPL to a particular document in the current query.
You can also use search features to locate additional records. For more information, see Searching Databases.
The following example opens a database and goes to field number 42.
main() { db2 = opendb("c:\temp\support.dcb"); goto(db2, 42); } |