Concordance® Programming Language User Guide

Copyright

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

Additional Resources
For additional help and support, please contact:

▪ ▪ ▪

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

151208CPLUG10.00

Concordance® Programming Language User Guide

i

Contents

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

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

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

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

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

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

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

ii

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sign up to vote on this title
UsefulNot useful