A

<< Click to Display Table of Contents >>

Navigation:  Concordance Programming Language Reference > Functions >

A

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.

See Also - annotationCount(), annotationDelete(), annotationGoto(), annotationIsTagged(), annotationRetrieve(), annotationTag(), annotationUpdate()

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.

See Also - annotationAppend(), annotationDelete(), annotationGoto(), annotationIsTagged(), annotationRetrieve(), annotationTag(), annotationUpdate()

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.

See Also - annotationAppend(), annotationCount(), annotationGoto(), annotationIsTagged(), annotationRetrieve(), annotationTag(), annotationUpdate()

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.

See Also - annotationAppend(), annotationCount(), annotationDelete(), annotationIsTagged(), annotationRetrieve(), annotationTag(), annotationUpdate()

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.

See Also - annotationAppend(), annotationCount(), annotationDelete(), annotationGoto(), annotationRetrieve(), annotationTag(), annotationUpdate()

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.

See Also - annotationAppend(), annotationCount(), annotationDelete(), annotationGoto(), annotationIsTagged(), annotationTag(), annotationUpdate()

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.

See Also - annotationAppend(), annotationCount(), annotationDelete(), annotationGoto(), annotationIsTagged(), annotationRetrieve(), annotationUpdate()

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.

See Also - annotationAppend(), annotationCount(), annotationDelete(), annotationGoto(), annotationIsTagged(), annotationRetrieve(), annotationTag(),

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);

}