Concordance Programming Language Reference > Functions

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

Accession

int accession(int db);

•Description - Returns the document's accession number. This function only works on version 6.0 or later databases. Previous version databases do not support accession numbers.

•Return Value - The document's accession number. Zero if the database version does not support accession numbers, or if the record has been blank()'ed but not yet append()'ed.

Example

/* See if we have a V6.x database opened */

if (accession(db) > 0)

/* It is V6.0 or later. */

else

/* It isn't V6.0 or later */

•Version - Version 6.0 and later

AddR

text addr(text string; int offset);

•Description - Converts a text variable offset into an address that can be used by any of the Concordance functions. The offset begins with one, the first character in the field. This offset also applies to char arrays, even though they are subscripted starting with zero. addr() is faster than passing a copy of the text with the substr() function, and it will not use additional memory.

•Return Value - Character index in internal format. Values returned by this function are treated as quoted strings for all practical purposes, i.e., they can only appear on the right side of an assignment.

•See Also - substr()

Example

printField(int db, i, file)

{/* Print every line in the field to file. */

int offset, length;

wrap(db->i, 40);

offset = findline(db->i,1,length);

while(offset > 0) {

writeln(file, addr(db->i, offset), length);

offset = findnline(db->i, offset, length);

}

AnnotationAppend

int annotationAppend( db->FIELD;

int offset, length;

text szNote;

text szAttachment;

int attachmentType;

int attachmentAction);

•Description - Appends a new note to the current record in the field identified by db->FIELD. The note is attached offset bytes from the beginning of the field, for length number of bytes. The remaining parameters are detailed in the table below.

Parameter	Description
szNote	The textual contents of the note.
szAttachment	The attachment, if any. This is the name of a file or web address that is launched.
attachmentType	Pass NOTEATTACHCLIPBOARD to have the attachment placed on the clipboard. Use NOTEATTACHEXTERNAL to have Concordance launch the application. NOTEATTACHNOTHING takes no action, and NOTEATTACHVIEWER sends the attachment to the current viewer.
attachmentAction	Pass TRUE to autolaunch the attachment

•Return Value - Returns zero if successful.

•Version - Concordance version 7.0 and later.

AnnotationCount

int annotationCount(int db);

•Description - Determines the number of annotations attached to the current record.

•Return Value - Returns a count of the annotations on the current record.

•Version - Concordance version 7.0 and later.

AnnotationDelete

int annotationDelete(int db);

•Description - Deletes the current annotation. The note is marked for deletion and the first character of the NOTEPARENT field is set to a space. This immediately disassociates the note from the parent record, however it is not physically removed from the database until the database is packed. Packing the parent database automatically packs the notes database.

oWhen you delete a note with this function, it is immediately removed from the document. Your functions should reinitialize with annotationCount() and annotationGoto() to ensure that you are using the correct annotation.

•Return Value - Returns zero on success.

•Version - Concordance version 7.0 and later.

AnnotationGoto

int annotationGoto(int db, recordNumber);

•Description - Reads the requested annotation into memory.

•Return Value - Returns zero if successful.

•Version - Concordance version 7.0 and later.

AnnotationLSTagged

int annotationIsTagged(int db; text tagName);

•Description - Determines if the current annotation is tagged with the parameter tagName.

•Return Value - Nonzero if the annotation contains the tag.

•Version - Concordance version 7.0 and later.

AnnotationRetrieve

text annotationRetrieve(int db; text "NOTETEXT");

•Description - Retrieves the contents of the named field from the annotation. See annotationUpdate() for data formatting.

•Return Value - All values are returned as text.

•Version - Concordance version 7.0 and later.

AnnotationTag

int annotationTag(int db; int TRUE|FALSE; [text tagName]);

•Description - Tags an annotation, creating an issue, in the current note for the database whose handle is db. The tag is either applied or cleared according to the value of the second parameter:

TRUE Document is tagged.

FALSE Document is untagged.

oIf the optional tagName parameter is not passed, the operation is performed on the "default" tagged set. Passing a tagName will perform the tag or untag operation only for the specific tag.

•Return Value - Zero indicates success.

•Version - Concordance version 7.0 and later.

AnnotationUpdate

int annotationUpdate(int db; text FIELD, text DATA);

•Description - Copies data to an annotation record field. All data must be passed as text. See below for examples. The FIELD parameter should be on of the fields in the annotation record.

Field	Description
NOTEPARENT	Unique identification assigned to the parent record. Do not modify this entry.
NOTEOWNER	The user logon of the person who created the note.
NOTETEXT	The text of the note.
NOTEATTACHED	An external file attached to the note. This is the file that is launched by a hyperlink.
ATTACHTYPE	The type of attachment can be "External", "Viewer", or "Clipboard", but this list may be expanded to support other types in the future. All three types take the contents of the NOTEATTACHED field as their parameter. A fourth value, "", is used to indicate that there is no attachment type.
AUTOATTACH	Either a "Y" or a "N". A "Y" indicates that the hyperlink is automatically launched when the user clicks on the link.
LINKFIELD	The field in the parent database that contains this note.
LINKOFFSET	The number of bytes from the beginning of the field where the note is attached. This is a zero based rich text offset; i.e., carriage returns are not counted.
LINKLENGTH	The length of the text at LINKOFFSET that contains the annotation. This is a rich text length. Carriage returns are not counted.
REPLICATION	The replication field that tracks edits.

oAll values must be passed as text, including dates and numbers. The function will make the appropriate conversion to store them in the database.

oDates must be passed in YYYYMMDD format, no punctuation, no spaces, fully padded and zero filled to eight characters.

•Return Value - Returns the number of bytes copied.

•Version - Concordance version 7.0 and later.

Append

int append(int handle);

•Description - Appends a document to the end of the database. This document becomes the current document. Use append() with blank() to create and add a record to the end of the database. Append() used without blank() will duplicate the current record.

The Network Edition of Concordance will automatically lock the end of the file while it adds the document to the database. The document is locked when the append finishes.

•Return Value - A -1 if unsuccessful.

•See Also - blank()

ASC

int asc(text info);

•Description - Converts a character to the integer ASCII code that represents it. In the case of text fields, text variables, and unsubscripted character arrays, asc() returns the character code of the first character.

oThis function allows you to directly compare individual characters with numeric values and character constants. Integer comparisons can run faster than string comparisons.

•Return Value - ASCII code that represents the character. The ASCII code is in the range 0 to 255. asc() will not return negative numbers.

•See Also - chr()

Example

DoSomething(int db)

{

int code;

if (asc(upper(db->sex)) == 'M')

code = DoThis(db);

else

code = DoThat(db);

return(code);

}