The following topic discusses the Concordance Programming Language (CPL) functions that begin with the letter S. For more information on CPL functions, see Functions, About the Advanced Programming Features, and About CPL Functions.
|
The function searchfs() has been removed from Concordance version 9.0 and later. |
Save
text save(row, col, brow, bcol); |
•Description - Returns an image of the screen window described by the upper left corner and lower right corner coordinates. The image is stored in text variable format, but it is not a standard text variable.
•Return Value - A text value containing the image of the screen.
•See Also - restore()
Scroll
scroll(int tr, tc, br, bc, rows, up [, bkcolor]); |
•Description - Scrolls a window in the screen. 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).
oThe window is scrolled up if the up parameter is 'U' or 'u', and down if it is 'D' or 'd'. It is scrolled rows number of lines, the new lines (at the top or bottom) appear empty and in the background color. If the rows parameter is zero the entire window is cleared. Bkcolor is an optional parameter and specifies the background color.
•Return Value - None.
•See Also - cls()
Example
/* Clear the screen in the passed color. */ clsc(int color) { scroll(0,0,24,79,0,'U',color); } |
Search
int search(int db; char string[]); |
•Description - The string contains a search, it is searched in the database and the results become the current query. The search screen is not displayed. Query error messages are not displayed.
•Return Value - Zero if no error occurred, an error number if the search could not be completed due to query logic or file error, or -1 if the user pressed [Esc] to cancel the search. The error number corresponds to an error message in the reference manual.
oPrograms should test both the return code and the query number to guarantee that a search was successful.
Example
int rc, /* Return code from search(). */ oldQueryNumber; /* Previous query number. */ ... /* Note that XYZ CO, a fixed field search, is enclosed in quotes. This is required by the search engine, otherwise it will interpret the search as XYX adj CO. */ oldQueryNumber = db.query; if(rc=search(db,'CUSTNO="XYZCO"andPAID="F"')) puts(10,30,"Error"+str(rc)+"duringsearch."); else if (oldQueryNumber <> db.query) processSuccessfulQuery(db); |
Select
int select(int db; char string[]); |
•Description - This function is only included for compatiblity with releases prior to 5.20. All programs should now use the search() function.
•Return Value - See search()
•See Also - search()
SelectFS
int selectfs(int db; char string[]); |
•Description - This function is only included for compatiblity with releases prior to 5.20.
•Return Value - See search()
•See Also - search()
Set
int | text set(int db; text option [,int|text value]); |
•Description - This is a family of functions which set or retrieve various environmental options in Concordance. Optional parameters are enclosed in brackets [...]. If the optional parameters are passed, the set option is changed to the new value. If the parameters are not passed, no change takes place. In either case, the previous value of the set option is returned by set().
oThe database handle is only required by Margin, Punctuation, and Empties. For all other set options the database handle is a dummy parameter.
text set(db,"Punctuation" [,"&-,"]); int set(db,"Margin" [,79]); int set(db,"Empties" [,TRUE | FALSE]); int set(db,"Wildcard" [,'*']); int set(db,"Quote" [,'"']); int set(db,"Bell" [,TRUE | FALSE]); |
Example
status(int db) { cls(); puts(2,2,"Margin "+str(set(db,"Margin"))); puts(3,2,"Punctuation "+set(db,"Punctuation")); puts(4,2,"Wildcard "+chr(set(0,"Wildcard"))); puts(5,2,"Quote "+chr(set(0,"Quote"))); puts(6,2,"Bell is "+(set(0,"Bell") ? "On":"Off")); puts(7,2,"Empties are "+(set(db,"Empties")?"On":"Off")); getkey(); } |
ShellExecute
int shellExecute(text szOp, szFile, szParams, szDir; int fsShowComd); |
•Description - shellExecute() launches a program, or opens or prints a file or a document. The file specified by the szFile parameter can be a document file or an executable file. If it is a document file, shellExecute() opens or prints it, depending on the value of the szOp parameter. If it is an executable file, this function opens it, even if the szOp string is "print."
oCreate a NULL parameter by declaring NULL as a text variable. Do not assign a value to it.
Parameter |
Meaning |
|---|---|
szOp |
A string specifying the operation to perform. This string can be "open" or "print." If this parameter is NULL, "open" is the default value. |
szFile |
A string specifying the file to open. |
szParams |
A string specifying parameters passed to the application when the szFile parameter specifies an executable file. If szFile specifies a document file, this parameter is NULL. |
szDir |
A string specifying the default directory. |
fsShowCmd |
Specifies whether the application window is to be shown when the application is opened. This parameter can be on of the values from the table below. |
oThe fsShowCmd controls the method used to display the application window. Use one of the following parameters for the fsShowCmd.
fsShowCmd Value |
Meaning |
|---|---|
SW_HIDE |
Hides the window and passes activation to another window. |
SW_MINIMIZE |
Minimizes the specified window and activates the top-level window in the system’s list. |
SW_RESTORE |
Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL). |
SW_SHOW |
Activates a window and displays it in its current size and position. |
SW_SHOWMAXIMIZED |
Activates a window and displays it as a maximized window. |
SW_SHOWMINIMIZED |
Activates a window and displays it as an icon. |
SW_SHOWMINNOACTIVE |
Displays a window as an icon. The window that is currently active remains active. |
SW_SHOWNA |
Displays a window in its current state. The window that is currently active remains active. |
SW_SHOWNOACTIVATE |
Displays a window in it most recent size and position. The window that is currently active remains active. |
SW_SHOWNORMAL |
Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_RESTORE). |
•Returns - The program’s instance or DDE server handle is returned. A return value less than or equal to 32 indicates an error. Error values are listed in the following table.
Return Value |
Meaning |
|---|---|
0 |
System was out of memory, executable file was corrupt, or relocations were invalid |
2 |
File was not found. |
3 |
Path was not found. |
5 |
Attempt was made to dynamically link to a task, or there was a sharing or network-protection error. |
6 |
Library required separate data segments for each task. |
8 |
There was insufficient memory to start the application. |
10 |
Windows version was incorrect. |
11 |
Executable file was invalid. Either it was not a Windows application or there was an internal error in the .EXE image. |
12 |
Application was designed for a different operating system. |
13 |
Application was designed for MS-DOS 4.0. |
14 |
Type of executable file was unknown. |
15 |
Attempt was made to load a real-mode application (developed for an earlier version of Windows). |
16 |
Attempt was made to load a second instance of an executable file containing multiple data segments that were not marked read-only. |
19 |
Attempt was made to load a compressed executable file. The file must be decompressed before it can be loaded. |
20 |
Dynamic-link library (DLL) file was invalid. One of the DLLs required to run this file was corrupt. |
21 |
Application requires Microsoft Windows 32-bit extensions. |
31 |
There is no association for the specified file type or there is no association for the specified action within this file type. |
•Version - Version 6.62 and later.
Show
show(db->field; int TRow, TCol, BRow, BCol, offset, lastRow); |
•Description - This function displays the passed field in a window described by the row and column coordinates. It will highlight all words located in the current query that appear in a paragraph field.
oThe query list will be positioned on the next item in the list to be highlighted when show() returns. If the last item in the current document is already highlighted on the screen, then the hit list will be positioned on that item. Show() will not cause the hit list to advance to the next document.
oAny field can be passed to show() for display, but only paragraph fields will receive highlighting. The text is not wordwrapped before it is displayed as with edit() mode -1.
oThe lastRow parameter is optional. If provided, it will contain the number of the last screen row used to display data when show() finishes. Use this value to determine the next screen line available for display.
•Return Value - The offset of the last line displayed in the text window.
•See Also - edit(), mode @
SizeOf
int sizeof(value); |
•Description - Determines the size of the variable in bytes. If the variable is an array, it returns the declared number of elements in the array times the size of an individual element. The size of a subscripted array element is the size of the base type.
oTaking the size of a database field is invalid.
oSizeof should not be confused with len(), which returns the number of characters stored in a character array or text variable.
•Return Value - Integer length of value in bytes.
•See Also - len()
Example
main() { short i, list[20]; puts(0,0,"str(sizeof(i),5,0)+str(sizeof(list),5,0)+str(sizeof(list[7]),5,0); } |
•Output - 2 40 2
Sleep
sleep(int winks); |
•Description - Pauses the program for as many thousandths of a second as the winks parameter specifies. If the program is an OS/2 or Windows application, the sleep function returns control to the operating system for at least that amount of time.
•Return Value - None
Snapshot
int snapshot(int db; text fileName; int takeShot); |
•Description - Saves or restores a full snapshot of the current state of Concordance, which includes all concatenated databases, all searches for the databases, the current record, and the current sort in effect.
otakeShot can be any nonzero value to save the snapshot to the fileName parameter. A zero for takeShot causes the named snapshot to be restored, the handle to the newly opened database is returned.
•Return Value - A handle to the newly restored database if the snapshot is being restored, or a zero to signify success when saving a snapshot. A nonzero value indicates failure when saving a database, typically caused by a disk full or insufficient write/create rights on a network drive.
•Version - Version 5.43 and later
Sort
int sort( int db; char string[]; [int row, column; [int color[, background]]]); |
•Description - Sorts the current query according to the string parameter. The string parameter can be a character array, a text variable, or quoted text. The query is sorted in ascending order unless the dc() function is used within the string, see example below. Sort() will display a percentage of progress if the optional row and column parameters are used. The color parameters, which affect the percentage display, are also optional.
•Return Value - A -1 if the sort failed, most likely due to a disk full condition or to the user pressing the [Esc] key. If the sort succeeds the current query is sorted, not the physical documents in the database. The sort will stay in effect until the database is closed, until another query is executed, or until the query is reloaded with the query() function.
•See Also - dc()
Example
main() { int db; /* Sort the current query in ascending order ** by the author field, in descending order ** by the publication date, most recent ** publication first. The sort routine will ** display its percentage of progress on the ** screen at row 5, column 11, in the default ** color. */ if ((db = opendb("library")) >= 0) { puts(5,2,"Sorting:); sort(db,"db->author+ dc(str(year(db->date),4)+ str(month(db->date),2)+ str(day(db->date),2))",5,11); browse(db); closedb(db); } return(0); } |
Spawn
int spawn(text "program.exe", "parameters"); |
•Description - Starts the external program and returns any exit value or completion code returned by the program. This differs from the system() command in that system() calls the operating system command interpreter to invoke the command. system() will handle external programs, .bat files, and internal commands such as dir and copy, but it will not return completion codes.
ospawn() will use the current environment path to locate the program if it is not in the current directory. The .exe and .com file extensions are optional. spawn() will not run .bat files.
•Return Value - The return code from the executed program if it was run. -1 if the program could not be executed.
•See Also - system()
SqRt
float sqrt(float v); |
•Description - Determines the square root of the value.
•Return Value - The square root as a floating-point value.
•Version - Version 6.0 and later
Str
text str(int x[, width[, decimals; [char format]]]); |
•Description - Converts numeric value to character string, with optional commas, dollar signs, decimal point, and width specification. Numeric value, x, can be char or int or float. Format specification can be '$', 'Z', a blank space, or ','. The comma places a comma every third significant digit, the dollar sign format is the comma format with a dollar sign preceding the number, a Z zero fills leading blank spaces, and a blank space formats the number without comma, dollar signs, or zero padding.
oThe number is formatted right justified within the specified width. If there isn't enough room for the number, a series of asterisks are returned.
•Return Value - The number as a character string.
•See Also - itoa(), num(), trim()
Example
main() { int width, decimals, i, format; width = 5; decimals = 2; format = '$'; for(i = 0; i <= 10; i = i + 2) puts(i,0,str(i,width,decimals,format)); } Output: $0.00 $2.00 $4.00 $6.00 $8.00 ***** /* No room to print $10.00 */ |
Struc
int struc(int db; text FileName); |
•Description - Creates a new database with the same structure as the currently opened database. The database isn't created if a database already exists with the same name.
oThe db parameter must be a handle to a currently opened database. The FileName parameter is the name of the new database created by this function. struc() creates the database, but it does not open it for use.
•Return Value - Zero if the new database was successfully created.
•See Also - createdb()
SubStr
text substr(text string; int from, width); |
•Description - Makes a copy of the characters in the string, beginning at from characters, and continuing for width characters. From must be greater than or equal to 1.
oWidth is optional. If it is left off, substr will return a copy of the entire string beginning at from.
•Return Value - A copy of the characters in the string.
•See Also - addr()
Example
main() { text a, b; a = "Joe's Diner in the Park"; b = substr(a,match(a,"Diner",1)); /* b is now "Diner in the Park" */ } |
System
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()