Concordance® Programming Language User Guide

Copyright

Copyright
LexisNexis and the Knowledge Burst logo are registered trademarks of Reed Elsevier Properties Inc., used under license. Concordance is a registered trademark and FYI is a trademark of Reed Elsevier, Inc. Other products or services may be trademarks or registered trademarks of their respective companies. © 2009 LexisNexis, a division of Reed Elsevier, Inc. All rights reserved.

Additional Resources
For additional help and support, please contact:

▪ ▪ ▪

General Product Information: http://law.lexisnexis.com/concordance Concordance Technical Support: phone: 866-495-2397, email: concordancesupport@lexisnexis.com Concordance Training: phone: 425-463-3503, email: concordancetraining@lexisnexis.com

151208CPLUG10.00

Concordance® Programming Language User Guide

i

Contents

Contents
Introduction ................................................................................................................................................. 1
Program Files .............................................................................................................................................. 1

Function Declarations ............................................................................................................................. 2
Function Parameters .................................................................................................................................. 2

Return Statement....................................................................................................................................... 3 Variable Declarations and Scope ....................................................................................................... 3
Scope ............................................................................................................................................................ 3

Identifiers ...................................................................................................................................................... 4 Data Types .................................................................................................................................................... 4
Arrays ........................................................................................................................................................... 5

Reserved Words and Symbols ............................................................................................................ 5 System Variables ....................................................................................................................................... 5 Operators and Operands........................................................................................................................ 6
Arithmetic Operators................................................................................................................................... 6 Assignments ................................................................................................................................................ 7 Bitwise Operators........................................................................................................................................ 7 Conditional Operator .................................................................................................................................. 7 Character Literals and Quoted Strings .................................................................................................... 8 Comments .................................................................................................................................................... 8 Database Information ................................................................................................................................. 9 Database Fields ........................................................................................................................................ 10 Logical Operators...................................................................................................................................... 11 Precedence of Operators and Order of Evaluation.............................................................................. 11 Relational Operators................................................................................................................................. 12

Program Flow and Control Structures ........................................................................................... 12
Begin and End ........................................................................................................................................... 12 Break........................................................................................................................................................... 13 Cycle Loops ............................................................................................................................................... 13 For Loops ................................................................................................................................................... 13 If-Else Statement ...................................................................................................................................... 14 Switch Statement ...................................................................................................................................... 14 While Loops ............................................................................................................................................... 15

Functions by Category.......................................................................................................................... 16
Annotations ................................................................................................................................................ 16
Concordance® Programming Language User Guide

ii

............................................................................................................................... 37 btdelete ........................................................................................................................................................................................................................................................................................................................................................................................... 27 accession ............................................................................................................................................................ 35 btclose .................................... 37 btcycle.................................................................................................................................................................................................................................................................................................... 33 beep ............................................... 39 btgte ...................................................................................................................................................................................................................................................................................................................................................................................................................... 42 Concordance® Programming Language User Guide iii .... 18 Dictionary Btree List Management ................................................................................................................................................................................................................................................................................... 23 System ....................................................... 24 Text Manipulation and Classification ................ 29 annotationGoto ... 34 box...................... 30 annotationIsTagged ......................................................... 28 annotationAppend ......................... 18 Data Editing .................................................................................. 19 Dynamic data exchange ........................................................................................................................................................ 38 btfind ......... 27 Functions .. 41 btlast ....................................................................................................................................................................................................................................................................................................................................................................... 27 addr ................................................................................................................................................................... 32 asc ................................................................................................................ 21 Query and Record Management ............................................................................................................................................................ 33 blank ....................................................................................................................................... 30 annotationRetrieve .............................................................................. 35 browse ................ 31 annotationUpdate........................................................................................................................................................................................ 28 annotationCount .............................................................................................................................Contents Database ....................................................................................................................................................................................................... 20 Math .................................................................................................................................................................................................................................................................................................................................................................................................................................... 36 btcount ........................................................ 39 btfirst ...................................................................................................... 36 btcreate............................................ 16 Data Conversion ................................................................................................................................................................................................................................................................................................................................................... 38 btexact .............................................................................................................. 25 Time ........................................................................................................................................................................................................................... 21 Screen Control ........................................................................................................................................................................................................................................... 20 File Handling ......................................................................................................................................................................................................... 31 append ............................................................................................................................................................................................... 40 btinserta ................................................................................... 29 annotationDelete ......................................................................................................................................................................... 40 btinsert ...... 30 annotationTag............................................................................................................................................................................................................... 39 btgt ........

..................................................... 49 createfs ........................................................... 53 dc ........................................................ 47 cls ......................................................................................................................................................................................... 51 cursor .....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................Contents btlock.......................................................................................................................................... 43 btprev ....... 53 day................................................. 45 chr ................................................................................................................................................................................................. 47 closedb ............................................................. 49 createdb ....................................................................................................................................................................... 57 deleteText ................................................................................................................................... 44 btunlock ................................................... 46 close ........................................................................................................................................................................................................................................................................................................ 53 cut. 56 ddeRequest......................................................................................... 54 ddeDisconnect ............................................................................................................................................................................... 60 Concordance® Programming Language User Guide iv ............................................................ 56 debug ............................................................................................................................................................................................................................... 44 ccol ............................................................................................................................................................ 48 concatclear ..................................................................................................................................... 44 capitalize .............................................................................. 51 ctod ................................................................ 47 concat ............................................................... 52 cursoron.......................................................................... 48 count ............................................................................................................................................. 58 diskspace ............................................................................................................................................................................................. 43 btopen ....................................................................................................... 59 dtoc ..... 46 clock ................................................................................................................................................................................................................................................................................................................................................................................................... 55 ddePoke ........................................................................................................................................................................... 57 deleted ....................................................................................................................................................................................................................................................... 51 crow............................................................................................................................................................................................................................................................................... 54 ddeConnect...... 45 chdir ................................................................................................................................................................................................................................................................................................................................. 58 docno .............................................................. 57 delete ........................................................................................................................................... 42 btlt ........................................................................ 42 btnext ............................................................................................................... 55 ddeExec ................................................................................................................................................................................................................................................................................................................................ 52 cursoroff............................................................................................................................................................................................................................. 42 btmenu ................................................................. 50 createReplica ....................................................................................................................................................................................................................................................................................................................................................................................................................................... 59 edit................................................................................................................

.. 70 func ....................................................... 66 findline .................................................................................................................................................... 73 getenv ......................................................... 79 gotouuid ............................................................. 68 findpline .. 82 insertText........................................................................................... 83 isdigit .... 63 erase ..................................................................................................................... 83 isdeleted ........................................................................................... 84 isfield ..................................................................................................................................................................................................................... 73 getfile .......................................................................................................................................................................................................................................................................................................................................... 78 global ........................................................................................................................ 68 findnline .................. 65 exit .................................................................................................................. 74 getline ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 82 isalnum ....... 69 first................................................................................................................................................................................. 64 exec......................................................................................................... 78 goto ............................................................................................................................................................................................................... 84 isedited ............................................................................................................................................................................................................................. 85 Concordance® Programming Language User Guide v .......................................................................................................................................................................................................................................................................................................................... 79 gotophysical ............................................................................................................................................................................... 76 gettags ........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................Contents edited .................................................................................................................. 75 getnumber ....................................................................................................................... 72 getcwd ..................................................................................................... 65 exist .................................................................................. 83 isalpha ................................................... 82 index ................................................................................................................................................................. 80 import ................................................................................................................................................................................... 74 getkey ........................................................................................................................................................................................... 63 eval ............................................................................................................................................................................................................................................................................................................................. 63 editfs ...... 70 fuzzy .................. 84 islower............... 77 getuuid ................................................................................................................................................. 76 getPrivateProfileString .......................................................................................................... 71 getarg ......................................................................................................... 81 importfs ............................................................................................................................................................................................................................................................................................................ 80 hits .................................................. 67 findnext .................................... 66 findfirst ................................................................................................................................................................................... 79 gotoaccession...................................................................................................

............................................................................................................................ 89 load ...................................................................................................................................................................................................................................................................................................................................................................................................................................................... 93 mapDevice ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 97 memset ............................................................................................... 90 lockdb ........ 104 opendb .. 91 lower ......................................................... 92 lseek .............................. 98 messageBox ........................................................................................... 88 len ................ 86 itoa............................................................................ 104 open . 96 memavl ......................................................................................................................................................................................Contents isnexthit ..................................................................................................................................................................................................................................................................................... 105 overlayfs ............................................................................................................................................... 86 istagged ................................................................................................................................................. 101 netuser ............................................................................................................................................................................. 95 matchc ................................................................................................................................................................................................................................................................................................................................................................... 94 match ....................................................................... 100 mkdir ................................................................................................................................ 87 keep ....................................................................................................................................................................... 87 keypress ..................................... 86 isupper ......................................................................................................................................................................................................................... 99 min........................................................................................................................................................................................................................................................................................................................... 105 operator ............................................... 101 month .............................................. 103 num ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 97 menu .................................................................................................................................................................................................................................................................................................................................................. 93 markhits .................................................................... 101 modify ................ 102 next ............................................................................................................................................................................................................. 103 onexit ................................................................................................................................................................................................................................................................. 103 not ........................... 102 nexthit ....................... 105 Concordance® Programming Language User Guide vi ..................................................................................................................................................................................................... 96 memcpy ..................................................................................................................................................... 85 isspace .................... 95 max ............... 89 loadfs ...................................................................................................... 91 lockdoc ............................... 102 newline ............................................................... 91 locked ............................................................................ 93 ltrim ........................................................................................................................................................................ 88 last ........................................................................................................................................................................................

.......................................................................................................................................... 129 sleep ...................................................................................................................................................................................................................................... 106 paste .............................................................................................................................................................................................. 107 prevhit ........................................................................................................................ 110 query .......................................................................................................................................... 119 resolve ... 123 scroll ................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ 123 save................................................................................................................. 116 replicate ..................................................... 114 recall .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 112 rand .................................................... 107 prev ........ 122 round ..................................................................................................... 108 program ............................................................................................................................................................... 125 selectfs ............................................................................................................................ 120 restore..................................................................... 113 readdoc....................................................................................................................................... 110 putsl........................................................................ 106 pad ................................................................................................................................................................................................................................................................................................................................................................................ 121 rmdir ................................................................................. 122 rtrim ........................................................................................................................................................................................................................................................ 122 run .......................... 109 putenv ........................................................................................................................... 112 readc .................................................................................................................................................................................................................................................................................. 124 search .... 126 show ...................................................................... 109 puts ........................................................................................................................................................... 114 readln ........................................ 130 Concordance® Programming Language User Guide vii ................. 111 queryString .... 115 reindex .............................................................Contents pack................................................................................................................................................................................................................................................... 114 recno ......................................... 116 report..................................................................... 129 sizeof................................................................................................................................................................................................................................................................................................ 124 select................................................................... 108 printfs .......................................................................................................................... 118 reportfs ...................................................................................................................................................................................................................................................................................................................................... 125 shellExecute ........................................................................................... 116 rep .......................... 107 print .............................................................. 115 rename ................................................................. 112 read ................... 125 set........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................

...................................... 135 time ............................................................................................................. 131 sqrt ...................................................................................................................................................................................................... 143 zap.. 142 year ............................................................................................................................................ 134 tag ............................................................................................................................................................................................................................. 137 unload ...................................................................... 132 str..................................................................................................... 139 unlockdoc ............................................................................................................................................................................................................. 140 weekday ........................................................................................................................... 135 tagquery ................................................................................................................................................................................................. 140 wordlen ....................................................................................................................................................................................................................................................................................... 133 substr .................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 139 unmapDevice ........................................................................................................................................... 133 system .................... 141 writec.............................................................................................................................................................................. 143 Concordance® Programming Language User Guide viii ............................................................................................................................................................................................................ 136 trim ............................................... 135 today ................ 140 ver ....................................................................................................................................... 139 upper ....................... 134 table ................................................................................................... 142 writePrivateProfileString.............................. 141 write......... 141 wrap ................................................ 138 unlockdb ........................................................................................................................................................................................................................................................................ 132 struc .......................................................... 142 writeln ....................Contents snapshot ................................................................................... 130 spawn .................................................................................................................................................................................................................................................................................... 137 unloadfs ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 130 sort .........................................................................................................

Concordance® Programming Language User Guide 1 . including the CPL or CPT file extension. values it will receive when it begins. Program syntax and features are discussed in detail in the following pages. When Concordance has finished running a program. } The example program begins execution with the main() function. Example int color. world”. numbers. main() { char string[20]. color = 15. The next time you run the program. and predictable program flow. Program Files Concordance programs are stored in plain text files with the file extension CPL. Program instructions are organized in functions. CPL programs are stored in files with the . For a list of CPLs installed with Concordance. CPT files run faster than CPL files and can be run from the command line like a CPL file. designed for users who are familiar with a structured language. you must include the full program name. text. Its features promote clear and concise program design through the use of modularity. value returning functions. characters. A CPL program consists of a sequence of instructions that tells Concordance how to solve a particular problem. show(10. Program files are edited with the Edit Program option on the Concordance File menu.Introduction Introduction The Concordance Programming Language (CPL) is a structured language in the C/Pascal family. 20. Concordance will run the CPT file if it has a date and time later than the CPL file. CPT files cannot be edited or modified with a text editor. main() assigns a value to the global variable color. This example illustrates the structure found in a typical CPL program. However. If you use the command line method. This manual. The program will usually contain some amount of data. Programs are run either by selecting Begin Program from the File menu or by including the program name on the command line when you start Concordance. and dates. column. and the local variables it will use while it is running. local and global variables. char xyz[]) { puts(row. In CPL the data can be database fields. column. describes CPL. see "Supported CPLs" in Concordance Help and User Guide. return. string = “Hello.CPL file extension. } show(int row. Concordance will consecutively run as many programs as you include on the command line. CPL function declarations establish the name of the function. string). it saves an optimized version of the file to disk with the CPT file extension. color). You can edit these files with any text editor or word processor that creates plain text files in ASCII format. and to its local variable string. xyz. It then calls a second function show() to put the string on the screen.

main() may then call other functions for help in executing the program. and go away when the function finishes. float b) { float x. Functions facilitate complex programs by breaking them into small. Function Parameters Parameter declarations appear within the parentheses following the function’s name. Every CPL program must have a main() function. It is executed by Concordance. Multiple parameter declarations can be separated by commas if they are of the same type. Functions use discreet local variables that come into existence when the function runs. CPL program execution always begins with a function called main. easy to manage tasks. } Concordance will convert all parameters passed to max() into float types if necessary. Parameters are declared exactly as all other variables are declared. if (a > b) x = a. by stating their type followed by their names. A statement that uses max() might look like this: salary = salary * max(1. Example max(float a. initialized to their passed values and accessible only within max(). b) with the same effect. The function parameters could also have been declared max(float a. Since a and b become local variables. max() returns the largest of the two parameters passed. return(a). b) { if (a < b) a = b.raise).Function Declarations Function Declarations Syntax name(optional parameters) { statements } A CPL function consists of a group of program statements that perform a job. CPL functions can call other functions to perform work without worrying how they do their jobs. or by semicolons for different type declarations. } Concordance® Programming Language User Guide 2 . else x = b.5. Functions can optionally return values. max(float a. return(x). max() can be rewritten without local variable x.

In all other cases a called function gets a copy of the parameter. ch. are terminated by a semi-colon. In this instance the receiving function can modify the original data.Return Statement Return Statement The value computed by max() is returned by the return statement. c[1]. z. all variables start with the initial value of zero. Local variables come into existence when the function is active and disappear when the function returns. Globally declared variables are visible and accessible to all functions. and simpler to maintain. int x. but no value will be returned. Any value can be computed within the return statement’s parentheses. c[0] = 3. count. All variables must be declared before they are used. Arrays are passed by name alone. CPL functions can contain multiple return statements. Local variable declarations must take place immediately following a function’s opening { brace and prior to the first executable statement. without subscription. y = 2. char string[20]. Variable names can be any CPL identifier. WayDownTheRoad. Example something() { int a[1].b. Variable declarations.c[0]). are visible and accessible only to the declaring function. This makes the function easier to understand. b. Variable Declarations and Scope Variables are declared by stating their type followed by their name. Return statements are optional. maximum = 25. /* a[0] now contains 5 /* b still contains 2 /* c[0] still contains 3 } */ */ */ Concordance® Programming Language User Guide 3 . Optionally. Local variables. a single return statement at the end of the function is preferred. Scope Global variable declarations must take place outside any function declaration. b = 2. a[0] = 1. Several variables of the same type can be declared at once by stating their names separated by commas. int i. like all CPL statements. The one exception to this is when a function passes a locally declared array to another function. a function without one will return automatically when the closing end statement is encountered. By default. However. Local variables can only be accessed by the function that declared them and only while it is executing. nothing(a. they can be declared and initialized in the same statement. not the original variable. A return statement without the parentheses will cause the function to finish. those declared between a function’s opening { and closing } braces.

text or paragraph fields. or themselves.2E-308 to 1.775.807 -2.767 -2. Their values are the values of the entire string. However. reserved word.854. Concordance® Programming Language User Guide 4 .036. quoted strings. z) { x[0] = 5. Database text fields. CPL is case sensitive.147.483.147. References to the variable within the function will only affect the local variable.7E+308 Size 1 byte variable length 2 bytes 4 bytes 8 bytes float 8 bytes The numeric data types—char. Data Types There are five basic data types in the Concordance Programming Language. CPL will perform the necessary conversion so that the comparison or assignment is performed correctly.036.Identifiers nothing(int x[]. Concordance will only consider the first 16 characters when comparing them.223. Database field names. both fixed length and free text. } A variable declared within a function with the same name as a global variable will cause the global variable to “disappear” from the function’s point of view.483. Identifiers can contain any combination of letters. and float—can be freely assigned to each other and compared with each other.647 –9. Text values contain variable length strings. variable. numbers. int.648 to 2. or data type. While the length of identifiers is not limited. z = 15. Type char text short int int64 Value Range -128 to 127 any null terminated text -32.372. and CoLoR constitute three different identifiers. an identifier can only begin with a letter.775. They can be assigned from or compared with character arrays. Identifiers A CPL identifier is any name. and the underscore character.808 to 9. Color.854. which are not case sensitive. Thus color. are treated as text variables. y. y = 10. The name can represent a function. Their types and limits are listed below.223. a function within a CPL program with the same name as a Concordance function will replace the Concordance function. short.768 to 32. Likewise. are generally upper case to improve program readability.372.

Dividing or multiplying dates. and structure. and. Character arrays can be assigned a quoted string. The first element in an array is element zero. case. thus an array with 100 elements contains elements 0 through 99. An array is a set of sequentially ordered elements which are accessed by subscripting the array. Example char today[10].. { } /* */ ‘ “ & = * + -> . if. and the character literal and string enclosures. taken from date fields and functions which return dates. end. A special array type is the char array. Adding 5 to a date will add 5 days. becomes an array. Date math is performed in increments of days. Each of the following variables can be changed by your program. will produce meaningless results. are handled as int types.Reserved Words and Symbols Date values. today = “Tuesday”. or compared with them. logic. begin. return. default. It can be used to store strings. while In addition to the reserved words. else. a sequence of characters. /* today[0] is T today[1] is u today[2] is e today[3] is s today[4] is d today[5] is a today[6] is y today[7] is 0 */ Reserved Words and Symbols Certain words in CPL have special meaning. they contain values used and initialized by Concordance. cycle. These symbols constitute the CPL math and comparison operators. Concordance® Programming Language User Guide 5 . Reserved words are used to control program flow. / <> <= < == >= > | System Variables Concordance has several variables which already exist when your program starts up. These are Concordance system variables. In CPL. all character arrays are terminated by a zero. or. These words are reserved and may not be used as function or variable names within a program. Changes to the color variables are stored by Concordance and are used as default values in Concordance displays and by various CPL functions. They are shown below. break. This is the only array type in CPL that will allow the direct assignment or comparison of the entire array. switch. mod. Arrays Any data type identifier followed by brackets. there are a number of reserved symbols. while valid with any integer. [ ]. the comments enclosures. assigned the value of other char arrays or text variables. for.

and mod.Operators and Operands Variable MaxRow_ TextColor_ TextBackground_ TextHighlight_ MenuColor_ MenuBackground_ MenuHighlight_ MenuHighlightBackground_ HelpColor_ HelpHighlight_ QueryHighlight_ QueryHighlightBackground_ Description The bottom row on the screen. –. Operator – * / mod + – Description Unary minus. the other arithmetic expressions are evaluated left to right. negative numbers Multiplication Division The remainder of the first operand divided by the second Addition Subtraction Concordance® Programming Language User Guide 6 . range 0 to MaxRow_ Color of text used for most displays Color used for background in Windows version Highlighted color used in most displays Color of menu background and unselected items Background color used in Windows version Color used to highlight selected menu item Background color for Windows version Used to display help screens Highlighted text on help screens Used in Browse mode to highlight search words Background color used in Windows version Operators and Operands Arithmetic Operators The arithmetic operators are +. Standard arithmetic precedence applies: division and multiplication are evaluated before addition and subtraction. *. Unary minus is evaluated right to left. /.

and int data types. */ close(data).txt”. | Conditional Operator The conditional operator “?:” provides a compact way to execute if-then logic. If the parentheses were not used. CPL assignments also produce a value as a result of the assignment. The comparison operator determines if the two values are equal and returns a true or false as a result. This is tested against -1 to see if the file was successfully opened. The assignment operator assigns a value to a variable. The result of the assignment is the value stored in data. This construct is both efficient and common in CPL. Returns a bit set to one for each bit set to one in both operands. the assignment operator. You can test the value of the assignment and make the assignment in one statement. Since the assignment operator has a lower precedence than the comparison operator. the comparison operator. b) { if (a < b) a = b.. Consider the example used earlier to describe function parameters: max(float a. Concordance® Programming Language User Guide 7 . } This program fragment opens a file and stores the file handle to the variable called data. and times to avoid it. Returns a bit set to one for each bit set to one in either operand. CPL would first compare the value of open() to -1. There are times to take advantage of this feature. not the file handle returned by open(). CPL would then store a true or false to data. Bitwise Operators CPL provides two operators that allow you to manipulate the individual bits in char. Operator & Description Bitwise AND compares each bit of the first operand to the corresponding bit of the second operand. short. Bitwise OR compares each bit of the first operand to the corresponding bits in the second operand. but it can become confusing if you are not careful.Operators and Operands Assignments Assignments in CPL are done with =."r")) <> -1) { /* .. Example if ((data = open(“letter. This allows you to write more compact programs. the assignment to data from open() must be enclosed in parentheses. return(a). This should not be confused with ==. The result of that comparison would be a true or false.

Comments cannot occur within a statement. but they cannot be nested. Concordance® Programming Language User Guide 8 . and the value following the colon if it is false. the test for the conditional expression should almost always be enclosed in parentheses.. following. */ string = “can’t”. b) { return(a > b ? a : b). Comments are introduced by the /* characters and are terminated by the */ characters. } The conditional expression evaluates the expression preceding the question mark. just above an assignment. /* ." she said. Here’s a bit of sample code that appends an “s” when the number of reported documents is plural. Consider the extra code it would take to write this statement with if-then logic. */ } Comments Comments can occur in a program preceding. Character Literals and Quoted Strings Individual characters used as data within a program are enclosed by apostrophes... string = ‘"What. It returns the value preceding the colon if it is true. /* . The syntax for the conditional expression is: (test-expression) ? TRUE : FALSE The conditional expression has the second lowest precedence of all operators. writeln(handle.. The character used to begin the enclosure must be used to terminate the enclosure. Character strings can be enclosed within quotation marks or apostrophes. A single character enclosed within quotes is interpreted as a character string. Including the logic in the assignment creates a more concise program. x = ‘a’. or between statements. by taking advantage of the conditional expression: max(float a. Therefore. A single character enclosed within apostrophes is interpreted as an integer. string=str(count(db))+" Document"+(count(db)<>1)?"s":"".Operators and Operands } It could be rewritten more compactly.’. Comments can span several lines. Example trans() { int x.string.len(string)). char string[50]. though it may be somewhat terse and less readily understandable.

It contains the following bit settings: Concordance® Programming Language User Guide 9 .access[i]. and the current query number. or read-write. either ‘T’ for text. this returns the left margin of paragraph fields. i. ‘P’ for paragraph. Number of documents in the database. length. read.image[i].access[i]. Number of fields defined in the database. Access the information by following the database handle with a period and one of the keywords listed below. or ‘N’ for numeric fields. ‘Y’.e.e.name[i]. True if the field is a key field. the field types. Keyword access Description User’s access rights to the field. Subscript by field number. i.e. Current active query. Number of places in numeric fields. ‘D’ for date. The name of the subscripted field. Global. db. db. The number of the last executed query. and other functions. ‘M’.Operators and Operands Database Information A variety of information can be obtained about a database by using the database handle with the information selector and several keywords. The field type of the subscripted field. mm/dd/yyyy. The order in which the subscripted field is used by Load. activequery database documents edited fields image key length name order places query type The access rights variable must be subscripted by the field’s number. and the format of date fields.key[i]. db. or ‘D’ for yyyy/mm/dd. Unload. Database name. The defined length of the subscripted field.. i. True if the field is an image key. write. or dd/mm/yyyy respectively. db. Non-zero if the database needs reindexing. and names. Available information includes the number of documents in the database. db.

55. i <= db. i = 2. and a field indicator.Operators and Operands Bit Setting 0 1 2 End-user Rights no access to this field read permission is granted write permission is granted Example /* Display the names of each database field */ /* in a menu. db->"author" = “O’Glue”.35. choices[0] = “Field Selection Menu”. if ((db = opendb(“catalog”)) <> -1) { db->string = “Marlowe”. i = i + 1) choices[i] = db. text choices[db. Using parameters to size arrays builds flexibility into your CPL functions.choices. string = “Author”. A field indicator can be the field’s number. name. Concordance® Programming Language User Guide 10 . to calculate the number of elements. main() { char string[25]. for(i = 1. An interesting feature in the preceding example is the use of a calculation to initialize the number of elements in the choices array.fields+1].20. The database handle is any valid integer returned by a call to the opendb() function. and dates. db.name[i]. the field operator ->. int i. Example Assuming a database’s second field is called AUTHOR. this program would replace the field contents five times. Database Fields Databases consist of individual fields which contain varying types of data. Function parameters become valid variables as soon as they are declared. This function guarantees that the array will always be large enough by using the parameter. numbers. including text. places. return(menu(5. Individual fields are accessed with the database handle.fields. return the menu choice selected */ info(int db) { int i. type. its name. or a character array or text variable containing its name. length.1)). } The access.fields+1. five different ways. db. as in the example above. and order entries must be subscripted by the field’s number.

if there were a variable called AUTHOR. db->i = “Stewart”. Operator . the AUTHOR variable could inadvertently contain a valid field name resulting in the replacement of the wrong field. Concordance would use it to determine the field name. the preferred method is db->AUTHOR. Care should be taken when using the field name without enclosing it in quotes. closedb(db). the value of the AUTHOR field will be “Stewart. on the left and right.” The variety of ways available to access fields provides a high degree of flexibility that should fit all situations. The operators are listed below from highest precedence to lowest. –> – (unary minus) * / mod +– < > <= >= == <> & | Operands Evaluated left to right right to left left to right left to right left to right left to right left to right left to right Concordance® Programming Language User Guide 11 .Operators and Operands db->AUTHOR = “Turley”. Ambiguities can occur when variable names match field names. Logical Operators The two logical operators are and and or. } } When this program finishes. with the field name in upper case. Parentheses should be used to override precedence where desired. An error would result if the variable contained something other than a valid field name. In the above example. Operator and or Result Evaluates to true only if both operands are true Evaluates to true if either operand is true Precedence of Operators and Order of Evaluation Operators are evaluated in order of precedence. Operators on the same line have the same precedence. and return true or false values. db->2 = “McGee”. Worse yet. They each evaluate two operands. However. They are usually used to connect individual relational comparisons into more complex relationships.

Several types of conditional execution and repetitive execution statements are available. or for to create a single block of statements that are executed if the test conditions are satisfied. false values return zero. Individual statements can be continued over several lines before being terminated with a the semi-colon. The result of all comparisons is integer.Program Flow and Control Structures Operator and or ?: = Operands Evaluated left to right left to right left to right right to left Relational Operators Relational operators compare two operands and return a true or false value. All simple CPL statements are terminated by a semi-colon. Operator < > <= >= == <> Relationship Left side is less than right side Left side is greater than right side Left side is less than or equal to right side Left side is greater than or equal to right side Left side is equal to right side Left side does not equal right side Program Flow and Control Structures Concordance statements provide for the control and execution of program logic. Compound statements are treated as a single statement. { and } braces can be used after an if-else. a semi-colon does not follow the }. Begin and End Syntax { statement } The { and } braces are used to create compound statements. Individual statements within the compound statement must be terminated by semicolons. curly end-brace. True values are nonzero. Concordance® Programming Language User Guide 12 . Compound statements are terminated by the }. while.

Cycle Loops Syntax cycle(database-handle) statement Cycle loops execute the controlled statement once for each document in the current query set.10. the test condition is then re-evaluated and the loop is re-executed if it is true. break causes the innermost loop to exit if one loop is enclosed by another loop. All three statements must be present. the last document in the retrieved set will be the current document. If the test condition evaluates to true. Example for(i = 0. i < 100. i = i + 1) string[i] = 0.25. the increment expression is executed. and a loop increment expression. It also causes a case statement to exit the switch. Syntax break. the test condition is then evaluated. the controlled statement is executed. After completion. The initial loop value is set once by the initialization statement. Example cycle(db) if (db->NAME == “Claire Ellen”) break. Concordance® Programming Language User Guide 13 . else db->BONUS = db->COMMISSION * 0. a test condition.Program Flow and Control Structures Break The break statement causes a cycle. while. When the statement finishes. increment expression) statement For loops contain three expressions: an initialization value. } For Loops Syntax for(initialize. or for loop to terminate before the loop control statement ends the loop. test-condition. Example bonus(int db) { cycle(db) if (db->COMMISSION >= 100000) db->BONUS = db->COMMISSION * 0.

. i = next(db)) if (db->COMMISSION >= 100000) db->BONUS = db->COMMISSION * 0. If i is not less than j the else clause is executed which will subtract one from i and add one to j.1.25. else db->BONUS = db->COMMISSION * 0.. */ default: statement. statement. } In this example. i will be set equal to j. statement. If-Else Statement Syntax if(test-condition) statement else statement The if-else statement constitutes the most frequently used decision making syntax available in CPL. If the test condition is false.Program Flow and Control Structures This example would advance through the first 100 elements (from 0 to 99) of the array called string setting each element to zero. The statement evaluates the test condition and executes the first statement if it is true. for(i = goto(db. 14 .10. else { i = i . the else statement is executed.1). i > 0. break. else statements are optional. break. Example if (i < j) i = j. if i is less than j. Switch Statement Syntax switch(expression) { case expression: case expression: case expression: /* . break. break. j = j + 1. } Concordance® Programming Language User Guide statement. The for loop used in this example produces the same results as the example used in the cycle statement on the previous page.

’: periods = periods + 1. string[i] 0. The while loop executes the statement if the condition is true. intClear() does not know the number of elements in the array when it starts. while(i < elements) { numbers[i] = 0. elements = sizeof(numbers)/sizeof(numbers[0]). One noteworthy feature is its use of sizeof(). no action is taken. break. then program execution will begin at the default statement. Example for(i = 0. The case statements must be enclosed within a { } pair of braces. Example intClear(int numbers[]) { int i. break. or } statement is encountered. break. default: if (isalpha(string[i]) consonants = consonants + 1. A switch statement will evaluate its test expression and begin executing the statements following the case statement that matches the test expression. case ’. Execution will continue until the next case. It determines Concordance® Programming Language User Guide 15 . default statements are optional. } While Loops Syntax while(test-condition) statement A while loop will evaluate the test condition and execute the controlled statement zero or more times. i = i + 1. else other = other + 1. Execution will continue until the test condition becomes false.Program Flow and Control Structures Switch statements are similar to multiple nested if-else statements. break. default. } } This example would set every element of the numbers array to zero. If no case statement matches. If no match is made and a default is not present. elements. i = i + 1) switch(string[i]) { case ’a’: case ’e’: case ’i’: case ’o’: case ’u’: vowels = vowels + 1. i = 0.

Functions by Category the number by dividing the size of the whole array by the size of one element. Creates a replica of the database. Closes an open database. and searching. annotationAppend annotationCount annotationDelete annotationGoto Appends a new annotation to a record. or help manage databases by opening. This function could be called in several places within a program to clear a variety of int arrays. Full screen database create options. Creates a new database. annotationIsTagged Determines if an annotation is tagged. Updates the annotation with new data. closing. Concordance® Programming Language User Guide 16 . annotationTag annotationUpdate Adds or delete s a tag from an annotation. Concordance full screen editing. Note: The function searchfs() has been removed from Concordance version 9.0 and later. or notes to the text. browse closedb createdb createfs createReplica editfs Concordance database browse. Functions by Category Annotations Annotation functions access notes and attachments on Concordance records. annotationRetrieve Retrieves data from an annotation record. Makes an annotation the current record. Deletes an annotation. Using the functions you can add hyperlinks to external files. Database These functions start Concordance options that appear on the standard menus. Count of annotations on the current record.

Replicates changes between databases. Prints data base records using a print format file. Invokes Concordance full screen load option. Saves the current query session to file. Locks database for exclusive use. Changes the default search operator.Functions by Category exec global import importfs index keep load loadfs lockdb modify opendb operator overlayfs pack print printfs reindex replicate report reportfs resolve search snapshot Executes a saved query file. Reindexes edited and appended documents. printing a document range. Indexes a data base. Resolves collisions between replicated databases. Invokes Concordance full screen report writer. Concordance® Programming Language User Guide 17 . Invokes Concordance full screen global editing. Loads a delimited ASCII file. Invokes Concordance full screen overlay module. Opens a data base for use. Full screen data base modify. Removes documents marked for deletion. Loads a text file into the selected field. Full screen Documents/Import menu option. Runs a saved report. Saves and restores a complete Concordance environment. Invokes Concordance full screen print mode. Searches a data base.

dates to text and back again. Invokes Concordance full screen table view mode. and characters to text and back again. Unlocks database from exclusive use.Functions by Category struc table unload unloadfs unlockdb zap Duplicates a database's structure. numbers in a window. Concordance® Programming Language User Guide 18 . Data Editing Full screen editing. and input from the keyboard are handled with these routines. Status of next keystroke. edit getkey getline getnumber keypress Edits text. removes every document. Retrieves a keystroke. Edit a line of text. Converts a string into a number. Zaps the data base. editing in windows. asc chr ctod dtoc itoa num str Converts a text variable into a numeric value. Invokes Concordance full screen unload command. into a string. Converts a number into a string. Data Conversion Conversion functions convert numbers to text and back again. Converts a character into a text variable. Converts an integer date. Converts a text representation of a date into an integer. Creates a delimited ASCII file from the current query. or date field. Edits a number. dates. Converts an integer to a plain text in any base.

Loads a list file from a data base field.Functions by Category Dictionary Btree List Management Concordance uses special dictionaries in searching and sorting. and search these list files. It can store textual data in alphabetical order. Displays a list file list in a menu. btclose btcount btcreate btcycle btdelete btexact btfind btfirst btgt btgte btinsert btinserta btlast btlock btlt btmenu btnext btopen btprev Closes a list file. Locks the list file for exclusive use. Locates an entry in a list file. Adds a new entry to the file in ascending order. Returns the first entry in the file. Functions are available from the programming language to create. Opens an existing list file for use. such as a bibliographic report where there are multiple authors per record. Adds a new entry to the list. maintain. Locates an entry less than the target. One use for list files is in subsorting a field to produce reports from fields with multiple entries. Locates an entry greater than the target. and locate and retrieve it very quickly. Concordance® Programming Language User Guide 19 . Locates the last entry in the file. Locates an entry greater than or equal to the target. Deletes an entry from a list file. Returns the count of entries. Locates the previous entry in the file. Creates a new list file. Returns the next entry in the file. The dictionary is list of words or phrases stored in a file known as a btree. Locates a match for both the target and data value.

ddeDisconnect Terminates a DDE conversation. Determines the current working drive and directory. or write-only access. Determines if the file exists. File Handling This group of functions allow you to access external files. Prompts the user for a file name. Dynamic data exchange Dynamic data exchange (DDE) is a mechanism provided within Windows to exchange data and send commands to other Windows programs that support DDE. ddeExec ddePoke ddeRequest Executes a command in the DDE server. Concordance® Programming Language User Guide 20 . chdir close diskspace erase exist findfirst findnext getcwd getfile lseek Changes the file system drive and directory. Concordance provides DDE client functions within CPL to exchange data with other DDE enabled programs. The specified DDE protocol and commands supported by other programs are documented by those programs. to open. ddeConnect Connects to a DDE server application. read-write. Moves to the requested place in a file. Retrieves data from the DDE server. Releases list file for multiuser use. Returns next matching file name. Determines the amount of disk space available. Closes an open file. Erases a file. Locates first matching file name. Files can be opened for read-only. create and erase. read and write. close.Functions by Category btrebuild btunlock Rebuilds a b+tree with 64-bit data values. Sends data to the DDE server.

Writes data to file. Math Math functions manipulate numeric data. Retrieves a character from a file. Several operate on the underlying data base. Unmaps a network drive or printer.Functions by Category mapDevice mkdir open read readc readln rename rmdir unmapDevice write writec writeln Maps a network drive or printer. Opens a file for use. Concordance® Programming Language User Guide 21 . Make a new directory. Reads data from a file. Remove a directory. providing functions for comparison and change. Write a line of text to file. Reads a line of text from file. max min not rand round sqrt Returns the greater of two values Returns the lesser of two values Inverts the number. Writes a character to file. Renames a file. returning its one's compliment Generate random numbers Rounds floating point numbers Calculates a square root Query and Record Management This group of functions access the documents in the data base. Most of them operate on the list of documents in the current query.

Appends a record to the data base. gotophysical gotouuid hits isdeleted isedited isnexthit istagged Locates the physical document number in the query. Concatenates data bases. Determines if there is another hit in the current document. gotoaccession Locates and reads the document the matches the accession number. Concordance® Programming Language User Guide 22 . The number of search terms located in active query. Clears a record. Goes to a record by universal unique identifier. used to append empty records. Determines if document is marked for deletion. Number of documents located by last search. Determines if a document is tagged.Functions by Category accession append blank concat concatclear count delete deleted docno edited exec first fuzzy getuuid goto Retrieves the records accession number. Determines if document was edited since last indexed. Returns the record's document number. Retrieves the record’s UUID. Marks current document for deletion in the next pack. Reads a requested document in the current query. Determines if document was edited since last indexed. Executes a saved query file. Reads the first document in the current query. Clears concatenated data bases. Determines if document is marked for deletion. Locates a list of fuzzy matches for a word.

Retrieves the last document in the current query. and the search logic. Returns data base document to prior state. Using them your program can save portions of the screen. Retrieves information on the next hit in the query. Screen Control Functions are provided to maintain control over the program's presentation on the screen. regardless of query. Converts tagged documents into a query. Returns the document's record number. Prevents other users from editing the document.Functions by Category keep last lockdoc locked markhits next nexthit prev prevhit query queryString readdoc recall recno reset set sort tag tagquery unlockdoc Saves the current queries to file. control the cursor. Retrieves the requested document. Sorts the list of documents in the current query. Tags a document. Retrieves information on the previous hit in the query. Determines if the document is locked. Retrieves the query string. Concordance® Programming Language User Guide 23 . Retrieves the previous document in the current query. Undeletes a document. and display status information. Changes data base environmental variables. with search hits marked. Releases a locked document. Returns record's data. box Draws a box on the screen. Loads the requested query. Retrieves the next document in the current query.

Displays a menu. Concordance® Programming Language User Guide 24 . Displays and highlights search words in a full text field. Clears the screen. operating system commands. Puts a string on the screen. Used in descending order sorts. Returns the name of the current function. Turns debugging on/off. Saves a portion of the screen.Functions by Category ccol cls crow cursor cursoroff cursoron menu messageBox puts putsl restore save scroll show Retrieves the column number of the cursor. Displays a standard Windows message box. Scrolls the screen up or down. Puts a string or substring on the screen. Evaluates a Concordance expression. Retrieves Concordance's command line arguments. Retrieves the row number of the cursor. Hides the cursor. and Concordance language features not available elsewhere. Restores a saved portion of the screen. beep dc debug eval exit func getarg Makes a beep on the speaker. Ends the program. returns to the operating system. Positions the cursor on the screen. Displays the cursor. System System commands provide access to external programs.

Concordance® Programming Language User Guide 25 . and to classify text by character type. Pauses execution of Concordance. to center and justify text. and its length.Functions by Category getenv getPrivateProfileString memavl program putenv run shellExecute sizeof sleep spawn system ver Returns environment string value. Copies text to the cut and paste buffer. Text Manipulation and Classification These functions work with text and character strings. Deletes text from a database field. Executes an external file. or program. Locates the preceding word wrapped line. Retrieves an entry from an initialization file. to search for substrings. Runs a function located in another CPL program file. Returns the Concordance version number. Executes an external program. They are used to move through full text paragraph fields line by line. writePrivateProfileString Writes an entry to an initialization file. addr capitalize cut deleteText findline findnline findpline Determines the address within a text variable. and its length. Sets environment string value. Duplicates the text with all words capitalized. Determines the space occupied by a variable. Locates the next word wrapped line. and its length. Locates the word wrapped line. Name of executing program. Determines available memory. document. Executes an operating system command or program.

Determines if the character is a numeric. Returns a partial string from a string. Determines if the character is alphanumeric. Removes leading and trailing spaces. Duplicates the text in upper case. Determines if the character is lower case. Retrieves text from the cut and paste buffer. Locates a string within another string. Returns a carriage return and line feed string.Functions by Category insertText isalnum isalpha isdigit isfield islower isspace isupper len lower ltrim match matchc newline pad paste rep rtrim substr trim upper wordlen wrap Inserts text into a database field while preserving annotations and formatting. Determines if the character is a space character. Determines if the character is upper case. Replicates a character into a string. Locates a character within a string. left or right justified. centered. Removes trailing white space from a string. Duplicates the text in lower case. Word wraps text data. Determines if the character is alphabetic. Concordance® Programming Language User Guide 26 . Length of the word. Calculates the length of the text. Determines if the field exists in the data base. Removes leading white space from a string. Pads a string with spaces.

date. Zero if the database version does not support accession numbers.0 or later. */ else /* It isn't V6. Previous version databases do not support accession numbers. Year as an integer. 1 .. Converts character strings to date integers. 1 . Current time. as a character string. or if the record has been blank()'ed but not yet append()'ed. Month number. for the date.0 and later Concordance® Programming Language User Guide 27 .0 or later */ Version 6. Today's date. Example /* See if we have a V6. Functions accession Summary int accession(int db).7. Day of the week.0 or later databases. Day number.Functions Time The time functions let you determine the current time. clock ctod day dtoc month time today weekday year Milliseconds elapsed since Concordance started. for the date.12. Description Returns the document's accession number. Converts date integers to character strings. Return Value The document's accession number. This function only works on version 6. Time and date math is handled as simple integer math and is Year 2000 compliant. and the elapsed time since the program started.x database opened */ if (accession(db) > 0) /* It is V6.

and it will not use additional memory.. addr() is faster than passing a copy of the text with the substr() function. */ int offset. This is the name of a file or web address that is launched. length. they can only appear on the right side of an assignment.e. text szNote. i. while(offset > 0) { writeln(file. The note is attached offset bytes from the beginning of the field. Values returned by this function are treated as quoted strings for all practical purposes. length). for length number of bytes. Return Value Character index in internal format. wrap(db->i. Description Appends a new note to the current record in the field identified by db->FIELD. i.1. See Also substr() Example printField(int db. The offset begins with one. szNote szAttachment The textual contents of the note. length. offset). Concordance® Programming Language User Guide 28 . if any. This offset also applies to char arrays. the first character in the field. 40). } } annotationAppend Summary int annotationAppend( db->FIELD. The attachment. offset. text szAttachment. int offset). addr(db->i. int attachmentAction). file) {/* Print every line in the field to file. The remaining parameters are detailed in the table below. Description Converts a text variable offset into an address that can be used by any of the Concordance functions. int attachmentType. even though they are subscripted starting with zero. int offset.length).Functions addr Summary text addr(text string. offset = findnline(db->i. offset = findline(db->i. length).

annotationDelete(). Pass TRUE to auto launch the attachment attachmentAction Return Value Returns zero if successful. annotationRetrieve().0 and later.Functions attachmentType Pass NOTEATTACHCLIPBOARD to have the attachment placed on the clipboard. annotationUpdate() Version Concordance V7. and NOTEATTACHVIEWER sends the attachment to the current viewer. Description Deletes the current annotation. annotationIsTagged(). The note is marked for deletion and the first character of the NOTEPARENT field is set to a space. Return Value Returns a count of the annotations on the current record. NOTEATTACHNOTHING takes no action. annotationIsTagged(). annotationRetrieve(). annotationDelete Summary int annotationDelete(int db). Use NOTEATTACHEXTERNAL to have Concordance launch the application. Packing the parent database automatically packs the notes database. however it is not physically removed from the database until the database is packed. See Also annotationAppend(). annotationCount Summary int annotationCount(int db). Description Determines the number of annotations attached to the current record. it is immediately removed from the document. annotationGoto(). annotationGoto(). This immediately disassociates the note from the parent record. annotationUpdate() Version Concordance V7. annotationTag(). When you delete a note with this function. Concordance® Programming Language User Guide 29 . annotationTag(). Your functions should reinitialize with annotationCount() and annotationGoto() to ensure that you are using the correct annotation. annotationDelete(). See Also annotationCount().0 and later.

annotationTag(). annotationRetrieve(). annotationGoto(). annotationIsTagged(). annotationCount(). Return Value Nonzero if the annotation contains the tag. annotationDelete().0 and later. See Also annotationAppend(). annotationUpdate() Version Concordance V7. See Also annotationAppend(). Return Value Returns zero if successful. See Also annotationAppend(). annotationTag(). text tagName). annotationTag(). annotationDelete().0 and later. annotationIsTagged(). annotationRetrieve(). recordNumber). annotationCount(). annotationGoto().0 and later.Functions Return Value Returns zero on success. annotationGoto Summary int annotationGoto(int db. annotationUpdate() Version Concordance V7. annotationUpdate() Version Concordance V7. annotationRetrieve(). annotationRetrieve Summary Concordance® Programming Language User Guide 30 . Description Determines if the current annotation is tagged with the parameter tagName. Description Reads the requested annotation into memory. annotationCount(). annotationIsTagged Summary int annotationIsTagged(int db.

Return Value Zero indicates success.0 and later. annotationDelete(). Passing a tagName will perform the tag or untag operation only for the specific tag. Return Value All values are returned as text. annotationUpdate Summary int annotationUpdate(int db. annotationIsTagged(). annotationGoto(). Description Copies data to an annotation record field. annotationUpdate() Version Concordance V7. text FIELD. If the optional tagName parameter is not passed. annotationCount(). annotationDelete().0 and later. See below for examples. annotationIsTagged(). annotationTag(). [text tagName]). int TRUE|FALSE. creating an issue. text DATA). annotationCount(). Description Tags an annotation. See Also annotationAppend().Functions text annotationRetrieve(int db. See Also annotationAppend(). Description Retrieves the contents of the named field from the annotation. annotationGoto(). FALSE Document is untagged. annotationTag Summary int annotationTag(int db. Concordance® Programming Language User Guide 31 . All data must be passed as text. See annotationUpdate() for data formatting. the operation is performed on the "default" tagged set. text "NOTETEXT"). annotationRetrieve(). in the current note for the database whose handle is db. The FIELD parameter should be on of the fields in the annotation record. The tag is either applied or cleared according to the value of the second parameter: TRUE Document is tagged. annotationUpdate() Version Concordance V7.

The user login of the person who created the note. Either a "Y" or a "N". no punctuation. The function will make the appropriate conversion to store them in the database. i. annotationTag() Version Concordance V7. See Also annotationAppend(). carriage returns are not counted. or "Clipboard". is used to indicate that there is no attachment type. This is a zero based rich text offset. The number of bytes from the beginning of the field where the note is attached. but this list may be expanded to support other types in the future. An external file attached to the note. annotationRetrieve(). Do not modify this entry. A fourth value. The length of the text at LINKOFFSET that contains the annotation. annotationGoto().e. Return Value Returns the number of bytes copied. "". no spaces. Dates must be passed in YYYYMMDD format. "Viewer".0 and later. A "Y" indicates that the hyperlink is automatically launched when the user clicks on the link. All three types take the contents of the NOTEATTACHED field as their parameter. annotationCount(). append Summary int append(int handle). annotationIsTagged()..Functions NOTEPARENT Unique identification assigned to the parent record. Carriage returns are not counted. The type of attachment can be "External". The text of the note. This is a rich text length. Concordance® Programming Language User Guide 32 . annotationDelete(). This is the file that is launched by a hyperlink. NOTEOWNER NOTETEXT NOTEATTACHED ATTACHTYPE AUTOATTACH LINKFIELD LINKOFFSET LINKLENGTH REPLICATION All values must be passed as text. The field in the parent database that contains this note. including dates and numbers. fully padded and zero filled to eight characters. The replication field that tracks edits.

asc() will not return negative numbers. else code = DoThat(db). and unsubscripted character arrays. text variables. In the case of text fields. See Also blank() asc Summary int asc(text info). Integer comparisons can run faster than string comparisons. This function allows you to directly compare individual characters with numeric values and character constants. See Also chr() Example DoSomething(int db) { int code. if (asc(upper(db->sex)) == 'M') code = DoThis(db). Return Value A -1 if unsuccessful. The ASCII code is in the range 0 to 255. } beep Summary beep(int frequency. Return Value ASCII code that represents the character. The document is locked when the append finishes. Note: The Network Edition of Concordance will automatically lock the end of the file while it adds the document to the data base.Functions Description Appends a document to the end of the data base. Description Converts a character to the integer ASCII code that represents it. This document becomes the current document. Concordance® Programming Language User Guide 33 . return(code). duration). asc() returns the character code of the first character. Append() used without blank() will duplicate the current record. Use append() with blank() to create and add a record to the end of the data base.

up scale and down scale. i. Beep will not make a sound if the beep option on the Set menu is disabled. ** Copy the individual fields.5). i <= db1. /* Get a blank document.5). Once a document is cleared it can be edited and appended to the data base. ** Get the next record to copy. */ /* Use a for-loop for the up scale tone. db2 = opendb("cooking"). } blank Summary blank(int db). /* Sound a siren. /* Copy records to another data base.Functions Description Emits a tone from the PC's speaker. db2. while(i > 450) beep(i = i . i = i + 1) beep(i.1. Description Clears a document at the end of the file. See Also append() Example main() { int db1. Example main() { int i. Return Value None. The current document is not affected. Frequency is a value in hertz. i < 550. Concordance® Programming Language User Guide 34 . */ cycle(db1) { blank(db2). */ db1 = opendb("recipes"). Duration is the length of time in thousandths of a second. */ for(i = 450. i = i + 1) db2->i = db1->i. Return Value None.fields. for(i = 1. ** Append the new document. a */ /* while loop for the down scale tone.

See Also scroll() browse Summary int browse(int db). brow. Browse will display the current document in the current query. format. The background color is only used for Windows. Drop shadows are not available in the Windows version. for a single line box or a double line box. The color and background color parameters are optional. Return Value The key pressed to exit Browse mode. col. Either the [Esc] key or a function key. Return Value None. close the data bases. Description Invokes the Concordance full screen browse mode. The screen is automatically saved before entering this mode and restored after exiting. If the format is SD or DD the box is created with a drop shadow. See Also table() Concordance® Programming Language User Guide 35 . Color selected for normal text is used if the color parameter is left off. 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. A 3D box will produce a DD box in non-Windows versions of Concordance.[background]]). bcol. } /* All done. [color. Windows 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. closedb(db2). but the extra line and columns are accounted for before the box is drawn. case is ignored. the dimensions of the box are decreased by two columns and one row for placement of the shadow.Functions append(db2). } box Summary box(int row. Format is either 'S' or 'D'. */ closedb(db1). The background color is used to fill the box.

} } btclose Summary int btclose(int handle).). i = btopen("recipes. btclose(i). Description Closes the dictionary file associated with handle. Description Concordance® Programming Language User Guide 36 .0)+ " words.Functions Example main() { int db.0."Can't open recipes. } else { search(db."There are "+ str(btcount(i). browse(db).0.").".dct"). See Also btopen(). db = opendb("recipes"). btcreate() Example ShowCount() { int i. } } btcount Summary int btcount(int handle). "chocolate"). else { puts(0. if (i == -1) puts(0. Return Value btclose returns 0 if successful. getkey(). or -1 if an error was encountered."Couldn't open the dictionary").0. closedb(db). if (db == -1) { puts(0.6.

Fixed fields will run the fastest. int duplicate). "pad(db>NAME. will not erase or open an existing file. diskette write protected. A zero value will reject duplicate keys.40)+ str(db->DATE)". Return Value The number of entries placed into the dictionary. text expression).0). Description Creates a new dictionary for use. db->NAME. The function will run faster with a simple field than it will with a quoted parameter that requires evaluation. or -1 if an error occurs. Example ShowUniqueEntries(int db) { char string[80]. The result of expression must be a text value.'L'. Evaluates expression for each document in the data base and inserts the result into the dictionary whose handle is file. See Also btopen(). This number may not be the number of documents in the current query if duplicates are not allowed in the dictionary. If duplicate is a nonzero value. dbHandle. int dict = btcreate("erase. The document's number is stored as the data value. The expression can be a data base field.Functions Returns a count of the number of keys in the file. or a quoted string for evaluation. bad file name or directory path. duplicate key values will be allowed in the file. btclose() btcycle Summary int btcycle(int file. int document. Reasons for failure are the file already exists. Concordance® Programming Language User Guide 37 . Return Value btcreate() will return a file handle if successful. Description Cycles through the data base using the current query. See Also btopen(). Handle must be a valid handle returned by a call to btopen() or btcreate(). btcreate() btcreate Summary int btcreate(char string[]. It cannot be changed once the file is created. a -1 if it was unable to create the file. The duplicate parameter is stored with the dictionary and will remain active when the file is reopened later. disk full. Return Value The count of keys in the file.me".

} btexact Summary int btexact(int file.document). } btclose(dict). int data).0. key = getkey(). if ((key == 'Y') or (key == 'y')) btdelete(btree. } btdelete Summary int btdelete(int file. text line.string. a nonzero value if an exact match could not be located. */ line = 'Delete "'+string+'"?'. Example remove(int btree.Functions /* Create the list and show entries in a menu.document)) { /* Load the selected document and browse.db. puts(0. Concordance® Programming Language User Guide 38 . while(btmenu(dict. Description Locates a matching entry in the file."Authors". /* Get field to display at top of btmenu(). text string) { int key.string).0. Return Value A zero if the entry was found.len(line)+1). The entry must match both the key value and the data value. Description Deletes the matching key from the dictionary.line). Return Value A 0 if successful. a -1 if not successful. /* Enclose string in quotes and ask */ /* if the user is sure they want to */ /* delete it from the file. Returns a -1 if the word was not in the file.7. browse(db). */ string = trim(db->AUTHOR).22.me"). erase("erase. */ btcycle(tree.db->AUTHOR). cursor(0. char key[]). char key[].79. */ goto(db.

buf[] must be large enough to hold the retrieved word. Return Value The value of btfirst() is 0. buf[].Functions See Also btfirst(). returns the associated integer value in data. If the word was not in the file. btfind(). int data). char key[]. See Also btexact(). its associated numeric value is returned in data. btgte() Concordance® Programming Language User Guide 39 . if found. the value of btfind() is -1. Description Locates the first word in the dictionary file and returns its integer value in "data. btgte(). char key[]. btlt(). btgte(). btlast() btfind Summary int btfind(int file. btlt(). btfirst(). See Also btlast() btgt Summary int btgt(int file. Return Value The value of btfind() is 0. int data). btlast() btfirst Summary int btfirst(int file. Description Locates the dictionary entry greater than the search key. btgt(). the entry is returned in buf[]. Return Value A value less than zero if an error occurs." The word is returned in key[]. int data). or if there is no value greater than the search key. See Also btlt(). Description Locates the word and. If an entry is found. The word is returned in buf[]. char key[]. the value of btfirst() is -1. key[] must be large enough to hold the retrieved word. The file handle must be a valid handle returned by a call to either btopen() or btcreate(). If the file is empty. btgt().

upper(string). and the key's value is returned in data. int handle) { int UpperCase. Description Locates the dictionary entry greater than or equal to the search key. if (isupper(string[1])) /* Mixed case word. buf[]. Return Value A 0 indicates success. Description The key value is inserted into the dictionary along with the numeric value in data.Functions btgte Summary int btgte(int file. } /* Insert word in upper case. btlt(). but */ /* store the case indicator as the */ /* data value. } Concordance® Programming Language User Guide 40 . The entry is returned in the buf[] variable. See Also btcreate(). /* Assume lower case word. Return Value A -1 if an error occurs. */ UpperCase = 2. char key[]. a value less than 0 indicates an error. int data). */ return(btinsert(handle. See Also btgt(). char key[]. btopen(). */ UpperCase = 1. btinserta(). int data). if (isupper(string[0])) { /* Capitalized word. This can be used */ /* later in a spell check program. btclose() Example update(char string[]. it may indicate either a disk full condition or a duplicate key value if duplicate keys are not allowed. UpperCase)). btfind() btinsert Summary int btinsert(int handle. */ UpperCase = 0. If a negative value is returned.

Functions btinserta Summary int btinserta(int handle.xyz"). NewError.buffer.0). Description The key value is inserted into the dictionary. a -1 if it was not. new.data).data). OldError = btfirst(old. char key[]."). erase("temp. btopen() Example main() { int OldError. */ if (btcount(old) <> btcount(new)) NewError = -1. new = btcreate("temp.0."Error in new dictionary. } /* If the key counts are not the same in ** both files it means that an error occurred ** at some point. puts(1."Disk may be full. int data). however the dictionary will assume that what you are inserting is already sorted in ascending order."). Return Value A 0 if the key was successfully added to the dictionary. } else { erase("oldfile.xyz". rename("temp. */ btclose(old). It will use an insertion scheme that optimizes for ascending order insertion and will produce a more compact dictionary. probably a full disk."oldfile. btcreate().data). old = btopen("oldfile.buffer.0. btclose(new). /* Close the files and finish.xyz"). while((OldError <> -1) and (NewError <> -1)) { NewError = btinserta(new.xyz". char buffer[60]. if (NewError == -1) { puts(0. */ NewError = 0.xyz").buffer. data. OldError = btnext(old. } } Concordance® Programming Language User Guide 41 . /* Read the existing dictionary and insert */ /* all data into the new dictionary. old. See Also btinsert().xyz").

See Also btunlock() btlt Summary int btlt(int handle. Description Read the last entry in the dictionary. Description Locates the key entry less than the passed key. int data). Return Value Returns a nonzero value if the file could not be locked. The character string buf[] must be large enough to hold the returned value. See Also btfirst(). char key[].Functions btlast Summary int btlast(int handle. Description Locks the btree file for exclusive use. All other network users are prevented from accessing the file. it is returned in buf[] with its associated numeric value returned in data. The file is left positioned on the last entry after this call. The file should be unlocked as quickly as possible to ensure access for other network users. If an entry is found. btgt() btmenu Summary Concordance® Programming Language User Guide 42 . char key[]. btnext() btlock Summary int btlock(int handle). Return Value Returns a -1 if an error occurred. btprev(). buf[]. A series of btprev() calls would then read the file in descending alphabetical order. return the entry and its numeric value. int data). Return Value A 0 if successfully read. a nonzero value if there was an error. See Also btprev().

A 0 return value indicates that the user pressed [Esc] to exit without making a selection. char key[]. The user can cursor through the dictionary. that key is returned in the key[] and data parameters. "U" or "u" converts all of the user's typed input to upper case. If key[] contains a value when btmenu() starts. int data[. Description Displays the contents of the dictionary whose handle was returned earlier by a call to btopen() or btcreate(). text action). char title[]. btmenu() will display the list of words that match most closely. See Also btprev(). The user can select the current word by pressing the [Enter] key. btfirst() btopen Summary int btopen(char string[]). bcol. A 1 indicates that the user pressed [Enter] to select a key. btmenu() will copy the word they are typing on the prompt line to the key[] parameter. and the word's associated numeric value to the data parameter. The action parameter is optional. Windows users should pass the "E" parameter mentioned above. An "L" or "l" converts the input to lower case. or type the letters of the word for lookup. Return Value A -1 is returned if there is no next key. row. Specifying an "E" or "UE" or "LE" enables the Insert and Delete buttons in the Windows version. If the user presses [Ctrl-Enter]. in this case key[] will contain the prompt line string. Description Locate the next entry in the file. Return Value A value of -1 indicates an error in the dictionary file. The key and data parameters are set to the value of the key. The key values are displayed in a menu window. brow. int data). col. Description Open a dictionary file for use. As the letters are typed. then the key greater than or equal to that key becomes the first key displayed on the screen. Concordance® Programming Language User Guide 43 . key[]. The title string is displayed at the top of the window.Functions int btmenu(int handle. A 2 indicates that the user pressed [Ctrl-Enter] to select the value they were entering on the prompt line. btnext Summary int btnext(int handle. btmenu() will copy the selected word to the key[] parameter.

A file must be unlocked exactly as many times as it was locked to completely release it. btfirst() btunlock Summary int btunlock(int handle). Description Unlocks the file allowing other network users to access it. or if it is not recognized as a valid dictionary file. all non-initial letters are lower case. char key[]. All words will begin with an upper case letter. See Also btclose(). Return Value A nonzero value if an error occurred while unlocking the file. Does not change the original. Description Produces a duplicate of the parameter string capitalized. and its numeric value in data. btcreate() btprev Summary int btprev(int handle.Functions Return Value -1 if the file cannot be found. See Also upper(). Return Value A -1 is returned if there is no previous entry. Return Value The parameter with capitalized text. Description Locates the previous entry in the file and returns it in key. lower() Concordance® Programming Language User Guide 44 . See Also btlock() capitalize Summary text capitalize(text string). See Also btlast(). int data). btnext().

0. Return Value A zero if successful.0. Description Changes the current drive and directory to the one specified by directoryPath.Functions Example main() { text author. See Also crow(). non-zero if the directory or drive does not exist. puts(1. /* Change drive and directories. cursor() chdir Summary text chdir(text directoryPath). /* Change directories. Return Value Cursor's column position.author). getcwd() Example main() { /* Change to drive E: *\ chdir("E:"). See Also diskspace(). puts(0. } Output: E E Cummings e e cummings ccol Summary int ccol(). Description Current column position of the cursor.capitalize(author)). */ Concordance® Programming Language User Guide 45 . */ chdir("concord5\DATA"). /* Display the current drive and path. */ chdir("F:\apps\concord5"). author = "e e cummings".

Description Converts the value of c to a text variable. close(handle)...'. Return Value The single character converted to a text type variable. text line.0.Functions puts(10.40. start.')). i = i + 1) puts(0. today() Example main() { int i. } } clock Summary int clock(). Return Value Returns -1 if the clock is not available.line."+chr(12). i < 100. Description The clock() function gets the number of thousandths of a second since the program was started. start = clock().0. See Also time(). */ if ((handle = open("prn". for(i = 0. Concordance® Programming Language User Guide 46 .len(line)). write(handle. /* Send a form feed to the printer. See Also asc() Example main { int handle."w")) <> -1) { line = "Page ejected."The current directory is "+getcwd()). } chr Summary text chr(int c).7."Count ="+str(i.

Example main() { int db. if (closedb(db) == -1) puts(0."There are "+str(db.')+" seconds."Can't open data base.1. } close Summary int close(int handle).8.Functions start = (clock() .7. Description Data base associated with db handle is closed.").'. Description The file associated with handle is closed. } else puts(0. -1 if not successful.')+" recipes in the cookbook"). puts(1.0. Return Value A 0 if successful. Concordance® Programming Language User Guide 47 . See Also open() closedb Summary int closedb(int db).").documents. Handle must be a value returned earlier by a call to open(). } cls Summary cls([int color]).'."Error closing data base. getkey().0."That took "+str(start.0.start) / 1000.0. db = opendb("recipes").") getkey(). Return Value A -1 if an error is encountered while closing the file. if (db >= 0) { puts(0.0.

Description Concordance® Programming Language User Guide 48 . oldColor. FileName should be the path and name of a data base file to concatenate. data base is in exclusive use by another user. the maximum is sixteen. i = i + 1) { TextColor_ = i. the color should be a background color. puts(MaxRow_/2. See Also scroll() Example colors() { int i.pad("Color "+str(i). Return Value Zero if the data base was concatenated. i <= 127.80)). */ oldColor = TextColor_. the requested data base is already concatenated. nonzero if an error occurred. Return Value None. See Also concatclear() concatclear Summary concatclear(int db).Functions Description Clears the screen to TextColor_. } TextColor_ = oldColor. getkey(). cls(). /* Show the basic set of colors. or to the specified color if one is passed as a parameter. for(i = 1. } concat Summary concat(int db.0. file not found. Cause for error includes: too many concatenated data bases. Description Concatenates a data base to the opened data base whose handle is db. Display the */ /* color's number centered in the screen. the default color.'C'. text FileName). Under Windows.

The fields are defined by giving them a name. int places[]. The data base is no longer concatenated after this call returns. db should be a valid handle returned by a call to opendb(). Concordance® Programming Language User Guide 49 . a length. A non-zero entry creates a key field. the places array must also be provided. Return Value None See Also concat() count Summary int count(int db). for Text. int keyField[]). Numeric. text FieldNames[]." for zero filled.documents. It sets the left margin of paragraph fields. use: x = db.Functions All data bases concatenated to the data base whose handle is db are closed. and its presence is optional. and optionally places and format entries. Length indicates the display format for date fields. If the format array is passed. or DMY. 'N'. int formats[]. Return Value Count of documents in the current query. The type can be 'T'. A value less than zero if the data base is not open. The keyField array specifies the key fields in the database. or 'P'. See Also hits() createdb Summary int createdb( text FileName. or ". currency and comma numeric types. a type. MDY. Description Creates a new data base with the requested file name and structure. int lengths[]. 'D'. Description Returns the number of documents in the current query. Date. $. The format array can contain numeric display formats Z. To find the total number of documents in the data base. int types[]. This function will not create the data base if another data base already exists by the same name. The places array is only used for numeric field types. The length entry designates the total width of the field for text and numeric fields. and Paragraph field types respectively. YMD. All queries are reset and cleared by this call.

then presents the data base create screen. types[3] = 'P'. A nonzero return value is an error code in the reference manual error listings. types[4]. modify(). See the Concordance Reference Manual for a full description of data base create. string). err = createdb(string. lengths[0] = 'M'. lengths[2] = 16.types. Concordance® Programming Language User Guide 50 . } createfs Summary int createfs(). This function only creates the data base. newHandle = -1. "*. lengths[1] = 10. key[1] = 0. getfile("New Database".lengths). if (err == 0) newHandle = opendb(NewName).DCB". struc(). */ MakeNew() { char string[80]. } return(newHandle). text names[4]. or in the concordp. It first prompts the user for a data base name. names[1] = "EARNINGS". opendb() Example /* Create a new data base. newHandle. types[0] = 'D'. key[3] = 0.msg file. See the reference manual for a full explanation. See Also createfs(). Return Value Zero if the data base structure was valid and a data base was created. it does not open it.msg or runcpl. types[1] = 'N'. names[2] = "NAME". Description Concordance full screen create command.names. int lengths[4]. int err. Note: This function is not implemented in the Concordance Runtime Module. lengths[3] = 16. key[2] = 0. types[2] = 'P'. key[0] = 1.Functions All rules that apply to creating data bases in Concordance's full screen Database Create mode apply to this function. key[4]. if (len(string) <> 0) { names[0] = "BIRTHDATE". names[3] = "AUTHORED". It will always return a creation error in the Runtime module.

See Also ccol(). The optional parameter. resolve() crow Summary int crow(). will copy attachments with the database if set to TRUE. Return Value A handle to the newly created and opened data base. Description Creates a replica database using all records in the current query. in the current sorted order.Functions Note: This function is not implemented in the Concordance Runtime Module. Concordance® Programming Language User Guide 51 . copyAttachments. See Also modify(). char format]). 'M' or 'D' to select YYMMDD. text databaseName. if specified. Return Value Row position of the cursor. The replica has all security settings and document tags in the current database. MMDDYY and DDMMYY formats of the string parameter. The format. It will always return an error when called from the Runtime module. int copyAttachments). but it is not indexed. Description Current cursor row. Return Value A zero signals success See Also replicate(). struc() createReplica Summary int createReplica(int db. A value less than zero if the user canceled the data base create. Description Convert character string or text variable to date format. The default is 'M' format if none is specified. createdb(). can be 'Y'. cursor() ctod Summary int ctod(char string[][.

DaysBefore2000 = ctod("1/1/2000") . and from column 0 to column 79. } cursor Summary cursor(int row.Functions Return Value The date as an integer. Return Value None. return(DaysBefore2000)."). cursoron()."The cursor has disappeared.today(). cursoroff() cursoroff Summary cursoroff(). Description Hides the cursor. puts(1. See Also ccol()."). The screen begins in the upper left corner with row 0. Description Moves the cursor to the specified row and column coordinates. Concordance® Programming Language User Guide 52 . column 0. crow(). puts(0.0. Return Value None. column).0. An 80 column screen goes from row 0 to row 24. See Also cursoron() Example main() { cursoroff()."Hit any key to show the cursor. See Also dtoc() Example days() { int DaysBefore2000.

or a date field. The data replaces the current contents of the buffer. as returned by ctod(). Description Extracts the day of the month from the date.31). See Also cursoroff() cut Summary text cut(text data).Functions getkey(). } cursoron Summary cursoron(). cursoron(). Return Value The text value that was cut. The buffer is shared by the programming language with the editor's cut & paste functions. Description Copies the data to the cut and paste buffer. Note that other programs have access to the clipboard. and they can clear or replace the data. The date can be a numeric representation of the date. The Windows version cuts to the system clipboard. Return Value None. See Also Concordance® Programming Language User Guide 53 . See Also paste() day Summary int day(int birthday). Description Enables the display of the cursor. It remains in the buffer until another cut() replaces it. Cutting text with the editor will also flush the buffer and replace the data. Return Value The day of the month (1 .

Functions

month(), year(), weekday() Example oneHundred(int billday) { text line; billday = billday + 100; puts(0,0,"100 days overdue is:"); line = str(day(billday),2,0,'Z')+"/"+str(month(billday)2,0,'Z')+"/"+str(year(billday),4,0,'Z' ); puts(1,0,line); }

dc
Summary text dc(text string); Description dc() is used within a sort parameter string to specify a descending order sort. Enclose the entire sort string, or specific fields, within the dc() function to perform the descending or mixed order sort. Any data not enclosed within the dc() function is sorted in ascending order. Return Value The parameter string inverted for a descending order sort. See Also sort() Example See sort() for an example.

ddeConnect
Summary int ddeConnect(text Service, text Topic); Description Begins a dynamic data exchange (DDE) conversation with another Windows application. Service is the name of an application which can respond to DDE messages. This is usually the program name without the .EXE extension. Topic is the name of a topic recognized by the server. This function is available only in Concordance for Windows. Return Value Returns a nonzero handle to that conversation. An error can occur if the application is not running, or if it is running but does not recognize the topic or support DDE. See Also ddeDisconnect(), ddeExec(), ddePoke(), ddeRequest()

Concordance® Programming Language User Guide

54

Functions

Example makeWorksheet() { int ddeHandle, i; text topicList, sheetName; /* Establish a link to the spreadsheet. */ ddeHandle = ddeConnect("Excel","System"); /* Create a new work sheet. */ ddeExec(ddeHandle,"[New(1)]"); /* Retrieve a list of available spreadsheets. */ topicList = ddeRequest(ddeHandle,"Selection"); /* Disconnect */ ddeDisconnect(ddeHandle); /* Isolate the name of the first spreadsheet. */ /* Establish a new conversation based on the spreadsheet, */ /* this will allow us to modify the spreadsheet.*/ sheetName = substr(topicList,1,match(topicList,"!",1) - 1); ddeHandle = ddeConnect("Excel",sheetName); /* Fill it with data. */ for(i = 1; i < 10; i = i + 1) ddePoke(ddeHandle,"R1C"+str(i),str(i)); /* Make a chart. */ ddeExec(ddeHandle,'[Select("R1C1:R1C10")]'); ddeExec(ddeHandle,'[New(2,1)]'); /* Terminate the DDE conversation. */ ddeDisconnect(ddeHandle);

ddeDisconnect
Summary ddeDisconnect(int ddeHandle); Description Disconnects from the dynamic data exchange (DDE) conversation previously opened by using ddeConnect(). Return Value None. See Also ddeConnect(), ddeExec(), ddePoke(), ddeRequest()

ddeExec
Summary ddeExec(int ddeHandle, text command); Description Uses an open dynamic data exchange conversation handle to send a command to another application. The command depends on the application and topic specified when the conversation was initiated.

Concordance® Programming Language User Guide

55

Functions

Return Value Success value returned by the server. Generally 0 means the ddeExec() was not processed, 16384 means the server was busy, and 32768 signifies success. See Also ddeConnect(), ddeDisconnect(), ddePoke(), ddeRequest()

ddePoke
Summary ddePoke(int ddeHandle, text item, text data); Description Sends data to the DDE server application. The item is a value, such as a spreadsheet row and column or database field name, which is recognized by the server. The data is a string containing the data sent to the other application. Return Value Success value returned by the server. Generally 0 means the ddeExec() was not processed, 16384 means the server was busy, and 32768 signifies success. See Also ddeConnect(), ddeDisconnect(), ddeExec(), ddeRequest()

ddeRequest
Summary ddeRequest(int ddeHandle, text item); Description Sends a dynamic data exchange (DDE) request to the open conversation. This generally retrieves data from the server, though the action taken is dependant on the server, the topic, and the item. Return Value The DDE server must return a text value. See Also ddeConnect(), ddeDisconnect(), ddeExec(), ddePoke() Example int dh; text listOfFields, field, fieldData; /* Establish a link to the database */ dh = ddeConnect("Concordance","Resumes"); /* Retrieve a list of fields in the database. */ listOfFields = ddeRequest(dh,"List of Fields"); /* Retrieve data from the first field */ field = substr(listOfFields,1,match(listOfFields,',',1)-1); fieldData = ddeRequest(dh,field); /* Disconnect from the database */

Concordance® Programming Language User Guide

56

Functions

ddeDisconnect(dh);

debug
Summary int debug(int mode); Description Turns single step debugging on or off. Mode should be 1 to turn debugging on, 0 to turn it off, and -1 to disable it. Debugging can also be turned on and off by pressing [Alt-F1], unless debug(-1) has disabled it. Return Value Value of previous setting.

delete
Summary delete(int db); Description Marks the current document for deletion. The document isn't removed from the data base until it is packed. Return Value None. See Also deleted(), recall(), pack()

deleted
Summary int deleted(int db); Description Checks if the document is marked for deletion. Return Value Nonzero if the document is marked for deletion, zero if it is not marked for deletion. See Also delete(), recall(), pack() Example /* Count the documents marked for deletion. */ DelCount(int db) { int count; cycle(db)
Concordance® Programming Language User Guide

57

Functions if(deleted(db)) count = count + 1. totalSpace. See Also insertText() Version Concordance V7 and later. freeSpace).freeSpace) == 0) allocatedSpace = totalSpace . getcwd() Version 5. Allocated space can be calculated with: int allocatedSpace. Description Determines the amount of total and free space on the drive specified. Return Value The number of bytes deleted. See Also chdir(). if (diskspace('C'. the variables totalSpace and freeSpace will contain the total bytes available on the disk and the free space remaining. such as 'A'.totalSpace. freeSpace. 'C'. int length) Description The first parameter identifies a field in the database. totalSpace.32 and later Concordance® Programming Language User Guide 58 . Any annotations contained by the block of deleted text are also deleted. etc. non-zero if an error occurred or the drive does not exist. } deleteText Summary int deleteText(db->FIELD. Upon returning. This function preserves rich text formatting and properly processes annotations. Return Value Zero if successful. The deleteText() function deletes a block of text at offset for length number of bytes. return(count). int offset.freeSpace. The drive should be a letter. respectively. diskspace Summary int diskspace(int drive.

If the optional parameters document. document.e. Description Returns the relative document number in the current query.. field. document. Return Value A relative document number.Functions docno Summary int docno(int db. */ } } dtoc Summary text dtoc(int birthday[. the fifth document located in the search. This function will return the exact date contained in a date field. db must be a value returned by a call to opendb(). /* document now equals 5. Returns a value less than or equal to zero if there are no documents in the current query set. recno() Example main() { int db. db = opendb("recipes. and offset are provided they will contain the same information documented in. Docno() always returns a number relative to the current query set. nexthit(). Description Converts the date value to a character string. docno() would return the number 1. the first() function. prev().5). document = docno(db). and returned by."chocolat*"). The document's physical position in the underlying data base may be almost any number. See Also goto(). prevhit(). next(). After issuing a first(). i. 12/00/81 or 99/99/9999. if (db <> EOF) { search(db. To test for a valid date use: if (dtoc(db->DATE) <> dtoc(db->DATE+0)) badDate(db). offset). even though the first document retrieved in the query may be the 25th document in the data base. field. first(). goto(db. not a physical document number in the underlying data base. even if the date is invalid.dat"). char format]). last(). Concordance® Programming Language User Guide 59 .

35.. they contain the current offsets of the user's cursor. TC."Today is "+dtoc(today())). Multiple data values can be passed to the edit function in one call. . They specify the offset into a full text field to begin displaying data. SO and EO are the Screen Offset and Edit Offset. BC. floating point value. Setting element to a value greater than the total number of elements will cause edit() to use the last element. and column. BR. The last line in edit() uses additional variables to tell edit() which element to edit first. The window is described by its top row.Functions else goodDate(db). is the color used to edit all values passed to the edit() function. These are used for full text paragraph fields. or date. integer. The optional format parameter can be 'Y'. The mode string tells the edit function how to edit the data. int element. what initial mode to use. The following mode string attributes are available: Concordance® Programming Language User Guide 60 . Edit elements are numbered starting with one at the top. Upon return. Upon return. BR. color. Description Edits a data-value. EO. Return Value A character string representing the date. what offset into the data to start editing.. MMDDYY. and the offset into the field to place the cursor when edit() is first called. text iMode. See Also ctod() Example whatDayIsToday() { puts(12. The last parameter. int TR. which can be a database field. and its bottom corner row. BC.. and column. . instead of the first. element is the data element to edit first. in an edit window. The default format 'M' is used if the parameter is not explicitly set. color). int SO. See the modes below for additional information. } edit Summary int edit(data-value. TC. If multiple values are passed you can tell edit() to start editing with any selected value. element contains the current number of the element being edited. The iMode parameter specifies the edit attribute to use for this first element the initial time it is edited. or DDMMYY. 'M' or 'D' to indicate the date format for conversion: YYMMDD. text mode. char array. TR.. and what color to use. Mode attributes are described later.

Display only this value.d Y M D C Alpha only mode. Return on [Enter] key. This mode allows the user to move with the cursor control keys. Creates a button under Windows. Returns CR if selected. This requires [NumLock] to be off. MDY mode for dates. [Shift-Del] copies marked text to the cut and paste buffer. Upper case conversion. no hard carriage returns allowed in data. can be a date field or integer value. If T and B are not specified. Use for fixed fields and char arrays. Pressing [Alt-M] again will unmark the text. Concordance® Programming Language User Guide 61 . Always edit data starting from the top. can be a date field or integer value. Edit data starting from the bottom. [Ctrl-Y] deletes text from the cursor up to and including the end of the line. Note that the element parameter must be changed upon calling edit() again or an endless loop is created when edit() immediately returns again and again. YMD mode for dates. no editing allowed. This is how required authority lists or other special handling can be added to the edit function. Useful with fixed fields and char arrays. Return immediately when this field is entered. Cut and paste mode. no word wrapping. Scroll field left and right. mark text with [Alt-M]. Numeric only mode. This requires [NumLock] to be off. edit() assumes you wish to continue editing using the screen and edit offset parameters. with d decimals. numeric values are rejected. and copy it to the cut and paste buffer using the [Enter] key. Use the paste() function to access the marked text. If T and B are not specified. can be a date field or integer value. Numeric data is edited in a field w characters wide. don't edit it. edit() assumes you wish to continue editing using the screen and edit offset parameters. DMY mode for dates. [Ctrl-Y] ignores marked text and does not save the deleted text in the cut and paste buffer. [Del] deletes marked text and copies it to the paste buffer. for text or char array variables. This mode is useful as an initial mode value overriding default value. [Shift-Ins] copies text from the buffer to the edit window. S E T B @ ! Button The following additional keys can be used while editing: [Alt-M] will begin marking text for cut and paste.Functions A U N N:w.

Edit Offset. db->NAME. 3. "phone. Upon returning. 3. Screen Offset. TextColor_). element. /* Edit them until [Enter] or [Esc] is hit.'L'. 3. display mode. areacode. 60. areacode. phone[5]. 11.4). 3. show() Example /* name: editPhone ** synopsis: Edits a phone number in 999/999-9999 format. prefix. 3.9)). /* Value of [Enter] key. The value -1 indicates an insufficient memory error. /* Edit offset */ /* Get the three elements of the phone number. "-". is returned if the user types past the last character in a field. /* Element to edit first. "@". will contain the offsets into the text of the line displayed at the top of the current window and of the character under the cursor. 15. int key. the returned value is always a 0. getnumber(). 3. 3.3)). 3. return(key). 8. "". "prefix. 3. */ ESC = 27. 14. 19. unless the user tries to cursor above the first element or below the last element.3)). /* Screen offset */ EO = 1. 3. 8. */ element = 2. the parameter element will be set to the number of the data element currently being edited. 15. */ areacode = trim(substr(db->PHONE. and EO. */ SO = 1. CR = 13. respectively. "/". "@". phone = trim(substr(db->PHONE. 16. /* Value of [Esc] key.3)+"/"+pad(prefix. "@". 12. prefix = trim(substr(db->PHONE. prefix[4]. SO. "@". Edit returns the keystroke that caused termination. 7. In the case of mode @.Functions Return Value Edit will automatically process all cursor control keys that move between edit elements. EO.5. "NET". a [Ctrl-P]. */ editPhone(int db) { char areacode[4]. */ while((key <> ESC) and (key <> CR)) key = edit("Phone:". 1. } Concordance® Programming Language User Guide 62 . 3. /* If the user pressed [Enter].'L'. See Also getline(). */ if (key == CR) db->PHONE = pad(areacode. and phone number. The value 16.3)+"-"+pad(phone. 2. 11. 3. save the number. 10.1. "NET".'L'. 2. The parameters SO. "NET".

editfs Summary editfs(int db).").0. Return Value If successful."). Description Determines if the paragraph fields in the current document have been edited or appended to the data base since the last time the data base was reindexed. may result in the wrong words being highlighted. Description Invokes the Concordance full screen editor. All fields in the data base are edited. Return Value None. Otherwise it returns a -1. The screen is automatically saved before entering this mode. Documents located in a full text search that have been edited may not actually match the search conditions. erase Summary int erase(char string[]). Description Erases the file.Functions edited Summary int edited(int db). or to underline them on a printer.FileName+" has been erased. } Concordance® Programming Language User Guide 63 . erase() will not delete a read-only file or a directory. It is restored upon exiting. Attempting to highlight the keywords on the screen. The file name can be a character array or a text variable.0. else puts(0. Example remove(char FileName[]) { if (erase(FileName) == -1) puts(0."Couldn't erase "+FileName+". Return Value A nonzero value if the document has been edited or modified since the last reindex. Users can change documents. The current document in the current query is edited. erase returns a 0. but they cannot change queries from the editor.

The third parameter. Enclosing the eval() function within the str() function guarantees that the result is always of type text. Concordance® Programming Language User Guide 64 . and passing them to another function for report creation. Return Value The value and type returned by eval() is the result of the string that is evaluated. The error code corresponds to one of the numbered error messages in this manual. However if the string contains "weekday(today())" eval() returns the day of the week as a character string.81. For instance. code. ** Display an error code if an error code is ** returned. if the string contains "2+2" eval() will return an integer. db. db = opendb("c:\concord\database\research"). Scroll each line up the screen ** after each command. is optional.string). /* Get the command from the user. This function allows end users to enter commands into strings and have them evaluated by the command processor. Otherwise it will contain zero. while(key <> ESC) { key = 0. Local variables declared in the function which executes eval() are accessible to the eval() function. This is useful when using eval() within a run() function to determine the error code and line number which produced the error. */ while((key <> CR) and (key <> ESC)) key = getline(MaxRow_. ESC. char string[81].Functions eval Summary eval(text string.0. It returns the line number that produced the error. int code. CR = 13. or combination. */ main() { int code. field. int CR. The second parameter. ESC = 27. will contain an error code if the expression could not be evaluated. Description Executes the Concordance expression in the string and returns the result as the value of eval(). line. key. See Also run() Example /* Read a command from the user and execute it. line). Using eval() to execute a run() also keeps your main program from crashing if the external program does not exist or has an error. string[0] = 0. This function is useful in allowing the user to enter a report format.

Functions

/* Scroll the screen and display the command. */ scroll( 1, 0, MaxRow_ - 2, 79, 1, 1); puts(MaxRow_ - 2,0,pad(string,'L',80)); scroll( 1, 0, MaxRow_ - 2, 79, 1, 1); string = trim(string); if (string[0]) { if (upper(string) == 'QUIT') return; /* Evaluate string, convert all results */ /* to strings. Display result or error. */ string = str(eval(string,code)); if (code) puts(MaxRow_ - 2,0,"Error "+str(code)); else puts(MaxRow_ - 2,0,string); } } }

exec
Summary int exec(int db; text filename); Description Executes the saved query file. Unlike the Execute option on Concordance's Search menu, exec() does not display the searches as they are executed. Concordance normally appends the file extension .QRY to executed query files. The exec() function does change the file name passed to it. Your program must ensure that the file extension is correct before calling the exec() function. Return Value A nonzero value if the file could not be found. See Also keep(), snapshot()

exist
Summary int exist(char string[]); Description Looks for the file name and determines if it exists. Return Value Exist returns a nonzero value if the file was found, and a zero if it was not found. In addition, the returned value has the following bit settings to indicate:

Concordance® Programming Language User Guide

65

Functions

1 file exists 2 write permission is granted 4 read permission is granted Example main() { int status; if (status = exist("c:\config.sys")) { puts(0,0,"config.sys exists."); if (status & 2) puts(1,0,"config.sys has write access."); if (status & 4) puts(2,0,"config.sys has read access."); } else { puts(0,0,"config.sys file not found."); puts(1,0,"Creating one for you..."); CreateConfig(); } puts(3,0,"Press any key to continue..."); getkey(); }

exit
Summary exit() Description Stops execution of the CPL program and of Concordance. Quits Concordance and returns to the operating system. Any open data bases are closed automatically. Return Value No return value, this function does not return to the caller.

findfirst
Summary text findfirst(text fileMatch; int attribute); Description Locates the first matching file name for the fileMatch string parameter that has matching file attributes. All DOS wildcards are valid. The attribute parameter specifies DOS file attributes that are included in the search. They include: 0 1 2 4 8 Normal files - no read/write restrictions. Read only files. Hidden files. Systems files. Volume ID file.

Concordance® Programming Language User Guide

66

Functions

16 Subdirectory. 32 Archived file. The file attributes can be or'ed together to find various file types. For example: findfirst("C:\*.*", 1 | 2 | 4); Return Value The name of the first file found that matches the file specification string and the attribute value. See Also findnext() Example main() { char f[128]; /* Erase all matching files. */ for(f=findfirst("\*.TMP",0); f[0]<>0; f=findnext()) erase(f); }

findline
Summary int findline(text line; int offset, length); Description Locates a line of text which contains the character at "offset" bytes from the beginning. The line is terminated by an end-of-line character. The end-of-line character is handled internally to Concordance and may not be compatible with other programs. The "line" parameter can be a data base field, a character array, or a text variable. It cannot be a numeric or date formatted field, or a numeric variable. Text begins with character 1. An 11 character char array would contain characters at offsets 1 through 11, though it would be indexed with values 0 through 10. Return Value Returns the offset into the text variable where the line begins, the length entry will contain the length of the line. The length is only for the text on the line, it does not include the end-of-line terminator. If the line isn't found the field is empty or offset is out of range then findline will return 0 and length will be undefined. Remember that a length of 0 is legal since some lines may be empty. See Also findpline(), findnline() Example main() { int file, i, width, db; /* Open the printer as a file. */ if ((file = open("prn","w")) == -1) { puts(0,0,"Couldn't access printer.");
Concordance® Programming Language User Guide

67

Functions return. int offset.width).i. See Also findfirst() Example main() { char f[256]. } findnext Summary text findnext()."stocks". Description Concordance® Programming Language User Guide 68 .width)."Couldn't open the database. f[0]<>0."stocks". */ close(file). return. Return Value A file name.substr(db->NOTE. closedb(db).width). /* Look for next hit in the next line. Description Locates the name of the next matching file first located using findfirst(). */ if ((db = opendb("c:\concord\research")) < 0) { puts(0. /* Erase all matching files.1). } findnline Summary int findnline(text line.i+width).0).TMP". writeln(file. } /* Open a data base for business. or an empty string if no file name is available. while (i > 0) { i = findline(db->NOTE.0. */ i = match(db->NOTE.i."). } /* Find and print every line in the */ /* note field that mentions stock. } /* Close all files before exiting. f=findnext()) erase(f). close(file). */ i = match(db->NOTE. length). */ for(f=findfirst("\*.

Description Locates the line of text preceding the line indicated by offset. int offset. */ /* Enter the loop. i. length). } return(error). Offset is an index into the field. length. See Also findline().length).1. Concordance® Programming Language User Guide 69 . fh) { int offset. print the line. then */ /* continue writing lines until there */ /* aren't any left to process. Return Value The value of findpline() is the offset of the first character of the preceding line. or character array.offset). Length will contain the length of the line when the function returns. Return Value findnline() returns the offset of the first character in the next line or 0 if there isn't a following line. offset = findline(db->i.addr(db->i. */ /* Get the offset of the first line. /* Wrap the field to fit in 40 columns. 40). findnline() Example /* Scan up several lines in the field. */ PrintField(int db. ** Watch for disk full errors in writeln(). findpline() Example /* Print every line in the text field to file. while((offset > 0) and (error == 0)) { if(writeln(fh.length)<length) error = 1. ** Returns offset of the nth line above or ** a 0 if there aren't enough lines. offset = findnline(db->i. */ wrap(db->i.Functions Locates the next line of text following the line indicated by offset. or 0 if there is no preceding line. or character array. The length parameter will contain the length of the preceding line. text variable. Offset is an index into the field. } findpline Summary int findpline(text line. offset. int error. text variable. length). See Also findline().

the 100th document in the data base may be the first in the query. lines) { int length. level -1 returns the name of the function that called the current function. The document number is the relative document number in the query. while((offset > 0) and (lines > 0)) { lines = lines . Returns a value less than or equal to zero if the query or data base is empty. field. Level is a number determining which function name is returned. Description Reads the first document in the current query. For instance. next(). The variables document. length). and query 0. the field number that contains the search word. will return 0's for the values of field and offset. and so on. nexthit(). prev(). and all previous call functions. Description Returns the name of the currently executing function. Level 0 returns the name of the current function. Mixing select and search mode queries will result in some values for field and offset containing 0's within the retrieved query set. docno(). If no query exists. i. offset.1. } return(offset). See Also last(). hits() func Summary text func(int level). and the offset into the field where the word occurs. Note: Select queries. If one or more are provided.Functions */ scanup(int db. } first Summary int first(int db. offset. Return Value Returns the physical document number of the first document retrieved in the query. offset). not the physical document number in the data base. and offset are optional. level -2 returns the name of the function two functions back. prevhit(). they will contain the document's number. count(). In this case the value of the document variable after issuing a first() would be 1. offset = findpline(db->i. Return Value Concordance® Programming Language User Guide 70 . document. field. the first document in the data base is used. Use the recno() function to get the physical document number. or if document could not be read.

Do not declare them.1) writeln(con. CPLSYNONYMS Words are returned in quotes. Simply use them. Retrieves words that are spelled like szWord. flag). The following flag parameters are integer values that are predefined for you. int certainty. string = func(i). Concordance will append to the file if it exists. They can be or’ed together with the | operator to combine functions.Functions The name of a currently executing function. if ((con = open("con". } } fuzzy Summary int fuzzy( int db.string. This takes longer than a sounds-like search. whose name and path is provided in szDestination. Description This function locates words that match the szWord parameter either in spelling or sound. Concordance® Programming Language User Guide 71 . text szDestination. text szWord. A value of 70 (70%) or higher is recommended. or an empty string if the level parameter is out of range. Never assign values to them. i = i . Example /* Display the names of all functions ** (currently called) on the screen. close(con). i. CPLSPELLEDLIKE CPLSYNONYMSORT Words are returned with the best matches first. Do not pass them in quotes."w")) >= 0) { for(i = 0. The matches are placed in a file. Concordance uses a sounds-like algorithm similar to soundex. certainty is the percent of a match for spelled-like words. Flag Parameter CPLSOUNDSLIKE Function Retrieves words that sound like the passed szWord parameter. The certainty parameter is used to determine if a word has similar spelling.len(string)). */ ListFunctions() { int con.

". Version V7. "getargs". int i. else pszArgs = pszArgs + chr(13) + chr(10) + "arg(" + str(i) + ") = " + pszCurrentArg. MB_OK). not just those beginning with @. getarg Summary text getarg(int argNumber). allowing a CPL program to retrieve them for exclusive use.Functions Return Value Returns a count of the words found to match the passed parameter. Return Value A text string containing the argument. MB_OK). } /* Display the args */ if (pszArgs == "") messageBox("No args found on the command line. pszCurrentArg. /* Loop for each arg */ while ((pszCurrentArg = getarg(i)) <> "") { /* Add the arg to the list */ if (pszArgs == "") pszArgs = "arg(0) = " + pszCurrentArg. /* Increment to the next arg */ i = i + 1. See Also getenv() .30 and later. Concordance will ignore any arguments beginning with @. Note that this function will also retrieve all command line arguments. Description Retrieves the command line argument passed to Concordance at startup. "getargs". An empty string indicates the end of arguments. putenv() Example main() { text pszArgs. } Version 5. else messageBox(pszArgs.32 and later Concordance® Programming Language User Guide 72 .

} getenv Summary int getenv(text name). You can view the current environmental settings by typing SET from the DOS command prompt. putenv() Example main() { text tempDir."The current directory is "+getcwd()). See Also chdir(). 40. Entries are added to the environment list with the DOS SET command."). Description The getenv() function searches the environment list for an entry matching name. if(tempDir == "") puts( 10. diskspace() Example main() { chdir("C:\DATA"). Return Value A text string containing the current working drive and directory. Return Value A text value containing the string assigned to the environment variable specified by name. Concordance® Programming Language User Guide 73 . tempDir = getenv("TEMP"). return(getkey()). "No temporary directory exists. Description Determines the full file path of the current working directory. or with the CPL putenv() command. "The temporary directory is "+tempDir).Functions getcwd Summary text getcwd(). The string is empty if there is no entry for name. else puts( 10. See Also getarg(). The search is not case-sensitive. puts(10.40. 40.

the file's name is returned in the filename[] array. char string[60]. if the user presses escape to quit file selection without making a selection. Return Value Key pressed. */ input() { int value. This function will not return until a key is ready. The mask can contain any characters valid in a file name. Description Read a key from the keyboard. The prompt string is displayed as the title of the file selection window. there is no error value. if (getfile("Database".22). } getfile Summary int getfile(char prompt[]. If the user selects a file. It returns an ASCII escape character. CR = 13. value = 0. including wildcard characters. return(db). fileName[]). Description A file selection window is displayed that shows the names of files that match the file mask."Enter code:").DCB". puts(5. See Also keypress() Example /* Prompt the user for the input code. Concordance® Programming Language User Guide 74 . } getkey Summary int getkey().10. Return Value getfile() returns a carriage return and a file name if the user selects a file. fileMask[]."*. value 27. cursor(5. Example OpenADataBase() { int db = -1.string) == CR) db = opendb(string).Functions return(getkey()).

txt[0] = 0. is returned if the user types past the last character in the field. The maximum number of characters it will retrieve is equal to width . char string[]. /* [Esc] */ break. return */ /* the input and the exiting key stroke. since all character strings must be terminated by a zero. "Huh?"). [int color[. key.background]]).1. See Also edit(). case 'S': case 's': value = 2. 25. Description Retrieves a line of input text from the user. LEFT. */ huh(char txt[]) { int CR. break. } Concordance® Programming Language User Guide 75 . The value 16. Ctrl-Y (Delete to end of line). width. break. It will handle END. return(key). } getline Summary int getline( int row. Return Value The keystroke that caused the function to terminate. and RIGHT. ESC = 27. The background color only has meaning under Windows. sizeof(txt). HOME. break. case 27: value = -1. } return(value). The LEFT and RIGHT cursor control keys will also cause it to return if the user tries to move out of the text they are editing. 20. key = 0.100). getnumber() Example /* Get a line of input from the user. txt). default: beep(45. CR = 13. while((key <> CR) and (key <> ESC)) key = getline(15. Color and background color are optional parameters. Any key that it cannot process itself will cause it to return. puts(15. a Ctrl-P.Functions while(value == 0) switch(getkey()) { case 'A': case 'a': value = 1. column. ESC. All other keys cause it to return.

The value 16. min. ESC. "Lines per page:"). Description Prompts the user for a number at the row and column coordinates on the screen. Return Value The key that caused the function to return. return(lpp). key. 0. 17. number will contain the original value when getnumber() was called. } getPrivateProfileString Summary int getPrivateProfileString( text szSection. col. puts(15.background]]). and will contain only places number of decimal places. places. lpp. text szFile). ESC = 27. int size.Functions getnumber Summary int getnumber( int row. min. [color[. char szDestination[]. 0). is returned if the user types past the last character in the field. See Also getline() Example /* Get the number of lines per page to print. a Ctrl-P. It will be no more than width characters wide. The number parameter will contain the user's entry when the function returns. If the user presses the [Esc] key. not just float. text szDefault. int width. Concordance® Programming Language User Guide 76 . while((key <> CR) and (key <> ESC)) key = getnumber(15. 5. text szKey. TextColor_ will be used if the color parameters are left off. max. The number will be between the min and max values. CR = 13. Description The getPrivateProfileString() function returns a string from the specified section in an initialization file. The number. and max parameters can be any numeric value type. */ GetLinesPerPage(int lpp) { int CR. 255. The color and background color parameters are optional. 1. float number.

You can create a NULL parameter by declaring NULL as a text variable and not assigning any value to it. If neither szSection nor szKey is NULL and the supplied destination buffer is too small to hold the requested string. the last string is truncated and followed by two null characters. then the default string is returned. This parameter cannot be NULL. and the return value is equal to size minus one. Return Value The return value is the number of characters copied to the buffer. See also writePrivateProfileString() Version Version 7. Concordance® Programming Language User Guide 77 .ini file. It must be large enough to hold the data. If either szSection or szKey is NULL and the supplied destination buffer is too small to hold all the strings. The function can insert a null character in the returned text to strip any trailing blanks. for instance. gettags Summary text gettags(int db. the return value is equal to size minus two. The fully qualified name of the . If this parameter is NULL. the string is truncated and followed by a null character. The length of szDestination in byes. In this case. not including the terminating null character. If the szKey entry cannot be found in the initialization file. depending on the operating system used. use sizeof(szDestination). The data is returned in this array of char. The name of the key whose associated string is to be retrieved.0 and later.Functions Parameter szSection Function The name of the section containing the key name. If this parameter does not contain a full path. the function copies all section names in the file to the supplied buffer. szKey szDefault szDestination size szFile Avoid specifying a default string with trailing blank characters. all key names in the section specified by the szSection parameter are copied to the return buffer. text szDelimiter). the system searches for the file in the Windows directory. If this parameter is NULL.

". See also accession(). Description Invokes Concordance Global Edit mode. The screen is automatically saved before entering this mode and restored after exiting. Return Value A text string containing the document’s tags. See also istagged() Example /* Locate tags. Description Retrieves the document’s unique universal identifier.30 and later. Each tag is separated by the szDelimiter parameter. Only V7. Concordance® Programming Language User Guide 78 . Records in earlier databases will return empty strings. Unlike accession numbers. Delimit with semi-colon & newline. global Summary global(int db). See the Concordance manual for a description of Global Editing. Version V8 and later. */ text szResult. An empty string if the document is not tagged. Return Value A text string containing the document’s UUID. Return Value None." + newline()). getuuid Summary text getuuid(int db).0 and later databases contain UUIDs. gotouuid() Version V7. This is a unique serial number assigned to each record in a Concordance database. szResult = gettags(db. the UUID is unique across databases.Functions Description Retrieves all tags applied to the current document.

next(). document. offset). recno().0 and later databases. if they are passed. readdoc() gotoaccession Summary int gotoaccession(int db. Accession numbers are returned by the accession() function. Return Value Returns a value less than or equal to zero if you to try to move past the last document in the current query. The offset indicates the offset of the retrieved word from the beginning of the field. accessionNumber). field. They are used by Concordance internally in place of physical record numbers for record tagging and full text searching in V6. prev(). docno().0 and later. On return. Description Reads the specified document in the current query set. field. The document. gotophysical(). field. last(). gotophysical Summary int gotophysical(int db. field. field number and word offset. and offset parameters. readdoc() Version Versions 6.Functions goto Summary int goto(int db. Additional calls to nexthit() will retrieve information about the other items in the list. will contain the relative document number. Concordance® Programming Language User Guide 79 . the document. document. Return Value Returns zero if successful. offset). Description Locates and reads the document that matches the accession number. The hit list is positioned on the first hit for the document. See Also accession(). first(). gotouuid(). goto(). Fixed field searches will return offset values of zero. See Also recno(). and offset parameters will contain information about the first word in the document. docno().

Description Locates and reads the document that matches the unique universal identifier text. text szUUID). field. field number and word offset. The offset indicates the offset of the retrieved word from the beginning of the field. Returns a value less than or equal to zero if the physical document can't be located in the current query. the document. Only the database handle and document number parameters are required. They are used by Concordance internally in place of physical record numbers to link an annotation to a record. Use the NOTEPARENT field in a database-notes database to obtain the parent record’s UUID. On return.Functions Description Locates the specified document in the current query set. the last document in the list becomes the current document. The document. Return Value Returns zero if successful. The note is attached to this record. Then use the UUID with gotouuid() to retrieve the parent record. field. not the relative document number in the current query. hits Summary int hits(int db). gotoaccession() Version V7. In this case. See Also goto() gotouuid Summary int gotouuid(int db. and offset parameters will contain information about the first hit word in the document if it was located successfully.0 or later database. Return Value Returns the physical document number if successful. will contain the relative document number. and offset parameters. Additional calls to nexthit() will retrieve information about the other items in the hit list. This function should not be used with concatenated databases as more than one database can have the same physical document number.30 and later. The hit list is positioned on the first hit for the document. Concordance® Programming Language User Guide 80 . UUIDs are returned by the getuuid() function for any V7. See also getuuid() . Fixed field searches will return offset values of zero. if they are passed. The document number is the physical document number in the underlying data base.

Concordance loads up to 60. and it cannot flow the text into following paragraphs. This will cause Concordance to treat all carriage returns as soft returns. A nonzero value would indicate that the user aborted the import by pressing the [Esc] key.000 characters per field unless the optional maxBytes parameter specifies another maximum. or an error reading or locating the import file. Return Value A zero if no error occurred. The text file is a plain text file. This parameter should be set to zero to remove blank lines. int anchored. word wrapping all text until it finds an indented or empty line. Concordance will keep blank lines if the blanks parameter is 'B'. See Also load() Example LoadDeposition(int db) { Concordance® Programming Language User Guide 81 . Import will break the file into several documents if it is larger than 65. If the file contains data for several documents. int blanks. Description Loads the text file. If the keepfile parameter is 'K'.000 characters or maxBytes. Concordance will store the file's name in parentheses on the first line of each document created. they are separated from each other by a line with the delimiter string on it. Concordance will automatically trim any trailing spaces from each line it loads. into the selected field and appends the new document(s) to the end of the data base. char filename[]. ASCII format. See Also count() import Summary int import( text db->field. int wrap. char delimiter[].e. or paragraphs separated by blank lines. whose name is passed in filename[]. The wrap parameter should be set to a 'W' if your text has indented paragraphs.. Concordance will assume the delimiter string is flush left if the anchored parameter is an 'A'. int keepfile. The file name will appear on the line by itself. a disk or data base full condition. [int maxBytes]). Return Value Number of hits in currently retrieved search list. i.Functions Description Returns the count of words located by the active query.

This function preserves annotations and rich text formatting. The dictionary file and inverted text files are erased before this command begins.e. Return Value None. The insertText() function inserts a block of text. db->FIELD = db>FIELD + szText may cause all annotations to be misplaced and rich text formatting to disappear. int offset). Description Full screen import menu as described in the Concordance Reference Manual. Description Data base is indexed from scratch. text szText.string) == CR) import(db->depo."".*".0. Concordance® Programming Language User Guide 82 . if (getfile("Deposition".'K'. See Also loadfs() index Summary int index(int db). Return Value Zero if successful.Functions int CR. The screen is automatically saved before entering this mode and restored after exiting. the szText parameter. opendb() insertText Summary insertText(db->FIELD.0). Description The first parameter identifies a field in the database.string. The db parameter must be a value returned by a call to opendb(). char string[60]."*.. CR = 13. The user is not prompted before the files are erased. See Also reindex(). return. } importfs Summary importfs(int db).0. Simply assigning text to a field does not preserve annotations or rich text. into the field. i.

isdigit() isdeleted Summary int isdeleted(int db). Return Value Returns a nonzero value if the character is alphabetic. Description Checks if the document is marked for deletion. Return Value Nonzero if the document is marked for deletion. See Also isalpha(). Description Tests the character value to determine if it is in the set a to z. Concordance® Programming Language User Guide 83 . isdigit() isalpha Summary int isalpha(char ch).Functions Return Value The number of bytes inserted. or A to Z. See Also isalnum(). or short. or a zero if it is not alphabetic. Description Tests the character value to determine if it is in the set a to z. zero if it is not marked for deletion. char. or A to Z. float. int. isalnum Summary int isalnum(char ch). ch can be any numeric value. Returns a zero if it is not. Return Value Returns a nonzero value if the character is in the alphanumeric set of characters. or 0 to 9. See Also deleteText() Version Concordance V7 and later.

*/ DelCount(int db) { int count. Attempting to highlight the keywords on the screen. See Also isalnum(). return(count). recall(). cycle(db) if (isdeleted(db)) count = count + 1. isalpha() isedited Summary int isedited(int db). Description Determines if the full-text indexable fields in the current document have been edited or appended to the database since the last time the database was reindexed.Functions See Also delete(). isfield Summary int isfield(int db. Return Value A nonzero value if the document has been edited or modified since the last reindex. text fieldName). pack() Example /* Count the documents marked for deletion. Concordance® Programming Language User Guide 84 . } isdigit Summary int isdigit(char ch). Description Tests the character value to determine if it is in the set 0 to 9. Return Value Returns a nonzero value if the character is a digit. and a zero if the character isn't. or to underline them on a printer may result in the wrong words being highlighted. Documents located in a full text search that have been edited may not actually match the search conditions.

Description Tests the character to see if it is a lower case letter. Return Value Returns the nonzero field number if the field exists in the current data base. Useful with concatenated data bases and the report writer. upper() isnexthit Summary int isnexthit(int db). someData). lower(). isnexthit(db). Return Value Returns a nonzero value if the character is lower case. See Also nexthit() Concordance® Programming Language User Guide 85 . in the set a to z."SUMMARY")) ? db->i : ""). Description Determines if there is another hit in the current document.Functions Description Determines if the named field exists in the data base. otherwise zero. Return Value Returns a nonzero value if there is a hit. } } islower Summary int islower(char ch). cycle(db) { someData = ((i=isfield(db. writeln(fh. See Also isupper(). Example /* Count the hits in this record */ for (i = 1. A hit is a word located in a search. fh) { int i. text someData. i = i + 1) nexthit(db). and a zero if it is not a lower case letter. Example printSomeData(int db.

Description Checks if the document is currently tagged. form feed. respectively. isupper Summary int isupper(char ch). The parameter db is a handle an open database. text tagName]). if (tagged(db. Return Value A nonzero value is returned if the character is a space. To determine if ANY tag has been applied use the following code: text NULL.33 and later isspace Summary int isspace(char ch). vertical tab. 12. and 13. 9. 11. in the set A to Z. tag(). White space characters include the space. Calling istagged() without a tagString determines if the default tag. and carriage return. See Also gettags(). If the optional tagString is passed. "". Description Tests the character to see if it is a white space character.NULL)) Return Value Returns a zero if the document is not tagged. Description Tests the character to determine if it is an upper case letter. horizontal tab. tagquery() Version The tagName parameter is only valid in versions 5. istagged Summary int istagged(int db[. the return value only applies to that tag. 10. and a zero is returned if it is not a space character. ASCII codes 32. line feed.31 and later.Functions Version 5. has been applied to the document. Return Value Concordance® Programming Language User Guide 86 . nonzero if it is tagged.

If the value of radix is 10. int radix). upper() itoa Summary int itoa(int value. An error return indicates a bad file name. snapshot() Concordance® Programming Language User Guide 87 . 16 )). 19.QRY to saved query files.Functions Returns a nonzero value if the character is upper case. which is the decimal 25 in base 10. } keep Summary int keep(int db. getkey(). Return Value The number as a string in the requested base. or a full disk. Description Saves all queries in the current session to the named file. itoa( 25. and a zero if the character is not an upper case letter. Description Converts an integer to a plain text. and 11001. 16 and base 2. 10. Concordance normally appends the file extension . then itoa() will prepend a minus sign to the result. puts( 11. See Also exec(). The keep() function does change the file name passed to it. See Also islower(). See Also str(). itoa( 25. main() { puts( 10. 10 )). text filename). 10. itoa( 25. 2 )). puts( 12. 10. num() Example The following program displays the values 25. value in base radix notation. ASCII. lower(). and the number is negative. Return Value Returns a nonzero value if an error was encountered while saving the queries.

keypress does not read the key from the buffer if one is ready. See Also getkey() Example main() { int ESC. will return field values of zero.Functions keypress Summary int keypress(). On return the document. Additional calls to nexthit() will retrieve information about the other items in the hit list. and offset parameters. It immediately returns to the caller. Description Checks to see if there is a key in the input buffer. such as query zero. */ while((keypress() <> ESC) and (finished == 0)) finished = DoSomething(). offset). field. The document's number is its position relative to other documents in the query. */ if (keypress() == ESC) getkey(). Check the field parameter before using it to access a field's data. field number and offset into that field that indicates the offset of the retrieved word. field. otherwise it returns the value of the key that will be returned by the next getkey() call. Some searches. if they are passed. } last Summary int last(int db. Description Advances to the last document retrieved in the current query set. finished = 0. Return Value Returns a zero if no key is ready. whether or not a key is ready. will contain the relative document number. /* If the user hit the ESC key */ /* to terminate processing early. */ /* read it from the buffer. ESC = 27. document. The hit list is positioned on the first hit for the last document. Return Value Concordance® Programming Language User Guide 88 . /* Loop until finished or until */ /* someone hits the ESC key. finished.

and offset parameters are passed. quote and newline parameters off if transferring data between Concordance data bases. 254 and 174 respectively. Description Determines the length. prevhit(). nexthit(). However. or if the document could not be read. Return Value Integer length in bytes of the parameter. prev(). newline. char filename[]. color]]). You should always renumber the fields before loading the data base. they are required if the screen status parameters are passed. quote and newline.Functions Returns the physical document number of the last document retrieved by the query. The results are not valid for numeric or date fields. the field order in several full screen modes including Print. See Also first(). Load. You can assign any number from -128 to 127. comma. [int row. Concordance uses. count(). The file must contain data base records in delimited ASCII format. The optional parameters. See Also Concordance® Programming Language User Guide 89 . character array. It is recommended that you leave the comma. are used to delimit the fields during the load process. A count less than expected can indicate a disk full condition. Returns a value less than or equal to zero if the query or data base is empty. is set by assigning a number to the "order" entry of the field definition. or data base field. quote. [int comma. If they are left off Concordance will use its internal ASCII default values. and changes. See the for-loop example below. field. Description Loads the data base from the parameter file name. docno() len Summary int len(text note). See Also sizeof() load Summary int load( int db. but Concordance will only load fields with consecutive numbers from 1 to the last field number defined in the data base. Return Value A count of the number of documents loaded from the delimited ASCII file. of the text variable. Information about the hit word is returned only if one or more of the document. and the order in which they are loaded. next(). and Unload. in characters. The fields loaded. column. 20. or that the user pressed the [Esc] key to cancel the operation.

"helpdesk.order[i] = i.dat") <> count) puts(0. count = db."helpdesk. Return Value None.0.dat")."). else { zap(db). else { erase("helpdesk. i. } } loadfs Summary loadfs(int db)."). Concordance® Programming Language User Guide 90 . if (load(db."db->DATE").. /* Permanately sort all records in the */ /* data base in ascending order."Error reloading data. it is restored after returning.documents. */ for(i = 1. */ if ((db = opendb("helpdesk")) <> -1) { sort(db. Description Invokes Concordance full screen load mode. This step is necessary */ /* since the order previously set. i <= db.0."Error unloading data base.fields.. if (unload(db. Never assume the */ /* order includes all fields. unloadfs(). getkey(). loadfs()."Press any key to continue. count. */ /* or set in Print."). i = i + 1) db. index(db).1. puts(0. } } closedb(db).dat") <> count) puts(0. is retained */ /* until reset. import() Example main() { int db. /* Renumber all fields to unload in */ /* order. The screen is automatically saved before entering Load.Functions unload().

such as loadfs() or global(). unless they have been unlocked by a call to the unlockdoc() function. a nonzero value if unsuccessful. locked() locked Summary int locked(int db). or using one of the Concordance full screen functions. Description Will attempt to lock the current data base for exclusive use. will unlock the document. See Also unlockdb() lockdoc Summary int lockdoc(int db). Return Value Returns a zero if the lock operation was successful. Description Will attempt to lock the current document in the network version of Concordance. but none of the changes will be saved to file. Concordance® Programming Language User Guide 91 . See Also unlockdoc(). Description Determines if the current document is locked. Documents are automatically locked by Concordance when read into memory. This will always succeed in single user versions of Concordance. This has no effect in non-network versions of the program. and modified. A locked document can be used. Reading another document. Concordance will make ten attempts to lock the document before giving up. Documents are automatically locked in network versions of Concordance. the document is automatically locked again when it is reloaded. The data base cannot be accessed by other network users while it is locked.Functions lockdb Summary int lockdb(int db). Your program should unlock them as a courtesy to other network users if you do not intend to edit or modify them. A locked document cannot be changed and saved to file by other users. The data base is automatically locked and unlocked by Concordance during pack and modify procedures. edited. However. Network versions will fail if another user is accessing the database. Return Value Returns a zero if the lock operation was successful.

lower(author)). trys = trys .author).document).0. Does not change the original. A value of one if you have locked the document by a call to lockdoc(). and a value greater than one if the document is locked by another user on the network. See Also lockdoc() Example getdoc(db. */ return(locked(db) == 1). author = "E E Cummings". See Also capitalize().0. /* Return a nonzero if we got a lock. } Output: e e cummings E E Cummings Concordance® Programming Language User Guide 92 .document) { int trys. puts(1. readdoc(db. /* Try to get document up to 10 times.Functions Return Value A zero if the document is not locked.1. upper() Example main() { text author. Description Produces a duplicate of the variable in lower case. } lower Summary text lower(text author). while((trys > 0) and locked(db)) { readdoc(db.document). */ trys = 10. Return Value The parameter in lower case. puts(0. Non-network versions of Concordance will always return zero. } lockdoc(db).

Use offset = lseek(handle. If that is unsuccessful then the system may prompt the user for a password. carriage returns. 0. Description Maps a network printer or disk drive. as an offset in bytes from the beginning of the file.0 and later mapDevice Summary int mapDevice(text localName. as follows: Mode 'B' Move relative to the beginning of file. offset. The mode indicator tells lseek how to move.Functions lseek Summary int lseek(int handle. Concordance® Programming Language User Guide 93 . remoteName. Return Value Returns a duplicate of the string. remoteName is the network device name. The first byte in the file is at offset zero. 'P') to determine the present location in the file. Description Removes all leading white space from the text variable. trim() Version 6. localName is the local device name such as "lpt1" or "f:" that you will use to access the device. Return Value The new position in the file. user. Returns a -1 if the move was unsuccessful. Create a NULL parameter by declaring a text variable and not assigning a value to it. Description Moves the next read or write position in the file to the specified offset. character array. password). See the example below. White space consists of spaces. or field. ltrim Summary text ltrim(text string). Mode 'P' Move relative to the present position. If user and password are NULL parameters then mapDevice() will use the currently logged user. such as "\\MyServer\sys". does not modify the original. mode). and line feeds. See Also rtrim() . Mode 'E' Move relative to the end of the file. tabs.

"<B>". Concordance® Programming Language User Guide 94 . The function should be called with a database field: text markedText. } markhits Summary text markhits(text field.) */ /* Output the text using Internet HTML (Hyper */ /* Text Markup Language.) */ OutputHTML(int db. NULL. Version 5. "</B>"). mapDevice("T:". text szText. Example /* Write fields from db to fh (file handle. marking hits with the beginMark and endMark text sequence. for (k = findline(szText. This would include situations where Concordance is being used with an Internet Server to return data in Hypertext Markup Language (HTML) for Internet Web Browsers.Functions Return Value Zero indicates success. 65000).fields. j. int fh) { int i. "\\MyServer\sys". 1. "</B>"). Description Retrieves the database field. See also unmapDevice() Version 7. k. "<B>". j = j + 1) { switch(db. for (j = 1.j <= db. markedText = markhits(db->TEXT.42 and later. endMark). NULL). ln). Return Value The database field as a text value. This is used primarily for adding word processing bold-on and bold-off sequences to search terms located in a query. ln. k > 0.type[j]) { case 'P': szText = markhits(wrap(db->j.30 and later Example main() { text NULL. beginMark.

ln)).name[j]+" = </B>" + trim(db->j) + "<BR>". k).name[j]+" = </B>" + str( db->j. len(szText)).places[j]) + "<BR>". k. letterString).name[j]+" = </B>" + dtoc(db->j. db. The length parameter is optional.length[j]. at most. } } } /* OutputHTML() */ match Summary int match( text target. case 'T': writeln(fh. length bytes. szText="<B>"+db. Description Locates the search string in the target beginning offset bytes into the target and looking for. "<BR>". Description Locates the first occurrence of any character from the letter string in the target search string. int offset. Return Value The index to the location of the search string in the target string. search. See Also matchc() matchc Summary int matchc(text target. db. case 'D': writeln(fh. len(szText)). szText="<B>"+db. break. case 'N': writeln(fh. szText="<B>"+db.Functions k = findnline(szText.length[j]) + "<BR>". db. break. if it is left out match will look through the entire target string from offset to the end. length ). write(fh. 4). len(szText)). ln)) { write(fh. break. } break. Return Value Concordance® Programming Language User Guide 95 . A zero if no match was made. addr(szText.

"abABC")) . See Also min() memavl Summary int memavl(). Note that in the following example. This can be important if your program concatenates large character strings... first. /* Check if there is enough memory to join */ /* two large text fields. second) { text data. or float. Return Value The greater of the two values. y). This value will change while your program runs. int. Concordance uses available memory to manipulate the large blocks of text and will produce an insufficient memory error if it cannot allocate enough room. */ Concordance® Programming Language User Guide 96 . This test avoids */ /* a FATAL "Insufficient Memory" error. Example concatenate(int db. then the offset returned will be that of the letter C. */ if (memavl()<len(db->first)+len(db->second)) { /* There wasn't enough space. Description Determines the maximum amount of memory that is available for use by your program.Functions The offset of the first matching letter from letterString found in the target. Description Determines which value is greater. The parameters x and y can be char. if the character C is found to occur in the target search string before the letters b and a. Return Value The largest block of memory that Concordance can allocate for use by your program. Example if (i = matchc(db->TEXT. See Also match() max Summary float max(float x. Returns a 0 if no match was found. max() will make the proper comparison regardless of type. short.

is not performed with memcpy(). read(fh."). getkey(). join the fields. short. including zeroed dates.sizeof(string)). */ memset(string. } else /* Enough space. This function offers a fast way to initialize a string or other variable to a set value.sizeof(string)). Return Value The destination value. float. text.1. This function should be used with caution as data type and range parameter checking that is performed with direct assignments. Example /* Copy to a date field to avoid math conversions */ /* on invalid entries. source. int bytes). */ memcpy(db->DATE. but it will not provide you with zero terminated strings. Return Value The destination value. Consequently memcpy() will perform faster in some cases. See Also memset() memset Summary memset(destination. return(data).0. char value. puts(0. } memcpy Summary memcpy(destination.Functions /* Display a non-fatal message. */ data = db->first+db->second.string. */ beep(45. Description Copies the source data value to the destination for the specified number of bytes. int length)."19930900". int. Destination can be any left-side-value including char. Example /* Clear an array before reading from disk. a = substr(b.8)."Can't join the two fields. Concordance® Programming Language User Guide 97 .0. or a data base field.10). Source and destination should be the same data type.200). Description Sets bytes in destination to value for length specified. but that is not required.

mymenu. the quick key list must contain only one key for each item in the menu.next. mymenu[1] = "Search". The "next" parameter specifies the first option in the text array[] to highlight when the menu is displayed. The first item in the menu.50. int db. ESC. The menu is not cleared from the screen when the user makes a choice. but they should appear at the end of the list. mymenu[0] = "Research Technology Library". the menu() function will attempt to highlight the item which corresponds with the key. case 2: /* Browse the data base. mymenu[2] = "Browse". */ search(db). col. only upper case letters should be in the quick keys list. The quick keys parameter.10. which do not correspond to displayed menu items. text array[]."SBEX"). Additional keys. item zero. is displayed as the title of the menu. Return Value The number of the menu item selected or 0 if the ESCape key was pressed. brow. Keystrokes read by menu() are converted to upper case before processing. ESC = 27. mymenu[3] = "Edit". If the user pressed a quick key. will cause the menu to return if any of the keys in the list are pressed. The menu() function will leave the selected menu item highlighted. break. if ((db = opendb("library")) >= 0) next = 1. can be included in the list. The menu is case sensitive. and they must be in the same order as the menu items. next. text "QUICK"). Description Displays a menu in a window whose screen coordinates are specified by the two row and column parameter pairs. See Also btmenu() Example main() { text mymenu[4].Functions See Also memcpy() menu Summary int menu( int row. switch(next) { case 1: /* Do a search. Therefore. which is optional.30. bcol. */ Concordance® Programming Language User Guide 98 . int next. while (next > 0) { next = menu(5.

The information icon. case 3: /* Edit retrieved documents. szTitle. break. Retry. */ puts(0."Memory: "+str(memavl())). Style is any one of the following values: Parameter MB_ABORTRETRYIGNORE Description The message box contains three push buttons: Abort. } } closedb(db). is displayed. for instance MB_YESNO | MB_ICONQUESTION. The first button is the default. The style parameter determines the return value. break. They are all integers. case 'X': /* Option X isn't ON the menu. break. Combine the style parameters together with the | operator. MB_DEFBUTTON1 MB_DEFBUTTON2 MB_DEFBUTTON3 MB_ICONEXCLAMATION MB_ICONINFORMATION MB_ICONQUESTION MB_ICONSTOP Concordance® Programming Language User Guide 99 . */ editfs(db). */ /* Display available memory. You do not need to declare them to use them. The second button is the default. A question-mark icon appears in the message box. int style).0. The first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.Functions browse(db). All parameters are predefined by the CPL interpreter. } messageBox Summary int messageBox(text szText. a lowercase letter "I" in a circle. */ /* it is in the quick key list. and Ignore. The message box displays an exclamation-point icon. The third button is the default. Description Displays a standard Windows message box with the szText parameter as the message and szTitle as the message box title. The message box displays a stop-sign icon.

Depending on the style parameter. If a cancel button is available and the user presses the [Esc] key. or float. Retry button was selected. Return Value The lesser of the two values. Abort button was selected. Cancel button was selected. Concordance® Programming Language User Guide 100 . int. y). min Summary float min(float x. Ignore button was selected.53 and later. min() will make the proper comparison regardless of type. IDCANCEL is returned. OK button was selected. No button was selected. The parameters x and y can be char. short. Yes button was selected. The message box contains two push buttons: Yes and No. The message box contains two push buttons: OK and Cancel. The message box contains three push buttons: Yes. generally as a result of a low memory condition. The message box contains two push buttons: Retry and Cancel. All return value parameters are predefined by the CPL interpreter. and Cancel. Return Value A zero is returned if Windows could not create the message box. the return values are listed below. You do not need to declare them to use them.Functions MB_OK MB_OKCANCEL MB_RETRYCANCEL MB_YESNO MB_YESNOCANCEL The message box contains one push button: OK. No. Description Determines which value is smaller. Parameter Description IDABORT IDCANCEL IDIGNORE IDNO IDOK IDRETRY IDYES Version 6.

Return Value None. See Also createfs(). Concordance® Programming Language User Guide 101 . It allows the user to modify the structure of the data base whose handle is db.Functions See Also max() mkdir Summary int mkdir(text directoryPath). createdb(). The screen is automatically saved before entering modify and restored after exiting. Description The mkdir() function creates a new subdirectory with directoryPath name. The date must be an integer value representing the date. nonzero otherwise. Return Value mkdir returns zero if successful. directoryPath can be either and absolute path name or relative to the current working directory. Description Extracts the month from the date. See the Concordance User Guide for a full description. the return value of the ctod() function. or either of these values stored as an integer. Description Concordance full screen data base modify command. See Also chdir() . struc() month Summary int month(int db->field). It will return immediately when called from the Runtime module. rmdir() . erase() modify Summary modify(int db). rename() . though any passed numeric value will be converted by month() to integer format before processing. The parameter can be a date formatted field. getcwd() . Note: This function is not implemented in the Concordance Runtime Module.

prev(). or workstation ID. index). docno(). year(). See Also last(). Return Value Returns the physical document number of the next document retrieved in the query. Return Value Text string containing the user's sign-on ID. or if an error was encountered reading the document. Description Determines the user ID. document. See Also day(). The hit list is positioned on the first hit for the document.12. 1 . weekday() netuser Summary text netuser().Functions Return Value The month of the year as an integer value. Return Value A carriage return/line feed combination. count(). Primarily used in the report writer. Additional calls to nexthit() will retrieve information about the other items in the hit list. nexthit(). newline Summary text newline(). next Summary int next(int db. for the network. Description Returns a hard carriage return. Returns a value less than or equal to zero if the current document is the last in the query. Description Concordance advances to the next document in the current query. first(). See last() for more information about returned values. field. prevhit(). hits() Example /* Cycle through every document in the data Concordance® Programming Language User Guide 102 .

for(i = docno(db). See Also goto(). Concordance® Programming Language User Guide 103 . Description Moves to the next hit in the current query. and offset parameters are passed. Information about the hit list item is returned. isnexthit(). first(). i = next(db)) db->state = upper(db->state). } nexthit Summary int nexthit(int db. The number is converted to int type before the inversion. The document. field. and offset parameters are optional. ** converting the STATE field to upper case. not(2) returns the value 1111111111111101. */ StateToUpper(db) { int i. prev(). Return Value The number's one's compliment.Functions ** base. count(). converts the number to its one's compliment. last(). hits() not Summary int not(int number). field. document. Return Value Information about the hit word is returned only if one or more of the document. next(). starting with the current document. i > 0. index). prevhit(). Description Logically inverts the number. num Summary float num(char string[]). See Also Bitwise operators | and &. The binary representation of 2 is 0000000000000010. If this moves to the next document. db is a valid database handle returned by a call to opendb(). field. then that document is read. Returns a value less than or equal to zero if the document could not be read.

"". Return Value Numeric representation of character string. The function is reset and zero is returned if the exitFunction menu string was not matched. something = " 1982 was a good year. The conversion begins with the first numeric character. See Also itoa(). int i. */ } onexit Summary int onexit(text exitFunction). /* i now equals 1983. Version 8. zero if onexit() has been reset. str() Example main() { text something. The exitFunction parameter is a string containing any standard item that appears in Concordance's menus. Description Opens a file for use and returns that file's handle. such as "Browse" or "Table.0 and later.Functions Description Converts a character string to a number. type[]). open Summary int open(char string[].". "w" Create empty file for writing. and it ends when the first nonnumeric character is encountered." Use an empty string. Concordance® Programming Language User Guide 104 . to reset the onexit() function. erases file if it exists. Description Runs a Concordance menu command after the CPL program terminates. Blank spaces are ignored in the conversion. The number is converted to a float type. but the result of num() can be assigned to any numeric type. The handle must be used to access the file. Type can be: "r" Open existing file for read only access. Return Value A nonzero value if successful. i = num(something) + 1.

ADJ1 .ADJ99. -1 if not successful. if available memory. erase() opendb Summary int opendb(char string[]). See Also closedb() operator Summary operator("ADJ"). readln(). erases file if it exists. OR. Description Opens the database and returns a file handle which must be used to access the data base documents. Up to 16 data bases may be open at one time. NEAR.NEAR99. NOT. never use apostrophes. its fields. Return Value None. Use caution with "w+" and "w" as they will reset a file and destroy its contents if the file already exists. "a+" Open or create file for appending and reading. Return Value A file handle if successful. Description Sets the default operator recognized by search(). AND. Return Value A -1 indicates an error opening the data base. XOR. The first document in the data base is automatically read into memory by the opendb() command. "r+" Open existing file for reading and writing. overlayfs Summary overlayfs(int db). write(). See Also read(). close(). writeln(). exist(). Note that both parameters must be either text or char arrays. and statistics. The operator can be any valid search operator: ADJ. "w+" Open file for reading and writing. Concordance® Programming Language User Guide 105 . no reading. Always use quotes to enclose the parameters. Any other positive value is a data base handle. NEAR1 . they can not be character literals as in 'r'.Functions "a" Open or create file for appending.

Return Value Zero if successful. pack Summary int pack(int db).'C'."|"+pad("hello". The screen is automatically saved before entering Pack and restored after exiting. } Output: |hello | | hello | | hello| Concordance® Programming Language User Guide 106 . adds or truncates lines to maximum height Return Value A duplicate of the original string padded with the specified number of spaces. The screen is automatically saved before entering Overlay and restored after exiting.'R'. align.0. or right justified within the spaces depending on the value of align: L String is left justified C String is centered R String is right justified V Vertical alignment. center."|"+pad("hello". Return Value None. puts(2. The data base is packed.Functions Description Invokes Concordance full screen Overlay mode. int width).21)+"|").21)+"|").0.21)+"|"). The string is truncated if the width is less than the length of the string. The string will be left.0. Description Duplicates the string and pads it with spaces to width number of characters. The returned text value will never be longer than width. Description Invokes Concordance full screen pack mode."|"+pad("hello". puts(1. Example main() { puts(0. all documents marked for deletion are removed. pad Summary text pad(char string[]. The search files are optimized if there is enough room on the disk.'L'.

hits() prevhit Summary int prevhit(int db. there is no previous document. offset). Description Concordance moves to the previous document in the current query. document. prevhit(). then that document is read. The Windows version uses the system clipboard. and index parameters. Returns a value less than or equal to zero if the current document is the first in the query. and offset parameters are optional. See Also cut() prev Summary int prev(int db. index)..e. db is a valid data base handle returned by a call to opendb(). or if the query set is empty. first(). field. Description Returns a copy of the data in the cut and paste buffer. If this moves to the previous document. field. document. The same data is returned over and over again until it is replace by a cut() or by the user from the editor.Functions paste Summary text paste(). next(). nexthit(). i. An error reading the document from file will also return a value less than or equal to zero. Return Value The contents of the cut and paste buffer. Return Value Concordance® Programming Language User Guide 107 . Information about the first hit in the document is returned in the document. Return Value Returns the physical document number of the previous document retrieved in the query. Description Moves to the previous hit in the current query. The document. field. See Also goto(). Information about the hit list item is returned. count(). field. last(). These parameters are optional. See first() for more detailed information on the return values.

Example PrintThisList(int db) { /* Example for DOS and OS/2 */ int fileHandle. if ((fileHandle = open("LPT1". next(). Any option not specified in the print format file is left alone.count(db).1. reportfs() printfs Summary Concordance® Programming Language User Guide 108 . and prints the document range in the current active query. prev(). and offset parameters.e. last(). first(). statusColor]]]). count().10. outputFileHandle. field.. page length. The Windows version displays the print status in a dialog box. it is not reset by its absence."w")) >= 0) { print(db. The Windows version requires a valid print format file parameter. statusColumn[. [int statusRow[."HPLASER". Information about the hit word is returned in the document. nexthit(). For instance.fileHandle.FMT. and are created with the Documents/Print/Save menu option. there is no previous document. firstDocument. The print format file parameter can be a file name or an empty string. text printFormatFileName. The output is sent to the open file whose handle is outputFileHandle. It ignores the outputFileHandle parameter and prints to the current device. } } See Also printfs(). and the setup string.Functions Returns a value less than or equal to zero if the document could not be read or if the current hit is the first in the data base. The settings are stored as plain text. See Also goto(). the file could contain only print margins. Print format files store all settings that can be set in full screen print mode. "".40). i. Description Loads the print format file. lastDocument. Return Value None. They can be edited with any text editor. The document count is displayed on the screen at statusRow. file extension . report() . statusColumn in statusColor. to accept the current settings. close(fileHandle). hits() print Summary print( int db.

The environment list consists of a name and a value. The following is an example of a set value. See description in the Concordance Reference Manual.Functions printfs(int db). main() { Concordance® Programming Language User Guide 109 . -1 indicates failure. putenv Summary int putenv(text nameAndValue). Description This function places the value into environment list. Description Invokes the Concordance full screen print menu. reportfs() program Summary text program(). Consequently. Return Value Zero indicates success. Return Value The name of the CPL program with the full DOS path if available. See Also getenv() Example The following program assigns a string to an environmental value and deletes another value. The screen is automatically saved before entering this mode and restored after exiting. PATH=C:\.C:\DOS Values are placed into the environment by passing the name followed by an equal sign and the value. Description Returns the name and DOS path of the currently running CPL program. These can be displayed from the DOS prompt by typing SET. Space for environment variables is limited. Items are deleted from the environment by passing the name followed by an equal sign only. The full program path may not be available if the program was executed as a command line prompt with Concordance. See Also print(). Return Value None. the putenv() function may fail if there isn't enough room to add another value.

column. Windows uses colors in the range 0 . char string[]. background]]). putenv("UPDATE="). Description Concordance® Programming Language User Guide 110 .255.215. } puts Summary puts(int row. col = col + 6) for(row = 0. See Also putsl() Example main() { int row. defined in your program. RGB(190. [int color[. col. green. } Return Value None. char string[]. [int color[. Description Displays the text variable or character string on the screen at the row and column. row = row + 1) { puts(row.190.777. "Color ". Color and background color are optional parameters. For DOS and OS/2 the color can be any value from 0 to 255. col < 74. /* Fill the screen with colors. grn.16. color. RGB(char red. col. row < 25. The colors consist of three values: red. } } putsl Summary putsl(int row. col. They are created by the RGB() function. */ for(col = 0. Only Windows will use the background color parameter. background]]). though values 127 and over may blink. blu) { return(((blu*65536)|(grn*256)|red).255). length. as follows: int white = RGB(255. color = color + 1. in the specified color.190)).Functions putenv("USERID=SMITHJ"). and blue. color.

while((offset > 0) and (line < 25)) { putsl(row. To use the entire data base use query(db. The query is used by all functions until it is changed by a call to search(). offset) { int length. row = 0. The color for Concordance normal text is used if the color and background parameters are omitted. } query Summary int query(int db. } /* Return the offset of the next line. See Also Database information variables db. length). Query 0 is defined to contain every document in the data base. Background color is only used by Windows. The string parameter is optional. Concordance® Programming Language User Guide 111 . or if an error was encountered reading the query from disk. length). 0). The length parameter specifies the number of characters in the string to be displayed. Return Value A -1 if the query is out of range. This will reset the query counter to 0. are restored when the function returns. offset. such as browse() and global(). -1). offset = findline(db->i. or query(). */ showfield(int db. and erase the temporary query file. offset. number.query and db.activequery. length. row = row + 1.Functions Displays the string at the row and column position on the screen. wrap(db->i. addr(db->i. select(). 75). offset)). offset = findnline(db->i. See Also puts() Example /* Display one screen of the text field. Description Retrieves and makes the selected query number the current query. To clear all queries use query(db. char string[]). */ return(offset). the function will fill it with the search string used to create the query. row. 0. Queries manually changed in full screen functions. Return Value None. When it is supplied. i.

query and db. From then on it will return random numbers. Version 6. Return Value Returns the number of bytes read. Description Reads length bytes from the file referenced by handle into the variable buffer.activequery. See Also readln(). close() Concordance® Programming Language User Guide 112 .Functions queryString Summary text queryString(int db. A random number otherwise. for instance. query). rand(clock()). rand() should be called with a seed value to begin the random number sequence. Description Creates a random number sequence for any given seed number. int length). and the database information variables db. open(). Unlike the query() function. The sequence will always be the same for a particular seed number. Return Value Zero when called with a seed value.30 and later. char buffer[]. See Also query(). Description Retrieves the query logic string for the query. readc(). it does not make the selected query number the current query. which may be less than that requested if the end-of-file was encountered during the read.0 and later read Summary int read(int handle. You can read and write numeric values by passing their names and using the sizeof() function to determine their lengths. write(). writeln(). Return Value The text of the query or an empty string if either parameter is invalid or out of range. rand Summary int rand([int seed]). Version V7.

in read only mode. writec(). /* Skip past one line of input. or -1 if end of file encountered. ** or a line feed is found. EOF. } readc Summary int readc(int handle) Description Retrieves one byte from the file referenced by handle.buffer. */ EOF = -1. } Concordance® Programming Language User Guide 113 . oldfile. close(). LF.buffer. /* Now open the new file. Return Value Character read from file. } /* Copy the old file to the new file. close(oldfile). int i. create it."w+")) < 0) { close(oldfile). return(-1)."r")) < 0) return(-1). close(newfile). */ if ((oldfile = open(from.i).Functions Example copyfiles(text from. LF = 10. to) { char buffer[512]. readln() Example skip(int handle) { int c. See Also open(). /* Open the old file. */ if ((newfile = open(to. */ while((i = read(oldfile.512)) > 0) write(newfile. Handle must be a value returned by a call to open(). Read ** until the end-of-file is encountered. return(0). c = 0. read(). while((c <> LF) and (c <> EOF)) c = readc(handle). newfile.

write() recall Summary recall(int db). Description Reads one line of text from the file referenced by handle. document). the buffer will not contain any characters in this case. If the current query contains 3 documents. then the partial line is returned. not document 101. Return Value None. The document becomes the current document. The text is stored in the buffer without the terminating line feed. 100). A -1 indicates an attempt to read beyond the end of the file. The buffer is terminated with a zero. Description The current document is unmarked for deletion. then the 100th document in the data base is read. char buffer[]). Concordance® Programming Language User Guide 114 . The read continues until a line feed is encountered. but reads the document in the underlying data base. Description Reads the document from the data base. without counting carriage returns and line feeds. This function does not use the query list. both functions work on the current query. Using next() after this command will retrieve the next document in the query. Return Value A -1 if the document is out of range. The same goes for prev(). Return Value The number of characters read. See Also recno() readln Summary int readln(int handle. and you request readdoc(db. See Also writeln(). read(). If the buffer fills before the full line is read. carriage returns are ignored.Functions readdoc Summary int readdoc(int db.

Use docno() with the functions that manipulate queries. Concordance® Programming Language User Guide 115 . See Also readdoc(). recno() can be used with either readdoc() or the query functions. deleted() Example main() { int db.Functions See Also delete(). Return Value Zero if successful. The screen is automatically saved before entering this mode and restored after exiting. or a value less than or equal to zero if no document is ready. Both readdoc() and recno() ignore the current query and operate on the underlying data base. The document read by readdoc() will be flushed. next(). after a blank(). */ cycle(db) recall(db). A related function. last(). } } recno Summary int recno(int db). reindex() will call index() if the data base has not yet been indexed. closedb(db). first(). or if the data base is empty.e. Using docno() after readdoc() will cause the current document in the query set to be read. Description The data base is reindexed. Description Retrieves the physical record number of the current document. docno() reindex Summary int reindex(int database). etc. always returns information from the current query. i. i. This function does not use the current query. if ((db = opendb("recipes")) <> 0) { /* Recall all documents from deletion.e. Return Value The current document's physical record number. recno() can be used with readdoc(). docno().

text deletionTag. erase() rep Summary text rep(char ch | text string.80). 0. Description The file name is changed from oldname to newname. int length). int appendToSubscriber. Return Value A text variable. text synchMethod. char ch). a poorly formed DOS file name. TextHighlight_). Description Creates a new string with the character ch or text string repeated length number of times. */ puts(row. int copyDeletionMarks. See Also exist().Functions See Also index() rename Summary int rename(char oldname[]. Example DrawLine(int row. Concordance® Programming Language User Guide 116 . or a file that already exists with the new name. Errors are caused by a failure to find the file. { /* Draw a line across the screen. int appendToPublisher. Return Value A return value of -1 indicates an error. rep(ch. text subscriber. } replicate Summary int replicate( int publisher. int restoreDeletedDocs. newname[]).

This is a Boolean value. Concordance will attempt to open the subscriber database in shared. Parameter publisher subscriber synchMethod Type int text text Function Handle of publisher database. However. Use zero to prevent appending of new records to the subscriber database. regardless of which database has the most up-to-date information. Pass any nonzero value to allow appending of new records to the publisher from the subscriber. deletions. if the single user program already has the database open on the File menu. Full path and file name of subscriber database. Only selected fields are replicated. and tags are replicated. for instance they were created from the same databases using createReplica(). Use the db. "Soverwrites" for the subscriber to overwrite the publisher when differences are detected. This flag indicates that a record should be deleted during the next database pack. Description Synchronizes two database.order[i] value to select fields for replication. See the example for more information. The databases must be from the same replication set. replicate() can synchronize all fields or just selected fields. Pass any nonzero value to allow appending of new records to the subscriber from the publisher.Functions text collisionTag. This enables laptop clients to synchronize with the network database even if they are running a single user. record edits. It does not delete the record during appendToPublisher int appendToSubscriber int deletionTag text copyDeletionMarks int Concordance® Programming Language User Guide 117 . See the resolve() function for information on scripting collision resolution. Use any nonzero value to allow replication to copy deletion flags. "POverwrites" for the publisher to overwrite the subscriber when differences are detected. A collision occurs when the same field in the same record in both databases has been edited. the shared open will fail. Replication does not reindex or pack the databases. int copyAttachments). but will flag the records as being in collision. Any records in collision are tagged with the collisionTag. Concordance will not overwrite either edit. The example program takes this into account by closing any open database handles. Specify one of the three following options for synchronization: "Synchronize" for full bi-directional synchronize between databases. Use zero to prevent appending of new records to the publisher database. The optional tag is applied to records when the flag marking a record for deletion is copied from one database to another. Security. Use "" if you do not want to tag these records. multi-user mode.

TRUE. See also createReplica(). /* Don’t restore deletions. Example /* Fragment of code to synchronize two databases. Use "" if you don’t need to track collisions. */ int i. Use this tag after replication to resolve collisions via the resolve() function. The tag could be used later to ** resolve the collisions with resolve().Functions replication. "\\Dataflight\Nome\Alaska\Catalog. Any nonzero value indicates failure. FALSE = 0. */ TRUE. /* Replicate every field. */ FALSE.order[i] = i. /* Don’t append to subscriber. /* Don’t tag deletions.dcb". int first. if the databases are not from the same replication set. This restores the record if it exists in one database but has been deleted from the other. "Synchronize". */ for (i = 0. replicate( db. /* Append to publisher. */ "". restoreDeletedDocs int Use any nonzero value to restore deleted records. ** The user’s ID and date are used to flag any ** collisions. collisionTag text copyAttachments Return Value int A zero indicates success. i = i + 1) db. resolve() report Summary int report(int db.fields. */ netuser() + " " + dtoc(today()). Failure can occur if the subscriber database cannot be opened. Description Runs the named report for the document range. TRUE = 1. This tag is applied to records in each database when a collision occurs. The report is sent to the current default printer. This is a required step. */ FALSE. /* Replicate deletions. last). Note that it may be restored and still flagged for deletion. if the replication fields are not present or are not both system and key fields. Concordance® Programming Language User Guide 118 . i <= db. This optional parameter copies attachments if set to TRUE. text reportName.

will automatically save the edits. /* Print a report for every record this month */ if (db. Concordance® Programming Language User Guide 119 . reset Summary reset(int db). Note that a call to any full screen function. nonzero otherwise. prev(). The screen is automatically saved before entering this mode and restored after exiting. 1.. rc = report(db. Description Resets the current document. count(db)). printfs() . reloading the record from disk without saving any changes made by the programming language application.Functions Return Value Zero if the report ran.arp". will also save the edits.documents > 0) { szNow = str(month(today())) + "/??/" + str(year(today())) search(db. } } return(rc). "C:\concord5\taxs. "DATE = " + szNow). reportfs Summary reportfs(int db). reportfs() Version 6. if (count(db) > 0) { sort(db. Return Value None. etc.0 and later. Example MonthlyReport(int db) { char szNow[10]. next(). "dtoc(db->DATE. int rc. } See also print() . such as browse() or editfs(). 'Y')"). The data base functions. Return Value None. Description Invokes the Concordance full screen report writer.

*/ netuser() + " " + dtoc(today()). /* Databases are replicated. Return Value A zero signifies success. Now handle collisions. "Synchronize". This is a required step. Make them visible to us. It provides a powerful mechanism to script collision resolution based on edit dates. */ /* Replicate every field. */ Concordance® Programming Language User Guide 120 . /* Don’t tag deletions. FALSE = 0. TRUE = 1. */ char string[200]. i <= db. Description This function is passed handles to two databases. making the records identical and eliminating the collision. /* Append to publisher. It resolves a collision between records in these databases by copying all fields from one database to another database. /* Tag used to locate collisions.dcb". */ if ((dbS = opendb("\\Williamson\Case\Production. */ replicate( db. tagging any collisions. Since Concordance cannot determine which edit is the "correct" edit. /* Replicate the databases. /* Used to create a search string. user log-in name. They */ /* link the records in the databases. */ int i. /* Append to subscriber. i = i + 1) db. */ "". Collisions occur when the same field in the same record has been edited in both the subscriber and publisher databases. it flags these records as being in collision. */ /* First open the subscriber database. and other user criterion stored in the replication fields. Example /* Fragment of code to synchronize two databases ** and resolve any collisions between them.fields. */ TRUE.order[i] = i.Functions resolve Summary int resolve(int toDatabase. TRUE. "\\Williamson\case\Production. /* Create a unique tag for collisions */ szTag = netuser() + " " + dtoc(today()). /* Don’t restore deletions. */ TRUE. The resolve() function is used to automate replication.dcb")) >= 0) { /* We need to see the system fields used for */ /* replication. /* Replicate deletions. text szTag. fromDatabase). dbS. */ for (i = 1. */ FALSE.

} } /* Clear the temporary tags we used for collisions. then process. /* Hide the system fields. Description Places the screen image on the screen that was previously created by a call to the save() function. we’re done. For the example */ /* we will keep the NOTES field from the */ /* publisher database. we’re done */ closedb(dbS). if ((search(dbS. "System fields". replicate() restore Summary restore(row. "System fields". and use all other */ /* fields from the subscriber database. */ dbS->NOTES = db->NOTES. */ tag(db. "System fields". tag(dbS. -1. */ tagquery(db. set(dbS. */ string = ‘CREATIONID = "’+trim(db->CREATIONID) + chr(‘"’). The image is placed at the location whose upper left corner is described by the row and column coordinates. } See also createReplica(). resolve(db. column. string) == 0) and (count(dbS) > 0)) { /* We found the record. "Hide"). See Also Concordance® Programming Language User Guide 121 . /* Close the subscriber. "Show"). "Show"). dbS). /* Locate all records in the publisher database */ /* that were tagged for collision. szTag). */ cycle(db) { /* Find this record in the subscriber.Functions set(db. */ set(db. /* Loop through the tagged collision records. Return Value None. szTag). text screen). -1. szTag).

and line feeds. See Also chdir() .Functions save() rmdir Summary int rmdir(text directoryPath). character array. int decimals). Description Removes all trailing white space from the text variable. f = round(pi. Example main() { float f. Description Removes (deletes) the specified directory. } rtrim Summary text rtrim(text string). erase() round Summary float round(float number. tabs. or field. pi = 3. Return Value The rounded floating point number. directoryPath can be either an absolute path name or relative to the current working directory. The directory must not contain any files or subdirectories. Return Value rmdir returns zero if successful. -1 otherwise.15 */ . pi. /* f now contains 3. Concordance® Programming Language User Guide 122 .1459. carriage returns.. Return Value Returns a duplicate of the string. mkdir() . rename() . Description Rounds the fractional portion of a floating point number to the specified number of decimals.2).. getcwd() . White space consists of spaces. does not modify the original.

Description This function is used to execute external CPL programs. Quoted strings that are used as parameters should be assigned to a text or char array before being passed. See Also eval() Example LoadSpeller(int db) { char prompt[50].prompt)")) { prompt = "Enter correction: ". Functions and variables in the module will replace pre-existing functions and variables of the same name.CPL or .CPT file which contains the function. brow.cpl". function)."Correct(db. The called function can access and change any globally declared variable in the calling program.cpl".0 and later run Summary run(text program. See the example below. ok = run("spellchk. Global variables declared in the called module are only accessible while the module is loaded and running. if (ok = run("spellchk. */ prompt = "Look up word: ". Concordance® Programming Language User Guide 123 .CPL or .prompt)"). /* Load an external program to spell check. bcol). } save Summary text save(row. int ok."Check(db. It can also execute any function in its own file or in the calling function's file. It can be any Concordance value. Return Value The value returned by run() is the value returned by the function that is executed. Inclusion of the .CPT file name suffix is optional. trim() Version 6. col. } return(ok).Functions See Also ltrim() . The program parameter is the name of a .

The image is stored in text variable format. The window is scrolled up if the up parameter is 'U' or 'u'. rows. it is searched in the database and the results become the current query.'U'. up [. The window is described by the upper left corner row and column coordinates (tr and tc) and the bottom right corner row and column coordinates (br and bc). br.0. The error number corresponds to an error message in the reference manual. Bkcolor is an optional parameter and specifies the background color. bc. Return Value None. Return Value Zero if no error occurred. It is scrolled rows number of lines. tc. */ clsc(int color) { scroll(0. bkcolor]). Return Value A text value containing the image of the screen. See Also cls() Example /* Clear the screen in the passed color. Query error messages are not displayed. If the rows parameter is zero the entire window is cleared. Description Scrolls a window in the screen.79. but it is not a standard text variable. char string[]).24.0. and down if it is 'D' or 'd'. The search screen is not displayed. See Also restore() scroll Summary scroll(int tr. Description The string contains a search.Functions Description Returns an image of the screen window described by the upper left corner and lower right corner coordinates. or -1 if the user pressed [Esc] to cancel the search. } search Summary int search(int db. an error number if the search could not be completed due to query logic or file error. the new lines (at the top or bottom) appear empty and in the background color. Concordance® Programming Language User Guide 124 .color).

Return Value See search() See Also search(). char string[]).."Error"+str(rc)+"duringsearch. /* Return code from search(). else if (oldQueryNumber <> db. Concordance® Programming Language User Guide 125 . All programs should now use the search() function. This is required by the search engine. Description This function is only included for compatibility with releases prior to 5. select Summary int select(int db.Functions Programs should test both the return code and the query number to guarantee that a search was successful. char string[]). text option [. selectfs Summary int selectfs(int db. a fixed field search.query) processSuccessfulQuery(db).20.."). Return Value See search() See Also search() set Summary int | text set(int db.20. Description This function is only included for compatibility with releases prior to 5.query. /* Previous query number.int|text value]). is enclosed in quotes. otherwise it will interpret the search as XYX adj CO.'CUSTNO="XYZCO"andPAID="F"')) puts(10. */ oldQueryNumber = db. Example int rc. */ .30. if(rc=search(db. */ oldQueryNumber. /* Note that XYZ CO.

"Bell") ? "On":"Off")).79]). the set option is changed to the new value. szDir. Parameter szOp Meaning A string specifying the operation to perform.Functions Description This is a family of functions which set or retrieve various environmental options in Concordance."Punctuation" [. If it is an executable file. shellExecute() opens or prints it. int set(db.TRUE | FALSE]). and Empties. int set(db. puts(6." If this parameter is NULL. text set(db. In either case. If the optional parameters are passed. Description shellExecute() launches a program."Punctuation "+set(db. even if the szOp string is "print. int set(db. puts(3."Quote" [."Wildcard"))).. Example status(int db) { cls().'*']). puts(7.2.2."Punctuation")).2. this function opens it. or opens or prints a file or a document. szFile.2."Wildcard "+chr(set(0."Wildcard" [."]). the previous value of the set option is returned by set(). A string specifying the file to open.2."Margin")))." Create a NULL parameter by declaring NULL as a text variable."&-."Empties are "+(set(db."Quote"))). puts(4."Bell is "+(set(0."Margin" [. The data base handle is only required by Margin. int set(db. If it is a document file."Quote "+chr(set(0. Punctuation. Optional parameters are enclosed in brackets [."Empties" [. szFile Concordance® Programming Language User Guide 126 . puts(5. For all other set options the data base handle is a dummy parameter.2. int fsShowComd)."Margin "+str(set(db. "open" is the default value. int set(db.. depending on the value of the szOp parameter. If the parameters are not passed."Empties")?"On":"Off")). szParams.'"']). Do not assign a value to it.]. The file specified by the szFile parameter can be a document file or an executable file. This string can be "open" or "print. puts(2.TRUE | FALSE]). } shellExecute Summary int shellExecute(text szOp. getkey()."Bell" [. no change takes place.

A string specifying the default directory. Activates and displays a window. SW_RESTORE SW_SHOW SW_SHOWMAXIMIZED SW_SHOWMINIMIZED SW_SHOWMINNOACTIVE SW_SHOWNA SW_SHOWNOACTIVATE SW_SHOWNORMAL Returns The program’s instance or DDE server handle is returned. The window that is currently active remains active. Windows restores it to its original size and position (same as SW_RESTORE). This parameter can be on of the values from the table below. fsShowCmd Value SW_HIDE SW_MINIMIZE Meaning Hides the window and passes activation to another window. If the window is minimized or maximized. Activates a window and displays it as an icon. Minimizes the specified window and activates the top-level window in the system’s list. The window that is currently active remains active. Displays a window in its current state. Displays a window as an icon. If szFile specifies a document file.Functions szParams A string specifying parameters passed to the application when the szFile parameter specifies an executable file. Use one of the following parameters for the fsShowCmd. A return value less than or equal to 32 indicates an error. Activates and displays a window. Activates a window and displays it as a maximized window. Concordance® Programming Language User Guide 127 . Specifies whether the application window is to be shown when the application is opened. Windows restores it to its original size and position (same as SW_SHOWNORMAL). this parameter is NULL. szDir fsShowCmd The fsShowCmd controls the method used to display the application window. If the window is minimized or maximized. Error values are listed in the following table. The window that is currently active remains active. Activates a window and displays it in its current size and position. Displays a window in it most recent size and position.

Path was not found. Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only.Functions Return Value 0 Meaning System was out of memory. Attempt was made to dynamically link to a task.EXE image. or there was a sharing or network-protection error.0. Type of executable file was unknown. Attempt was made to load a compressed executable file. There was insufficient memory to start the application. The file must be decompressed before it can be loaded. Application was designed for a different operating system. There is no association for the specified file type or there is no association for the specified action within this file type. Dynamic-link library (DLL) file was invalid. executable file was corrupt. Application was designed for MS-DOS 4.62 and later. Attempt was made to load a real-mode application (developed for an earlier version of Windows). Concordance® Programming Language User Guide 128 . Executable file was invalid. Windows version was incorrect. Either it was not a Windows application or there was an internal error in the . 2 3 5 6 8 10 11 12 13 14 15 16 19 20 21 31 Version 6. or relocations were invalid File was not found. Library required separate data segments for each task. Application requires Microsoft Windows 32-bit extensions. One of the DLLs required to run this file was corrupt.

Functions See Also spawn(). mode @ sizeof Summary int sizeof(value). Sizeof should not be confused with len(). int TRow. Any field can be passed to show() for display. Use this value to determine the next screen line available for display. It will highlight all words located in the current query that appear in a paragraph field. it returns the declared number of elements in the array times the size of an individual element. If the last item in the current document is already highlighted on the screen. lastRow). Description Determines the size of the variable in bytes. BRow. The lastRow parameter is optional. The query list will be positioned on the next item in the list to be highlighted when show() returns. which returns the number of characters stored in a character array or text variable. TCol. The size of a subscripted array element is the size of the base type. it will contain the number of the last screen row used to display data when show() finishes. See Also edit(). but only paragraph fields will receive highlighting. Description This function displays the passed field in a window described by the row and column coordinates. offset. Return Value The offset of the last line displayed in the text window. then the hit list will be positioned on that item. Return Value Integer length of value in bytes. If the variable is an array. If provided. See Also len() Example main() { Concordance® Programming Language User Guide 129 . Show() will not cause the hit list to advance to the next document. Taking the size of a data base field is invalid. The text is not word wrapped before it is displayed as with edit() mode -1. BCol. system() show Summary show(db->field.

0)+str(sizeof(list[7]). all searches for the databases. takeShot can be any nonzero value to save the snapshot to the fileName parameter. A zero for takeShot causes the named snapshot to be restored. [int color[.43 and later sort Summary int sort( int db. } Output: 2 40 2 sleep Summary sleep(int winks). Description Pauses the program for as many thousandths of a second as the winks parameter specifies. and the current sort in effect.5. puts(0. or a zero to signify success when saving a snapshot.0)+str(sizeof(list). If the program is an OS/2 or Windows application. typically caused by a disk full or insufficient write/create rights on a network drive. a text variable. the current record.Functions short i.0). Description Saves or restores a full snapshot of the current state of Concordance. the sleep function returns control to the operating system for at least that amount of time. list[20]. Return Value A handle to the newly restored database if the snapshot is being restored. The query is sorted in ascending order unless the dc() function Concordance® Programming Language User Guide 130 . text fileName. which includes all concatenated databases."str(sizeof(i). The string parameter can be a character array. background]]]). snapshot Summary int snapshot(int db. column. or quoted text.0. [int row.5. See Also exec() . Description Sorts the current query according to the string parameter. the handle to the newly opened database is returned. int takeShot).5. char string[]. Return Value None. A nonzero value indicates failure when saving a database. keep() Version 5.

exe". in descending order ** by the publication date. . Return Value A -1 if the sort failed. The sort will stay in effect until the data base is closed. Sort() will display a percentage of progress if the optional row and column parameters are used. column 11. If the sort succeeds the current query is sorted. The . most likely due to a disk full condition or to the user pressing the [Esc] key. system() will handle external programs.com file extensions are optional. and internal commands such as dir and copy.4)+ str(month(db->date). */ if ((db = opendb("library")) >= 0) { puts(5. } return(0). sort(db. browse(db).Functions is used within the string. are also optional. or until the query is reloaded with the query() function. spawn() will use the current environment path to locate the program if it is not in the current directory. most recent ** publication first. } spawn Summary int spawn(text "program. until another query is executed. Concordance® Programming Language User Guide 131 .2. This differs from the system() command in that system() calls the operating system command interpreter to invoke the command. /* Sort the current query in ascending order ** by the author field.5. see example below. The color parameters. Description Starts the external program and returns any exit value or completion code returned by the program. closedb(db).2))". spawn() will not run . in the default ** color. The sort routine will ** display its percentage of progress on the ** screen at row 5."Sorting:).2)+ str(day(db->date).bat files."db->author+ dc(str(year(db->date).bat files.exe and . "parameters"). but it will not return completion codes.11). See Also dc() Example main() { int db. which affect the percentage display. not the physical documents in the database.

} Output: $0.decimals. See Also system() sqrt Summary float sqrt(float v). or '. and width specification. If there isn't enough room for the number. width = 5. or zero padding. dollar signs. [char format]]]). can be char or int or float.0 and later str Summary text str(int x[. i <= 10. See Also itoa(). decimals. i = i + 2) puts(i. Description Converts numeric value to character string. format.0. a Z zero fills leading blank spaces. format = '$'.width. Description Determines the square root of the value. the dollar sign format is the comma format with a dollar sign preceding the number. x. The number is formatted right justified within the specified width. trim() Example main() { int width. dollar signs.format)). for(i = 0. Format specification can be '$'. num(). 'Z'. decimal point. The return code from the executed program if it was run. i. decimals. Numeric value. and a blank space formats the number without comma. with optional commas.Functions Return Value -1 if the program could not be executed. Return Value The number as a character string.'.str(i. The comma places a comma every third significant digit. a blank space. Version 6. a series of asterisks are returned. decimals = 2. Return Value The square root as a floating-point value. width[.00 Concordance® Programming Language User Guide 132 .

Functions $2. If it is left off. beginning at from characters. From must be greater than or equal to 1. a = "Joe's Diner in the Park". text FileName). See Also createdb() substr Summary text substr(text string. The data base isn't created if a data base already exists with the same name.00 $4. Description Creates a new data base with the same structure as the currently opened data base. b.00 ***** /* No room to print $10. Description Makes a copy of the characters in the string. Return Value Zero if the new data base was successfully created. Width is optional. but it does not open it for use. b = substr(a. substr will return a copy of the entire string beginning at from. Return Value A copy of the characters in the string.00 $6. /* b is now "Diner in the Park" */ } Concordance® Programming Language User Guide 133 . The db parameter must be a handle to a currently opened data base.00 */ struc Summary int struc(int db.1)).00 $8. struc() creates the data base. width).match(a. int from. See Also addr() Example main() { text a. The FileName parameter is the name of the new data base created by this function. and continuing for width characters."Diner".

Functions

system
Summary int system(text command); Description Passes the command string to the operating system for execution. This can be used to execute operating system commands such as DIR, or COPY, or to run external programs. Return Value A 0 if successful, a nonzero value if not successful. Reasons for failure are insufficient memory or the system was not able to find the program in the command string for execution. Example /* Program fragment to display a document on the screen ** and show a graphics image when ALT-V is pressed. */ ViewDocument(int db, document) { int key; goto(db,document); /*Call subordinate function to display browse screen.*/ ShowDoc(db); while(key <> ESC) { switch(key = getkey()) { case ALTV: system("view "+db->graphic); case '+': if (next(db) > 0) ShowDoc(db); case '-': if (prev(db) > 0) ShowDoc(db); } } } See Also spawn()

table
Summary table(int db); Description Invokes Concordance full screen table view mode. Return value None. See Also browse()

Concordance® Programming Language User Guide

134

Functions

Version 5.32 and later

tag
Summary int tag(int db, ON|OFF|CLEAR [, text tagString]); Description Tags a document in the database whose handle is db according to the value of the second parameter: ON 1 Document is tagged.

OFF 0 Document is untagged. CLEAR -1 All documents in the database are untagged. Remember to clear all tagged queries before beginning a tagging cycle. Otherwise, documents previously tagged will be included in the current tagging operation. Document tags are stored in a file called database.trk, they are retained with the database and do not disappear if the database is closed and reopened. If the optional tagString parameter is passed, the supplied tag is applied to the document. Otherwise the default tag, "", is applied. Return Value Returns a zero if no error occurred. Returns a nonzero value if an error occurred while tagging the document. See Also istagged(), tagquery()

tagquery
Summary tagquery(int db[, text tagString]); Description Collects all tagged documents in the database whose handle is db into a single query. If the optional tagString is supplied, only documents tagged to the tagString are selected. The set of tagged documents becomes the current active query. Return Value None. Check the database information variable db.query to see if a tagged query was actually created. The function will create a tagged query with zero documents if no tagged documents were found. See Also tag(), istagged()

time
Summary time(int hours, minutes, seconds);

Concordance® Programming Language User Guide

135

Functions

Description Returns the current time in the passed parameters. The hours are in military format, 1 - 24 hours. Minutes and seconds are optional parameters. Return Value Returns the total seconds elapsed since midnight, (hours * 3600) + (minutes * 60) + seconds. The passed parameters are set to the current time when the function returns. See Also clock(), today() Example ShowTime() { int hours, minutes, seconds; text AMorPM; char string[10]; /* Display time on the screen. */ /* Get the time in a string. */ time(hours, minutes, seconds); AMorPM = " p.m."; if (hours < 12) AMorPM = " a.m."; if (hours > 12) hours = hours - 12; string = str(hours,2,0,'Z')+":"+str(minutes,2,0,'Z')+":"+str(seconds,2,0,'Z')); puts(0,0,string+AMorPM); }

today
Summary int today(); Description Gets today's date in internal numeric format. Return Value Integer representing today's date. See Also dtoc(), ctod(), clock(), time() Example WhatDayIsIt() { puts(0,0,"Today is "+dtoc(today())); }

Concordance® Programming Language User Guide

136

20. Description Unloads the current query to the file specified by the string file name. but Concordance will only unload fields with consecutive numbers from 1 to the last field number defined in the data base. line = " This is a fine mess ". Concordance allows the user to change the field order in several full screen modes including Print. character array. "|"+line+"|").Functions trim Summary text trim(text string). however they are required if row. 0. quote and newline are used to delimit the fields during the unload process. The string must be a valid file name. "|"+trim(line)+"|"). puts(0. You can assign any number from -128 to 127. You should always renumber the fields before any unload. column. 0. The documents are unloaded in delimited ASCII format as documented in the Concordance Reference Manual. or field. It is recommended that you leave these parameters off if transferring data between Concordance data bases. comma. newline. See the for-loop example below. [int row. Any inequality will indicate full disk or other disk error condition. 254. Description Removes all trailing and leading blanks from the text variable. rtrim() Example main() { text line. If they are left off Concordance will use its internal ASCII default values. Load. The optional parameters. color]]). puts(1. } Output: |This is a fine mess| | This is a fine mess | unload Summary int unload(int db. This should be checked against the number of documents that should have been unloaded. Return Value Returns a duplicate of the string. char string[]. and the order in which they are unloaded. quote. Return Value The number of documents unloaded. and Unload. Concordance® Programming Language User Guide 137 . The fields unloaded. [int comma. column. does not modify the original. See Also ltrim() . or that the user pressed [Esc] to cancel the unload. and 174 respectively. and color are passed. is set by assigning a number to the order entry of the field definition.

"). */ for(i = 1. The screen is automatically saved before entering this mode and restored after exiting. getkey(). Return Value None."Error reloading data. Never assume the */ /* order includes all fields..Functions See Also unloadfs()."). if (load(db. */ /* or set in Print. This step is necessary */ /* since the order previously set.0."Press any key to continue. loadfs() Example main() { int db.1. count.dat")."helpdesk. i = i + 1) db.dat") <> count) puts(0. else { zap(db). i. is retained */ /* until reset.0. index(db). else { erase("helpdesk. Description Invokes Concordance full screen unload mode. Concordance® Programming Language User Guide 138 . /* Permanately sort all records in the */ /* data base in ascending order.."Error unloading data base. if (unload(db.documents. count = db.").fields. i <= db. load(). /* Renumber all fields to unload in */ /* order. } } unloadfs Summary unloadfs(int db)."helpdesk.dat") <> count) puts(0. puts(0. */ if ((db = opendb("helpdesk")) <> -1) { sort(db. } } closedb(db)."db->DATE").order[i] = i.

Your program should unlock them as a courtesy to other network users if you do not intend to edit or modify them. Simply use it as you would any integer. Unlocking the record will force an immediate write to disk if it has been edited.) Return Value Zero indicates success. This has no effect in non-network versions of the program. See Also lockdb() unlockdoc Summary unlockdoc(int db). Do not pass it in quotes. Reading another document will automatically un lock a document. You do not need to declare it. locked() unmapDevice Summary int unmapDevice(text Device. See also mapDevice() Concordance® Programming Language User Guide 139 . Do not assign a value to it. A locked document cannot be changed and saved to file by other users. See Also lockdoc(). Set the force parameter to TRUE if you want to force the device to unmap regardless of the open file status. Description The data base whose handle is db is unlocked and released from exclusive use.Functions unlockdb Summary unlockdb(int db). The unmapping fails if the device has a file or lock open. int force). (TRUE is a predefined integer. Description Removes the network’s mapping of the disk drive or printer. Description Will unlock the current document in the network version of Concordance. Documents are automatically locked by Concordance when read into memory. Return Value None. Return Value None.

dtoc() Concordance® Programming Language User Guide 140 . ctod(). Return Value The name of the weekday. Version 7. See Also capitalize(). Description Converts the parameter string to all upper case. Return Value The release version number of Concordance Professional Edition. lower() ver Summary float ver([char string[]]). Concordance Runtime.Functions Example unmapDevice("F:". month(). See Also day(). it will contain a verbose description of the version. The parameter can be a date field or the result of the ctod() function. year().30 and later upper Summary text upper(text string). The parameter can be a text value or a character array. does not modify the original. weekday Summary text weekday(int d). or Concordance/386 Network. Return Value Returns a duplicate of the string in upper case letters. If the optional string parameter is provided. Description Version number of the Concordance Professional Edition. Description Computes the day of the week for the parameter date and converts it to a text string. FALSE).

character array.20) except that the second statement provides additional processing work for Concordance without any effect whatsoever. findpline() write Summary int write(int handle. findnline(). The text can be a data base field. or data base field. Return Value The parameter text passed to wrap() is returned. but the actual text parameter fully wrapped. See Also findline(). such as show() or write(). The length is determined by using the data base embedded punctuation.20) is equivalent to db->SUMMARY = wrap(db->SUMMARY. or 0 if the first letter of the word isn't alphanumeric. Concordance® Programming Language User Guide 141 . Handle must be a valid file handle returned by a call to open(). int width). wrap Summary text wrap(text string. The statement wrap(db->SUMMARY. Description Writes length number of bytes to the file referenced by handle from the buffer. Returning the original parameter also avoids insufficient memory errors when word wrapping large text fields. Return Value The number of bytes written to file. wrap() returns the parameter textas opposed to a copyso that it can be passed as a parameter to other functions. text variable. Return Value Length of the word. Description Word wraps the text within a column of width characters. or text variable. int length). text field). If this value does not equal length. wrap() does not return a duplicate of the text. text buffer.Functions wordlen Summary int wordlen(int db. Description Determines the length of the word in the character array. it indicates a disk full condition. A value of -1 indicates an error.

Return Value Returns the number of characters written to file. text szValue. Description The writePrivateProfileString() copies a string into the specified section of the specified initialization file. If the number of characters written is less than the length parameter. See Also write(). Parameter Function szSection The name of the section to which the string is copied. text szFile). close() writePrivateProfileString Summary int writePrivateProfileString( text szSection. int length). Return Value Returns a nonzero value if successful. and a -1 if an error is encountered. Description Writes the contents of the buffer to file and prints a carriage return-line feed after the text. the disk is probably full. open(). text szKey. char ch). or a -1 if an error was encountered. close() writec Summary int writec(int handle. Description The character is written to the file referenced by handle. The handle must have been returned by the open() function.Functions See Also writeln(). text buffer. read(). close() writeln Summary int writeln(int handle. read(). open(). See Also readc(). readln(). readln(). If the section does not exist. open(). The name of the section is not case sensitive. Concordance® Programming Language User Guide 142 . it is created.

KEY and . the entire section. See Also day(). This must be the fully qualified name. is deleted.ini file extension. If this parameter is NULL. Description Removes every document from the database. The date can be a value returned by ctod() or a date field.Functions szKey The name of the key to be associated string with a string. Use with caution.DCB files. The name of the initialization file. year Summary int year(int duedate). If this parameter is NULL. the key pointed to by the szKey parameter is deleted. Return Value The year in integer format. weekday() zap Summary int zap(int db). Description Extracts the year from the date. with the . . If the key does not exist in the specified section. but do not assign any value to it. This can happen if the database has read-only access. nonzero if zap() was not able to clear the database. this is a destructive command. Create a NULL value by declaring NULL as a text variable. szValue is written to the file. Concordance® Programming Language User Guide 143 . it is created. month(). Return Value Zero if zap() was successful. szValue szFile Return Value Nonzero if successful. including all entries within the section. See also getPrivateProfileString() Version Version 7.0 and later. or if it is in use by other network users. erases all associated database files except for the stopword file.