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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Scrolls the screen up or down. Retrieves the row number of the cursor. Evaluates a Concordance expression. Used in descending order sorts. Puts a string on 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 the name of the current function. Saves a portion of the screen. Clears the screen. beep dc debug eval exit func getarg Makes a beep on the speaker. System System commands provide access to external programs. and Concordance language features not available elsewhere. Restores a saved portion of the screen. Hides the cursor. Concordance® Programming Language User Guide 24 . returns to the operating system. Displays a standard Windows message box. Displays the cursor. Displays and highlights search words in a full text field. Turns debugging on/off. Puts a string or substring on the screen. operating system commands. Retrieves Concordance's command line arguments. Displays a menu. Ends the program. Positions the cursor on the screen.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Functions

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

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

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

Concordance® Programming Language User Guide

65

Functions

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

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

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

Concordance® Programming Language User Guide

66

Functions

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

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

67

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sign up to vote on this title
UsefulNot useful