|
<< Click to Display Table of Contents >> Navigation: Concordance Programming Language Reference > Functions > B |
The following topic discusses the Concordance Programming Language (CPL) functions that begin with the letter B. For more information on CPL functions, see Functions, About the Advanced Programming Features, and About CPL Functions.
beep(int frequency, duration); |
•Description - Emits a tone from the PC's speaker. Frequency is a value in hertz. Duration is the length of time in thousandths of a second. Beep will not make a sound if the beep option on the Set menu is disabled.
•Return Value - None.
Example
main() { int i; /* Sound a siren, up scale and down scale. */ /* Use a for-loop for the up scale tone, a */ /* while loop for the down scale tone. */ for(i = 450; i < 550; i = i + 1) beep(i,5); while(i > 450) beep(i = i - 1,5); } |
blank(int db); |
•Description - Clears a document at the end of the file. The current document is not affected. Once a document is cleared it can be edited and appended to the database.
•Return Value - None.
•See Also - append()
Example
main() { int db1, db2, i; /* Copy records to another database. */ db1 = opendb("recipes"); db2 = opendb("cooking"); /* Get a blank document. ** Copy the individual fields. ** Append the new document. ** Get the next record to copy. */ cycle(db1) { blank(db2); for(i = 1; i <= db1.fields; i = i + 1) db2->i = db1->i; append(db2); } /* All done, close the databases. */ closedb(db1); closedb(db2); } |
box(int row, col, brow, bcol, format, [color,[background]]); |
•Description - Displays a box at the location described by the screen coordinates of the upper left corner and the lower right corner. The area inside the box is not cleared. Format is either 'S' or 'D', for a single line box or a double line box, case is ignored. If the format is SD or DD the box is created with a drop shadow, the dimensions of the box are decreased by two columns and one row for placement of the shadow. Drop shadows are not available in the Windows version, but the extra line and columns are accounted for before the box is drawn.
oWindows will display a raised 3-D box if the 3U format style is selected and a depressed 3-D box if the 3D format style is selected. The background color is used to fill the box. A 3D box will produce a DD box in non-Windows versions of Concordance.
oThe color and background color parameters are optional. Color selected for normal text is used if the color parameter is left off. The background color is only used for Windows.
•Return Value - None.
•See Also - scroll()
int browse(int db); |
•Description - Invokes the Concordance full screen browse mode. Browse will display the current document in the current query. The screen is automatically saved before entering this mode and restored after exiting.
•Return Value - The key pressed to exit Browse mode. Either the [Esc] key or a function key.
•See Also - table()
Example
main() { int db; db = opendb("recipes"); if (db == -1) { puts(0,0,"Can't open recipes."); getkey(); } else { search(db, "chocolate"); browse(db); closedb(db); } } |
int btclose(int handle); |
•Description - Closes the dictionary file associated with handle.
•Return Value - btclose returns 0 if successful, or -1 if an error was encountered.
•See Also - btopen(), btcreate()
Example
ShowCount() { int i; i = btopen("recipes.dct"); if (i == -1) puts(0,0,"Couldn't open the dictionary"); else { puts(0,0,"There are "+ str(btcount(i),6,0)+ " words.",); btclose(i); } } |
int btcount(int handle); |
•Description - Returns a count of the number of keys in the file. Handle must be a valid handle returned by a call to btopen() or btcreate().
•Return Value - The count of keys in the file, or -1 if an error occurs.
•See Also - btopen(), btcreate()
int btcreate(char string[]; int duplicate); |
•Description - Creates a new dictionary for use, will not erase or open an existing file. If duplicate is a nonzero value, duplicate key values will be allowed in the file. A zero value will reject duplicate keys.
oThe duplicate parameter is stored with the dictionary and will remain active when the file is reopened later. It cannot be changed once the file is created.
•Return Value - btcreate() will return a file handle if successful, a -1 if it was unable to create the file. Reasons for failure are the file already exists, bad file name or directory path, diskette write protected, disk full.
•See Also - btopen(), btclose()
int btcycle(int file, dbHandle; text expression); |
•Description - Cycles through the database using the current query. Evaluates expression for each document in the database and inserts the result into the dictionary whose handle is file. The document's number is stored as the data value. The result of expression must be a text value.
oThe expression can be a database field, db->NAME, or a quoted string for evaluation, "pad(db->NAME,'L',40)+str(db->DATE)". The function will run faster with a simple field than it will with a quoted parameter that requires evaluation. Fixed fields will run the fastest.
•Return Value - The number of entries placed into the dictionary. This number may not be the number of documents in the current query if duplicates are not allowed in the dictionary.
Example
ShowUniqueEntries(int db) { char string[80]; int document; int dict = btcreate("erase.me",0); /* Create the list and show entries in a menu. */ btcycle(dict,db,db->AUTHOR); while(btmenu(dict,7,0,22,79,"Authors",string,document)) { /* Load the selected document and browse. */ goto(db,document); browse(db); /* Get field to display at top of btmenu(). */ string = trim(db->AUTHOR); } btclose(dict); erase("erase.me"); } |
int btdelete(int file; char key[]); |
•Description - Deletes the matching key from the dictionary.
•Return Value - A 0 if successful, a -1 if not successful. Returns a -1 if the word was not in the file.
Example
remove(int btree; text string) { int key; text line; /* Enclose string in quotes and ask */ /* if the user is sure they want to */ /* delete it from the file. */ line = 'Delete "'+string+'"?'; puts(0,0,line); cursor(0,len(line)+1); key = getkey(); if ((key == 'Y') or (key == 'y')) btdelete(btree,string); } |
int btexact(int file; char key[]; int data); |
•Description - Locates a matching entry in the file. The entry must match both the key value and the data value.
•Return Value - A zero if the entry was found, a nonzero value if an exact match could not be located.
•See Also - btfirst(), btfind(), btgte(), btgt(), btlt(), btlast()
int btfind(int file; char key[]; int data); |
•Description - Locates the word and, if found, returns the associated integer value in data. The file handle must be a valid handle returned by a call to either btopen() or btcreate().
•Return Value - The value of btfind() is 0. If the word was not in the file, the value of btfind() is -1.
•See Also - btexact(), btfirst(), btgte(), btgt(), btlt(), btlast()
int btfirst(int file; char key[]; int data); |
•Description - Locates the first word in the dictionary file and returns its integer value in "data." The word is returned in key[], key[] must be large enough to hold the retrieved word.
•Return Value - The value of btfirst() is 0. If the file is empty, the value of btfirst() is -1.
•See Also - btlast()
int btgt(int file; char key[], buf[]; int data); |
•Description - Locates the dictionary entry greater than the search key. The word is returned in buf[], buf[] must be large enough to hold the retrieved word.
•Return Value - A value less than zero if an error occurs, or if there is no value greater than the search key. If an entry is found, the entry is returned in buf[], its associated numeric value is returned in data.
int btgte(int file; char key[], buf[]; int data); |
•Description - Locates the dictionary entry greater than or equal to the search key. The entry is returned in the buf[] variable, and the key's value is returned in data.
•Return Value - A -1 if an error occurs.
•See Also - btgt(), btlt(), btfind()
int btinsert(int handle; char key[]; int data); |
•Description - The key value is inserted into the dictionary along with the numeric value in data.
•Return Value - A 0 indicates success, a value less than 0 indicates an error. If a negative value is returned, it may indicate either a disk full condition or a duplicate key value if duplicate keys are not allowed.
•See Also - btcreate(), btinserta(), btopen(), btclose()
Example
update(char string[]; int handle) { int UpperCase; /* Assume lower case word. */ UpperCase = 0; if (isupper(string[0])) { /* Capitalized word. */ UpperCase = 1; if (isupper(string[1])) /* Mixed case word. */ UpperCase = 2; } /* Insert word in upper case, but */ /* store the case indicator as the */ /* data value. This can be used */ /* later in a spell check program. */ return(btinsert(handle, upper(string), UpperCase)); } |
int btinserta(int handle; char key[]; int data); |
•Description - The key value is inserted into the dictionary, however the dictionary will assume that what you are inserting is already sorted in ascending order. It will use an insertion scheme that optimizes for ascending order insertion and will produce a more compact dictionary.
•Return Value - A 0 if the key was successfully added to the dictionary, a -1 if it was not.
•See Also - btinsert(), btcreate(), btopen()
Example
main() { int OldError, NewError, old, new, data; char buffer[60]; new = btcreate("temp.xyz",0); old = btopen("oldfile.xyz"); /* Read the existing dictionary and insert */ /* all data into the new dictionary. */ NewError = 0; OldError = btfirst(old,buffer,data); while((OldError <> -1) and (NewError <> -1)) { NewError = btinserta(new,buffer,data); OldError = btnext(old,buffer,data); } /* If the key counts are not the same in ** both files it means that an error occurred ** at some point, probably a full disk. */ if (btcount(old) <> btcount(new)) NewError = -1; /* Close the files and finish. */ btclose(old); btclose(new); if (NewError == -1) { puts(0,0,"Error in new dictionary."); puts(1,0,"Disk may be full."); erase("temp.xyz"); } else { erase("oldfile.xyz"); rename("temp.xyz","oldfile.xyz"); } } |
int btlast(int handle; char key[]; int data); |
•Description - Read the last entry in the dictionary, return the entry and its numeric value. The file is left positioned on the last entry after this call. A series of btprev() calls would then read the file in descending alphabetical order.
•Return Value - A 0 if successfully read, a nonzero value if there was an error.
•See Also - btfirst(), btprev(), btnext()
int btlock(int handle); |
•Description - Locks the btree file for exclusive use. All other network users are prevented from accessing the file. The file should be unlocked as quickly as possible to ensure access for other network users.
•Return Value - Returns a nonzero value if the file could not be locked.
•See Also - btunlock()
int btlt(int handle; char key[], buf[]; int data); |
•Description - Locates the key entry less than the passed key. If an entry is found, it is returned in buf[] with its associated numeric value returned in data. The character string buf[] must be large enough to hold the returned value.
•Return Value - Returns a -1 if an error occurred.
int btmenu(int handle, row, col, brow, bcol; char title[], key[]; int data[, text action); |
•Description - Displays the contents of the dictionary whose handle was returned earlier by a call to btopen() or btcreate(). The key values are displayed in a menu window. The title string is displayed at the top of the window.
oThe user can cursor through the dictionary, or type the letters of the word for lookup. As the letters are typed, btmenu() will display the list of words that match most closely.
oThe action parameter is optional. "U" or "u" converts all of the user's typed input to upper case. An "L" or "l" converts the input to lower case. Specifying an "E" or "UE" or "LE" enables the Insert and Delete buttons in the Windows version.
oThe user can select the current word by pressing the [Enter] key. btmenu() will copy the selected word to the key[] parameter, and the word's associated numeric value to the data parameter.
oIf the user presses [Ctrl-Enter], btmenu() will copy the word they are typing on the prompt line to the key[] parameter. Windows users should pass the "E" parameter mentioned above.
oIf key[] contains a value when btmenu() starts, then the key greater than or equal to that key becomes the first key displayed on the screen.
•Return Value - A value of -1 indicates an error in the dictionary file.
oA 0 return value indicates that the user pressed [Esc] to exit without making a selection.
oA 1 indicates that the user pressed [Enter] to select a key, that key is returned in the key[] and data parameters.
oA 2 indicates that the user pressed [Ctrl-Enter] to select the value they were entering on the prompt line, in this case key[] will contain the prompt line string.
int btnext(int handle; char key[]; int data); |
•Description - Locate the next entry in the file. The key and data parameters are set to the value of the key.
•Return Value - A -1 is returned if there is no next key.
•See Also - btprev(), btfirst()
int btopen(char string[]); |
•Description - Open a dictionary file for use.
•Return Value - -1 if the file cannot be found, or if it is not recognized as a valid dictionary file.
•See Also - btclose(), btcreate()
int btprev(int handle; char key[]; int data); |
•Description - Locates the previous entry in the file and returns it in key, and its numeric value in data.
•Return Value - A -1 is returned if there is no previous entry.
•See Also - btlast(), btnext(), btfirst()
int btrebuild(text filename); |
•Description - The btree file named by filename is converted to a Concordance 8 b+tree with 64-bit data values. The old b+tree is renamed with the .old file extension. The file must be closed for the conversion to work.
oAfter the conversion, only Concordance V8 or later can open the b+tree.
•Return Value - A -1 is returned if the file is open or if it is not a b+tree, otherwise the number of keys in the converted b+tree is returned.
•Version - Concordance version 8 and later.
int btunlock(int handle); |
•Description - Unlocks the file allowing other network users to access it. A file must be unlocked exactly as many times as it was locked to completely release it.
•Return Value - A nonzero value if an error occurred while unlocking the file.
•See Also - btlock()