The following topic discusses the Concordance Programming Language (CPL) functions that begin with the letter M. For more information on CPL functions, see Functions, About the Advanced Programming Features, and About CPL Functions.
MapDevice
int mapDevice(text localName, remoteName, user, password); |
•Description - Maps a network printer or disk drive. If user and password are NULL parameters then mapDevice() will use the currently logged user. If that is unsuccessful then the system may prompt the user for a password. Create a NULL parameter by declaring a text variable and not assigning a value to it. See the example below.
olocalName is the local device name such as "lpt1" or "f:" that you will use to access the device. remoteName is the network device name, such as "\\MyServer\sys".
•Return Value - Zero indicates success.
•See Also - unmapDevice()
•Version - Version 7.30 and later
Example
main() { text NULL; mapDevice("T:", "\\MyServer\sys", NULL, NULL); } |
MarkHits
text markhits(text field, beginMark, endMark); |
•Description - Retrieves the database field, marking hits with the beginMark and endMark text sequence. This is used primarily for adding word processing bold-on and bold-off sequences to search terms located in a query. This would include situations where Concordance is being used with an Internet Server to return data in Hypertext Markup Language (HTML) for Internet Web Browsers.
oThe function should be called with a database field:
text markedText; markedText = markhits(db->TEXT, "<B>", "</B>"); |
•Return Value - The database field as a text value.
•Version - 5.42 and later.
Example
/* Write fields from db to fh (file handle.) */ /* Output the text using Internet HTML (Hyper */ /* Text Markup Language.) */ OutputHTML(int db; int fh) { int i, j, k, ln; text szText; for (j = 1;j <= db.fields; j = j + 1) { switch(db.type[j]) { case 'P': szText = markhits(wrap(db->j, 65000), "<B>", "</B>"); for (k = findline(szText, 1, ln); k > 0; k = findnline(szText, k, ln)) { write(fh, addr(szText, k), ln)); write(fh, "<BR>", 4); } break; case 'T': writeln(fh, szText="<B>"+db.name[j]+" = </B>" + trim(db->j) + "<BR>", len(szText)); break; case 'D': writeln(fh, szText="<B>"+db.name[j]+" = </B>" + dtoc(db->j, db.length[j]) + "<BR>", len(szText)); break; case 'N': writeln(fh, szText="<B>"+db.name[j]+" = </B>" + str( db->j, db.length[j], db.places[j]) + "<BR>", len(szText)); break; } } } /* OutputHTML() */ |
Match
int match( text target, search; int offset, length ); |
•Description - Locates the search string in the target beginning offset bytes into the target and looking for, at most, length bytes. The length parameter is optional, if it is left out match will look through the entire target string from offset to the end.
•Return Value - The index to the location of the search string in the target string. A zero if no match was made.
•See Also - matchc()
MatchC
int matchc(text target, letterString); |
•Description - Locates the first occurrence of any character from the letter string in the target search string.
•Return Value - The offset of the first matching letter from letterString found in the target. Returns a 0 if no match was found. Note that in the following example, if the character C is found to occur in the target search string before the letters b and a, then the offset returned will be that of the letter C.
•See Also - match()
Example
if (i = matchc(db->TEXT,"abABC")) ... |
Max
float max(float x, y); |
•Description - Determines which value is greater. The parameters x and y can be char, short, int, or float, max() will make the proper comparison regardless of type.
•Return Value - The greater of the two values.
•See Also - min()
MemAvl
int memavl(); |
•Description - Determines the maximum amount of memory that is available for use by your program. This can be important if your program concatenates large character strings. Concordance uses available memory to manipulate the large blocks of text and will produce an insufficient memory error if it cannot allocate enough room.
•Return Value - The largest block of memory that Concordance can allocate for use by your program. This value will change while your program runs.
Example
concatenate(int db, first, second) { text data; /* Check if there is enough memory to join */ /* two large text fields. This test avoids */ /* a FATAL "Insufficient Memory" error. */ if (memavl()<len(db->first)+len(db->second)) { /* There wasn't enough space. */ /* Display a non-fatal message. */ beep(45,200); puts(0,0,"Can't join the two fields."); getkey(); } else /* Enough space, join the fields. */ data = db->first+db->second; return(data); } |
MemCpy
memcpy(destination, source; int bytes); |
•Description - Copies the source data value to the destination for the specified number of bytes. Source and destination should be the same data type, but that is not required. This function should be used with caution as data type and range parameter checking that is performed with direct assignments, a = substr(b,1,10), is not performed with memcpy(). Consequently memcpy() will perform faster in some cases, but it will not provide you with zero terminated strings.
•Return Value - The destination value.
Example
/* Copy to a date field to avoid math conversions */ /* on invalid entries, including zeroed dates. */ memcpy(db->DATE,"19930900",8); See Also memset() |
MemSet
memset(destination; char value; int length); |
•Description - Sets bytes in destination to value for length specified. Destination can be any left-side-value including char, short, int, float, text, or a database field. This function offers a fast way to initialize a string or other variable to a set value.
•Return Value - The destination value.
Example
/* Clear an array before reading from disk. */ memset(string,0,sizeof(string)); read(fh,string,sizeof(string)); See Also memcpy() |
Menu
int menu( int row, col, brow, bcol; text array[]; int next; text "QUICK"); |
•Description - Displays a menu in a window whose screen coordinates are specified by the two row and column parameter pairs.
oThe "next" parameter specifies the first option in the text array[] to highlight when the menu is displayed. The first item in the menu, item zero, is displayed as the title of the menu.
oThe quick keys parameter, which is optional, will cause the menu to return if any of the keys in the list are pressed. The menu is case sensitive, only upper case letters should be in the quick keys list. Keystrokes read by menu() are converted to upper case before processing.
oThe menu() function will leave the selected menu item highlighted. If the user pressed a quick key, the menu() function will attempt to highlight the item which corresponds with the key. Therefore, the quick key list must contain only one key for each item in the menu, and they must be in the same order as the menu items. Additional keys, which do not correspond to displayed menu items, can be included in the list, but they should appear at the end of the list.
•Return Value - The number of the menu item selected or 0 if the ESCape key was pressed. The menu is not cleared from the screen when the user makes a choice.
•See Also - btmenu()
Example
main() { text mymenu[4]; int db, ESC, next; ESC = 27; mymenu[0] = "Research Technology Library"; mymenu[1] = "Search"; mymenu[2] = "Browse"; mymenu[3] = "Edit"; if ((db = opendb("library")) >= 0) next = 1; while (next > 0) { next = menu(5,30,10,50,mymenu,next,"SBEX"); switch(next) { case 1: /* Do a search. */ search(db); break; case 2: /* Browse the database. */ browse(db); break; case 3: /* Edit retrieved documents. */ editfs(db); break; case 'X': /* Option X isn't ON the menu, */ /* it is in the quick key list. */ /* Display available memory. */ puts(0,0,"Memory: "+str(memavl())); break; } } closedb(db); } |
MessageBox
int messageBox(text szText, szTitle; int style); |
•Description - Displays a standard Windows message box with the szText parameter as the message and szTitle as the message box title.
oThe style parameter determines the return value. Combine the style parameters together with the | operator, for instance MB_YESNO | MB_ICONQUESTION. All parameters are predefined by the CPL interpreter. You do not need to declare them to use them. They are all integers. Style is any one of the following values:
Parameter |
Description |
|---|---|
MB_ABORTRETRYIGNORE |
The message box contains three push buttons: Abort, Retry, and Ignore. |
MB_DEFBUTTON1 |
The first button is the default. The first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified. |
MB_DEFBUTTON2 |
The second button is the default. |
MB_DEFBUTTON3 |
The third button is the default. |
MB_ICONEXCLAMATION |
The message box displays an exclamation-point icon. |
MB_ICONINFORMATION |
The information icon, a lowercase letter "I" in a circle, is displayed. |
MB_ICONQUESTION |
A question-mark icon appears in the message box. |
MB_ICONSTOP |
The message box displays a stop-sign icon. |
MB_OK |
The message box contains one push button: OK. |
MB_OKCANCEL |
The message box contains two push buttons: OK and Cancel. |
MB_RETRYCANCEL |
The message box contains two push buttons: Retry and Cancel. |
MB_YESNO |
The message box contains two push buttons: Yes and No. |
MB_YESNOCANCEL |
The message box contains three push buttons: Yes, No, and Cancel. |
•Return Value - A zero is returned if Windows could not create the message box, generally as a result of a low memory condition. Depending on the style parameter, the return values are listed below. All return value parameters are predefined by the CPL interpreter. You do not need to declare them to use them. If a cancel button is available and the user presses the [Esc] key, IDCANCEL is returned.
Parameter |
Description |
|---|---|
IDABORT |
Abort button was selected. |
IDCANCEL |
Cancel button was selected. |
IDIGNORE |
Ignore button was selected. |
IDNO |
No button was selected. |
IDOK |
OK button was selected. |
IDRETRY |
Retry button was selected. |
IDYES |
Yes button was selected. |
•Version - Version 6.53 and later.
Min
float min(float x, y); |
•Description - Determines which value is smaller. The parameters x and y can be char, short, int, or float, min() will make the proper comparison regardless of type.
•Return Value - The lesser of the two values.
•See Also - max()
MkDir
int mkdir(text directoryPath); |
•Description - The mkdir() function creates a new subdirectory with directoryPath name. directoryPath can be either and absolute path name or relative to the current working directory.
•Return Value - mkdir returns zero if successful, nonzero otherwise.
•See Also - chdir(), getcwd(), rmdir(), rename(), erase()
Modify
modify(int db); |
•Description - Concordance full screen database modify command. It allows the user to modify the structure of the database whose handle is db. See the Concordance User Guide for a full description. The screen is automatically saved before entering modify and restored after exiting.
|
This function is not implemented in the Concordance Runtime Module. It will return immediately when called from the Runtime module. |
•Return Value - None.
•See Also - createfs(), createdb(), struc()
Month
int month(int db->field); |
•Description - Extracts the month from the date. The date must be an integer value representing the date, though any passed numeric value will be converted by month() to integer format before processing. The parameter can be a date formatted field, the return value of the ctod() function, or either of these values stored as an integer.
•Return Value - The month of the year as an integer value, 1 - 12.
•See Also - day(), year(), weekday()