|
<< Click to Display Table of Contents >> Navigation: Concordance Programming Language Reference > Functions > G |
The following topic discusses the Concordance Programming Language (CPL) functions that begin with the letter G. For more information on CPL functions, see Functions, About the Advanced Programming Features, and About CPL Functions.
text getarg(int argNumber); |
•Description - Retrieves the command line argument passed to Concordance at startup. Concordance will ignore any arguments beginning with @, allowing a CPL program to retrieve them for exclusive use. Note that this function will also retrieve all command line arguments, not just those beginning with @.
•Return Value - A text string containing the argument. An empty string indicates the end of arguments.
•See Also - getenv() , putenv()
Example
main() { text pszArgs, pszCurrentArg; int i;
/* 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;
/* Increment to the next arg */ i = i + 1; }
/* Display the args */ if (pszArgs == "") messageBox("No args found on the command line.", "getargs", MB_OK); else messageBox(pszArgs, "getargs", MB_OK); } |
•Version - Version 5.32 and later
text getcwd(); |
•Description - Determines the full file path of the current working directory.
•Return Value - A text string containing the current working drive and directory.
•See Also - chdir(), diskspace()
Example
main() { chdir("C:\DATA"); puts(10,40,"The current directory is "+getcwd()); return(getkey()); } |
int getenv(text name); |
•Description - The getenv() function searches the environment list for an entry matching name. The search is not case-sensitive.
oEntries are added to the environment list with the DOS SET command, or with the CPL putenv() command. You can view the current environmental settings by typing SET from the DOS command prompt.
•Return Value - A text value containing the string assigned to the environment variable specified by name. The string is empty if there is no entry for name.
•See Also - getarg(); putenv()
Example
main() { text tempDir; tempDir = getenv("TEMP"); if(tempDir == "") puts( 10, 40, "No temporary directory exists."); else puts( 10, 40, "The temporary directory is "+tempDir); return(getkey()); } |
int getfile(char prompt[], fileMask[], fileName[]); |
•Description - A file selection window is displayed that shows the names of files that match the file mask. The mask can contain any characters valid in a file name, including wildcard characters. The prompt string is displayed as the title of the file selection window. If the user selects a file, the file's name is returned in the filename[] array.
•Return Value - getfile() returns a carriage return and a file name if the user selects a file. It returns an ASCII escape character, value 27, if the user presses escape to quit file selection without making a selection.
Example
OpenADataBase() { int db = -1, CR = 13; char string[60];
if (getfile("Database","*.DCB",string) == CR) db = opendb(string); return(db); } |
int getkey(); |
•Description - Read a key from the keyboard. This function will not return until a key is ready.
•Return Value - Key pressed, there is no error value.
•See Also - keypress()
Example
/* Prompt the user for the input code. */ input() { int value; value = 0; puts(5,10,"Enter code:"); cursor(5,22); while(value == 0) switch(getkey()) { case 'A': case 'a': value = 1; break; case 'S': case 's': value = 2; break; case 27: value = -1; /* [Esc] */ break; default: beep(45,100); break; } return(value); } |
int getline( int row, column, width; char string[]; [int color[,background]]); |
•Description - Retrieves a line of input text from the user. The maximum number of characters it will retrieve is equal to width - 1, since all character strings must be terminated by a zero. Color and background color are optional parameters. The background color only has meaning under Windows.
•Return Value - The keystroke that caused the function to terminate. Any key that it cannot process itself will cause it to return. It will handle END, HOME, Ctrl-Y (Delete to end of line), LEFT, and RIGHT. All other keys cause it to return. 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.
oThe value 16, a Ctrl-P, is returned if the user types past the last character in the field.
•See Also - edit(), getnumber()
Example
/* Get a line of input from the user, return */ /* the input and the exiting key stroke. */ huh(char txt[]) { int CR, ESC, key; key = 0; txt[0] = 0; CR = 13; ESC = 27; puts(15, 20, "Huh?"); while((key <> CR) and (key <> ESC)) key = getline(15, 25, sizeof(txt), txt); return(key); } |
int getnumber( int row, col; float number, min, max; int width, places, [color[,background]]); |
•Description - Prompts the user for a number at the row and column coordinates on the screen. The number will be between the min and max values. It will be no more than width characters wide, and will contain only places number of decimal places. The number, min, and max parameters can be any numeric value type, not just float.
oThe color and background color parameters are optional. TextColor_ will be used if the color parameters are left off.
•Return Value - The key that caused the function to return. The number parameter will contain the user's entry when the function returns. If the user presses the [Esc] key, number will contain the original value when getnumber() was called.
oThe value 16, a Ctrl-P, is returned if the user types past the last character in the field.
•See Also - getline()
Example
/* Get the number of lines per page to print. */ GetLinesPerPage(int lpp) { int CR, ESC, key; CR = 13; ESC = 27; puts(15, 1, "Lines per page:"); while((key <> CR) and (key <> ESC)) key = getnumber(15, 17, lpp, 0, 255, 5, 0); return(lpp); } |
int getPrivateProfileString( text szSection; text szKey; text szDefault; char szDestination[]; int size; text szFile); |
•Description - The getPrivateProfileString() function returns a string from the specified section in an initialization file.
Parameter |
Function |
|---|---|
szSection |
The name of the section containing the key name. If this parameter is NULL, the function copies all section names in the file to the supplied buffer. |
szKey |
The name of the key whose associated string is to be retrieved. If this parameter is NULL, all key names in the section specified by the szSection parameter are copied to the return buffer. |
szDefault |
If the szKey entry cannot be found in the initialization file, then the default string is returned. This parameter cannot be NULL. |
szDestination |
The data is returned in this array of char. It must be large enough to hold the data. |
size |
The length of szDestination in byes, for instance, use sizeof(szDestination). |
szFile |
The fully qualified name of the .ini file. If this parameter does not contain a full path, the system searches for the file in the Windows directory. |
oAvoid specifying a default string with trailing blank characters. The function can insert a null character in the returned text to strip any trailing blanks, depending on the operating system used.
oYou can create a NULL parameter by declaring NULL as a text variable and not assigning any value to it.
•Return Value - The return value is the number of characters copied to the buffer, not including the terminating null character.
oIf neither szSection nor szKey is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to size minus one.
oIf either szSection or szKey is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to size minus two.
•See Also - writePrivateProfileString()
•Version - Version 7.0 and later.
text gettags(int db; text szDelimiter); |
•Description - Retrieves all tags applied to the current document. Each tag is separated by the szDelimiter parameter.
•Return Value - A text string containing the document’s tags. An empty string if the document is not tagged.
•See Also - istagged()
Example
/* Locate tags. Delimit with semi-colon & newline. */ text szResult; szResult = gettags(db, ";" + newline()); |
•Version - Version 8.0 and later.
text getuuid(int db); |
•Description - Retrieves the document’s unique universal identifier. This is a unique serial number assigned to each record in a Concordance database. Unlike accession numbers, the UUID is unique across databases.
•Return Value - A text string containing the document’s UUID. Only V7.0 and later databases contain UUIDs. Records in earlier databases will return empty strings.
•See Also - accession(), gotouuid()
•Version - Version 7.30 and later.
global(int db); |
•Description - Invokes Concordance Global Edit mode. See the Concordance manual for a description of Global Editing. The screen is automatically saved before entering this mode and restored after exiting.
•Return Value - None.
int goto(int db, document, field, offset); |
•Description - Reads the specified document in the current query set. On return, the document, field, and offset parameters, if they are passed, will contain the relative document number, field number and word offset. The offset indicates the offset of the retrieved word from the beginning of the field. Fixed field searches will return offset values of zero.
oThe hit list is positioned on the first hit for the document. Additional calls to nexthit() will retrieve information about the other items in the list.
•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.
oThe document, field, and offset parameters will contain information about the first word in the document.
•See Also - recno(), docno(), first(), last(), next(), prev(), readdoc()
int gotoaccession(int db, accessionNumber); |
•Description - Locates and reads the document that matches the accession number. Accession numbers are returned by the accession() function. They are used by Concordance internally in place of physical record numbers for record tagging and full text searching in V6.0 and later databases.
•Return Value - Returns zero if successful.
•See Also - accession(), goto(), gotophysical(), gotouuid(), recno(), docno(), readdoc()
•Version - Version 6.0 and later.
int gotophysical(int db, document, field, offset); |
•Description - Locates the specified document in the current query set. The document number is the physical document number in the underlying database, not the relative document number in the current query.
oOn return, the document, field, and offset parameters, if they are passed, will contain the relative document number, field number and word offset. The offset indicates the offset of the retrieved word from the beginning of the field. Fixed field searches will return offset values of zero.
oThe hit list is positioned on the first hit for the document. Additional calls to nexthit() will retrieve information about the other items in the hit list. Only the database handle and document number parameters are required.
•Return Value - Returns the physical document number if successful. Returns a value less than or equal to zero if the physical document can't be located in the current query. In this case, the last document in the list becomes the current document.
oThe document, field, and offset parameters will contain information about the first hit word in the document if it was located successfully.
oThis function should not be used with concatenated databases as more than one database can have the same physical document number.
•See Also - goto()
int gotouuid(int db, text szUUID); |
•Description - Locates and reads the document that matches the unique universal identifier text. UUIDs are returned by the getuuid() function for any V7.0 or later database. They are used by Concordance internally in place of physical record numbers to link an annotation to a record. Use the NOTEPARENT field in a database-notes database to obtain the parent record’s UUID. Then use the UUID with gotouuid() to retrieve the parent record. The note is attached to this record.
•Return Value - Returns zero if successful.
•See Also - getuuid(), gotoaccession()
•Version - Version 7.30 and later.