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

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

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

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

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

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

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

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

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

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

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

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

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 . /.Operators and Operands Variable MaxRow_ TextColor_ TextBackground_ TextHighlight_ MenuColor_ MenuBackground_ MenuHighlight_ MenuHighlightBackground_ HelpColor_ HelpHighlight_ QueryHighlight_ QueryHighlightBackground_ Description The bottom row on the screen. range 0 to MaxRow_ Color of text used for most displays Color used for background in Windows version Highlighted color used in most displays Color of menu background and unselected items Background color used in Windows version Color used to highlight selected menu item Background color for Windows version Used to display help screens Highlighted text on help screens Used in Browse mode to highlight search words Background color used in Windows version Operators and Operands Arithmetic Operators The arithmetic operators are +. the other arithmetic expressions are evaluated left to right. *. –. Operator – * / mod + – Description Unary minus. Unary minus is evaluated right to left. and mod.

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

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

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

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

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

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

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

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

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

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

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

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

Locates the previous entry in the 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. The dictionary is list of words or phrases stored in a file known as a btree. Locates a match for both the target and data value. Functions are available from the programming language to create. Returns the first entry in the file. and locate and retrieve it very quickly. Loads a list file from a data base field. Locates an entry in a list file. Locates an entry greater than the target. Concordance® Programming Language User Guide 19 . Returns the next entry in the file. Returns the count of entries. Opens an existing list file for use. such as a bibliographic report where there are multiple authors per record. Adds a new entry to the file in ascending order. Deletes an entry from a list file. Adds a new entry to the list. One use for list files is in subsorting a field to produce reports from fields with multiple entries. Displays a list file list in a menu. Locates an entry greater than or equal to the target. and search these list files. Locks the list file for exclusive use. Locates the last entry in the file. It can store textual data in alphabetical order. maintain. Locates an entry less than the target.Functions by Category Dictionary Btree List Management Concordance uses special dictionaries in searching and sorting.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

There is no association for the specified file type or there is no association for the specified action within this file type. Attempt was made to dynamically link to a task. Type of executable file was unknown.Functions Return Value 0 Meaning System was out of memory. Attempt was made to load a real-mode application (developed for an earlier version of Windows). or there was a sharing or network-protection error. executable file was corrupt. Path was not found. One of the DLLs required to run this 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 second instance of an executable file containing multiple data segments that were not marked read-only.EXE image. or relocations were invalid File was not found. 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. There was insufficient memory to start the application. Attempt was made to load a compressed executable file. Application was designed for MS-DOS 4. Dynamic-link library (DLL) file was invalid. Either it was not a Windows application or there was an internal error in the . Executable file was invalid. Windows version was incorrect.62 and later.0. Application was designed for a different operating system. Application requires Microsoft Windows 32-bit extensions.

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

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

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

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

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

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

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

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

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

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

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

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

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

Sign up to vote on this title
UsefulNot useful