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

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

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

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

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

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

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

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

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

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

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

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

Operators and Operands Variable MaxRow_ TextColor_ TextBackground_ TextHighlight_ MenuColor_ MenuBackground_ MenuHighlight_ MenuHighlightBackground_ HelpColor_ HelpHighlight_ QueryHighlight_ QueryHighlightBackground_ Description The bottom row on the screen. negative numbers Multiplication Division The remainder of the first operand divided by the second Addition Subtraction Concordance® Programming Language User Guide 6 . –. Operator – * / mod + – Description Unary minus. *. and mod. /. Unary minus is evaluated right to left. 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 +. the other arithmetic expressions are evaluated left to right. Standard arithmetic precedence applies: division and multiplication are evaluated before addition and subtraction.

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

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

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

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

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

or for to create a single block of statements that are executed if the test conditions are satisfied. false values return zero. Compound statements are terminated by the }. Individual statements can be continued over several lines before being terminated with a the semi-colon. Concordance® Programming Language User Guide 12 . { and } braces can be used after an if-else. a semi-colon does not follow the }. Several types of conditional execution and repetitive execution statements are available. All simple CPL statements are terminated by a semi-colon. while. Begin and End Syntax { statement } The { and } braces are used to create compound statements. 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. The result of all comparisons is integer. True values are nonzero.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. Individual statements within the compound statement must be terminated by semicolons. Compound statements are treated as a single statement. curly end-brace.

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

The statement evaluates the test condition and executes the first statement if it is true. the else statement is executed. i > 0.1). else db->BONUS = db->COMMISSION * 0. if i is less than j. If the test condition is false. statement. Example if (i < j) i = j.. for(i = goto(db. i = next(db)) if (db->COMMISSION >= 100000) db->BONUS = db->COMMISSION * 0. break. The for loop used in this example produces the same results as the example used in the cycle statement on the previous page. 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.10.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. i will be set equal to j. else { i = i . break.25. else statements are optional. } In this example. Switch Statement Syntax switch(expression) { case expression: case expression: case expression: /* . If i is not less than j the else clause is executed which will subtract one from i and add one to j.. break. } Concordance® Programming Language User Guide statement.1. j = j + 1. 14 . */ default: statement. break.

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

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

Loads a delimited ASCII file. Saves and restores a complete Concordance environment. Replicates changes between databases. Invokes Concordance full screen load option. Invokes Concordance full screen overlay module.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. printing a document range. Removes documents marked for deletion. Saves the current query session to file. Indexes a data base. Locks database for exclusive use. Concordance® Programming Language User Guide 17 . Full screen data base modify. Reindexes edited and appended documents. Runs a saved report. Full screen Documents/Import menu option. Opens a data base for use. Prints data base records using a print format file. Searches a data base. Changes the default search operator. Invokes Concordance full screen print mode. Resolves collisions between replicated databases. Invokes Concordance full screen report writer. Loads a text file into the selected field. Invokes Concordance full screen global editing.

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

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

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

max min not rand round sqrt Returns the greater of two values Returns the lesser of two values Inverts the number. Reads a line of text from file. Several operate on the underlying data base. Most of them operate on the list of documents in the current query. Unmaps a network drive or printer. Write a line of text to file. Renames a file. Retrieves a character from 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. Writes a character to file. Opens a file for use. Concordance® Programming Language User Guide 21 .Functions by Category mapDevice mkdir open read readc readln rename rmdir unmapDevice write writec writeln Maps a network drive or printer. Reads data from a file. Remove a directory. Math Math functions manipulate numeric data. Writes data to file. Make a new directory. providing functions for comparison and change.

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

Tags a document. Retrieves the previous document in the current query. Returns record's data. Converts tagged documents into a query. Screen Control Functions are provided to maintain control over the program's presentation on the screen. Retrieves the query string. Releases a locked document. Sorts the list of documents in the current query. and the search logic.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. Changes data base environmental variables. control the cursor. Prevents other users from editing the document. Retrieves information on the next hit in the query. Loads the requested query. Determines if the document is locked. Returns data base document to prior state. Undeletes a document. Retrieves information on the previous hit in the query. Retrieves the last document in the current query. Using them your program can save portions of the screen. Retrieves the requested document. Retrieves the next document in the current query. box Draws a box on the screen. with search hits marked. Concordance® Programming Language User Guide 23 . Returns the document's record number. regardless of query. and display status information.

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

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

Determines if the character is alphabetic. Locates a string within another string. Determines if the character is upper case. centered. Duplicates the text in lower case. left or right justified. Determines if the character is a space character. Determines if the field exists in the data base. Determines if the character is lower case. Word wraps text data. Replicates a character into a string. Retrieves text from the cut and paste buffer. Concordance® Programming Language User Guide 26 . Removes leading and trailing spaces. Returns a carriage return and line feed string. Pads a string with spaces. Calculates the length of the text. Returns a partial string from a string. Removes trailing white space from a string. Determines if the character is a numeric. Removes leading white space from a 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. Locates a character within a string. Duplicates the text in upper case. Determines if the character is alphanumeric. Length of the word.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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