Concordance Programming Language Reference > Functions

The following topic discusses the Concordance Programming Language (CPL) functions that begin with the letter E. For more information on CPL functions, see Functions, About the Advanced Programming Features, and About CPL Functions.

Edit

int edit(data-value; int TR, TC, BR, BC; text mode;

...

int element; text iMode; int SO, EO, color);

•Description - Edits a data-value, which can be a database field, char array, integer, floating point value, or date, in an edit window. The window is described by its top row, TR, and column, TC, and its bottom corner row, BR, and column, BC. The mode string tells the edit function how to edit the data. Mode attributes are described later. Multiple data values can be passed to the edit function in one call.

oThe last line in edit() uses additional variables to tell edit() which element to edit first, what initial mode to use, what offset into the data to start editing, and what color to use.

oelement is the data element to edit first. If multiple values are passed you can tell edit() to start editing with any selected value, instead of the first. Edit elements are numbered starting with one at the top. Setting element to a value greater than the total number of elements will cause edit() to use the last element. Upon return, element contains the current number of the element being edited.

oThe iMode parameter specifies the edit attribute to use for this first element the initial time it is edited. See the modes below for additional information.

oSO and EO are the Screen Offset and Edit Offset. These are used for full text paragraph fields. They specify the offset into a full text field to begin displaying data, and the offset into the field to place the cursor when edit() is first called. Upon return, they contain the current offsets of the user's cursor.

oThe last parameter, color, is the color used to edit all values passed to the edit() function.

oThe following mode string attributes are available:

Attribute	Description
A	Alpha only mode, numeric values are rejected.
U	Upper case conversion.
N	Numeric only mode, for text or char array variables.
N:w.d	Numeric data is edited in a field w characters wide, with d decimals.
Y	YMD mode for dates, can be a date field or integer value.
M	MDY mode for dates, can be a date field or integer value.
D	DMY mode for dates, can be a date field or integer value.
C	Cut and paste mode. This mode allows the user to move with the cursor control keys, mark text with [Alt-M], and copy it to the cut and paste buffer using the [Enter] key. Use the paste() function to access the marked text.
S	Scroll field left and right, no wordwrapping. Use for fixed fields and char arrays.
E	Return on [Enter] key, no hard carriage returns allowed in data. Useful with fixed fields and char arrays.
T	Always edit data starting from the top. If T and B are not specified, edit() assumes you wish to continue editing using the screen and edit offset parameters.
B	Edit data starting from the bottom. This mode is useful as an initial mode value overriding default value. If T and B are not specified, edit() assumes you wish to continue editing using the screen and edit offset parameters.
@	Display only this value, no editing allowed.
!	Return immediately when this field is entered, don't edit it. 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.
Button	Creates a button under Windows. Returns CR if selected.

•The following additional keys can be used while editing:

o[Alt-M] will begin marking text for cut and paste. Pressing [Alt-M] again will unmark the text.

o[Shift-Del] copies marked text to the cut and paste buffer. This requires [NumLock] to be off.

o[Shift-Ins] copies text from the buffer to the edit window. This requires [NumLock] to be off.

o[Del] deletes marked text and copies it to the paste buffer.

o[Ctrl-Y] deletes text from the cursor up to and including the end of the line. [Ctrl-Y] ignores marked text and does not save the deleted text in the cut and paste buffer.

•Return Value - Edit will automatically process all cursor control keys that move between edit elements, unless the user tries to cursor above the first element or below the last element. Edit returns the keystroke that caused termination. In the case of mode @, display mode, the returned value is always a 0.

oUpon returning, the parameter element will be set to the number of the data element currently being edited. The parameters SO, Screen Offset, and EO, Edit Offset, 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, respectively.

oThe value 16, a [Ctrl-P], is returned if the user types past the last character in a field.

oThe value -1 indicates an insufficient memory error.

•See Also - getline(), getnumber(), show()

Example

/* name: editPhone

** synopsis: Edits a phone number in 999/999-9999 format.

editPhone(int db)

{

char areacode[4],

prefix[4],

phone[5];

int key,

CR = 13, /* Value of [Enter] key. */

ESC = 27, /* Value of [Esc] key. */

element = 2, /* Element to edit first. */

SO = 1, /* Screen offset */

EO = 1; /* Edit offset */

/* Get the three elements of the phone number, areacode, prefix, and phone number. */

areacode = trim(substr(db->PHONE,1,3));

prefix = trim(substr(db->PHONE,5,3));

phone = trim(substr(db->PHONE,9));

/* Edit them until [Enter] or [Esc] is hit. */

while((key <> ESC) and (key <> CR))

key = edit("Phone:", 3, 1, 3, 7, "@",

areacode, 3, 8, 3, 10, "NET",

"/", 3, 11, 3, 11, "@",

"prefix, 3, 12, 3, 14, "NET",

"-", 3, 15, 3, 15, "@",

"phone, 3, 16, 3, 19, "NET",

db->NAME, 2, 8, 2, 60, "@",

element, "", SO, EO, TextColor_);

/* If the user pressed [Enter], save the number. */

if (key == CR)

db->PHONE = pad(areacode,'L',3)+"/"+pad(prefix,'L',3)+"-"+pad(phone,'L',4);

return(key);

}

Edited

int edited(int db);

•Description - Determines if the paragraph fields in the current document have been edited or appended to the database since the last time the database was reindexed. Documents located in a full text search that have been edited may not actually match the search conditions. Attempting to highlight the keywords on the screen, or to underline them on a printer, may result in the wrong words being highlighted.

•Return Value - A nonzero value if the document has been edited or modified since the last reindex.

EditFS

editfs(int db);

•Description - Invokes the Concordance full screen editor. The current document in the current query is edited. Users can change documents, but they cannot change queries from the editor. All fields in the database are edited. The screen is automatically saved before entering this mode. It is restored upon exiting.

•Return Value - None.

Erase

int erase(char string[]);

•Description - Erases the file. The file name can be a character array or a text variable.

•Return Value - If successful, erase returns a 0. Otherwise it returns a -1; erase() will not delete a read-only file or a directory.

Example

remove(char FileName[])

{

if ( erase(FileName) == -1)

puts(0,0,"Couldn't erase "+ FileName+".");

else

puts(0,0, FileName+" has been erased.");

}

Eval

eval(text string; int code, line);

•Description - Executes the Concordance expression in the string and returns the result as the value of eval(). This function allows end users to enter commands into strings and have them evaluated by the command processor.

oThis function is useful in allowing the user to enter a report format, field, or combination, and passing them to another function for report creation. Local variables declared in the function which executes eval() are accessible to the eval() function.

•Return Value - The value and type returned by eval() is the result of the string that is evaluated. For instance, if the string contains "2+2" eval() will return an integer. However if the string contains "weekday(today())" eval() returns the day of the week as a character string. Enclosing the eval() function within the str() function guarantees that the result is always of type text.

oThe second parameter, code, will contain an error code if the expression could not be evaluated. Otherwise it will contain zero. The error code corresponds to one of the numbered error messages in this manual.

oThe third parameter, line, is optional. It returns the line number that produced the error. This is useful when using eval() within a run() function to determine the error code and line number which produced the error. Using eval() to execute a run() also keeps your main program from crashing if the external program does not exist or has an error.

•See Also - run()

Example

/* Read a command from the user and execute it.

** Display an error code if an error code is

** returned. Scroll each line up the screen

** after each command.

main()

{

int code, key, db;

int CR, ESC;

char string[81];

db = opendb("c:\concord\database\research");

CR = 13;

ESC = 27;

while(key <> ESC)

{

key = 0;

string[0] = 0;

/* Get the command from the user. */

while((key <> CR) and (key <> ESC))

key = getline(MaxRow_,0,81,string);

/* 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

int exec(int db; text filename);

•Description - Executes the saved query file. Unlike the Execute option on the Concordance Search menu, exec() does not display the searches as they are executed.

oConcordance 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

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:

o 1 file exists

o 2 write permission is granted

o 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

exit()

•Description - Stops execution of the CPL program and of Concordance. Quits Concordance and returns to the operating system. Any open databases are closed automatically.

•Return Value - No return value, this function does not return to the caller.