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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sign up to vote on this title
UsefulNot useful