Assignments to and from global arrays may be accomplished either with overloaded versions of the shift operators (<< and >>) or the assignment operator (=). Originally, only the shift forms were permitted since restrictions in the C++ language made it difficult to construct assignments from globals to ordinary data types. This was bypassed by using an overloaded impled cast operator which permits most forms of assignment.

When you access a global array, the access may result in the thrown error exceptions GlobalNotFoundException and/or ConversionException. The first can occur in any context that attempts to retrieve data from a global array where none exists. The second occurs if you attempt to convert the contents of a global to a numeric type where the contents of the global are not valid data for the conversion.

If uncaught, both exceptions will result in program termination. Both exceptions may be caught, however, with code such as the following:

The following discussion is divided into two parts: assignment to global arrays and assignment from global arrays:

Assignment TO global arrays

Assignments using the overloaded assignment operator are permitted using the following assignment operator overloads:

Assignment to a global array using the "=" operator is enabled for right hand side variables of types character array (char *), mstring, string, integer, double, etc (see above). For example:

Assignment to global arrays can alos be accomplished by using the overloaded shift operator:

Assignment from global arrays to other data types:

Assignment from global arrays by overloaded shift operator:

Alternatively, the overloaded cast operator can be utilized in combination with the assignment operator ("="):

Each of the above converts the value stored at a global variable to a builtin data type, mstring or string.

Note: the C++ language specification does not permit a fundamental data type (e.g. int, double, char) to be placed on the left hand side of an overloaded assignment ("=") operator. In order to get around this, we use two techniques: (1) the overloaded right-shift operator; and (2) the overloaded cast operator.

Assignment by overloaded right-shift operator copies and, if necessary, converts the global array string value to the target. It works in all cases.

The overloaded cast operator permits fundamental data types to be placed on the left hand side of the assignment operator ("=") and a global array reference to be placed on the right hand side. When the C++ compiler detects a fundamental data type on the left hand side of the assignment operator and a global on the right hand side, it invokes a default cast to convert the right hand side.

In all cases except the one in which the left hand side is char *, the overloaded cast will make the necessary conversion and the assignment will take place as expected. In the case of a char * left hand side, only a pointer to a char * is copied from the global to the left hand side char *. The pointer copied is the address of a public char * string in the global class that contains the value of the global. This pointer is only valid until the next reference to the same global object.

Assignments from global to string or mstring using the assignment operator ("=") copy the value from the global to the object of type string or mstring. Assignments from global to string require a cast of the global consisting of (string &).

The case of assignment from global to mstring is handled by an overload in the class mstring. The case of assignment from global to string is handled by class string which copies the contents of the character string pointed to by the global.

Examples using an arbitrary global array reference with three string indices named gbl(a,b,c) at which is stored the string "12345":

1. Right-shift based assignments (overloaded ">>" operator):

   char target[32]; long s_long; unsigned long u_long; int s_int; unsigned int u_int; short s_short; unsigned short u_short; float float_var; double double_var; string str_var; mstring mstr_var; gbl(a,b,c) >> target; gbl(a,b,c) >> s_long; gbl(a,b,c) >> u_long; gbl(a,b,c) >> s_int; gbl(a,b,c) >> u_int; gbl(a,b,c) >> s_short; gbl(a,b,c) >> u_short; gbl(a,b,c) >> float_var; gbl(a,b,c) >> double_var; gbl(a,b,c) >> str_var; gbl(a,b,c) >> mstr_var; int i; test("1") << 10; // initialize while ( ( test("1") >> i ) > 0 ) { cout << i << endl; test("1") --; }

2. Cast operator based assignments:

   char *p1; long s_long; unsigned long u_long; int s_int; unsigned int u_int; short s_short; unsigned short u_short; float float_var; double double_var; string str_var; p1 = gbl(a,b,c); s_long = gbl(a,b,c); u_long = gbl(a,b,c); s_int = gbl(a,b,c); u_int = gbl(a,b,c); s_short = gbl(a,b,c); u_short = gbl(a,b,c); float_var = gbl(a,b,c) double_var = gbl(a,b,c); str_var = (string &) gbl(a,b,c);

   The character string stored at gbl(a,b,c) is converted and copied to the target variable in all cases except those where the left hand side of the assignment operator is char *. This case does not copy character strings but, instead, copies the address of a string containing the result to the target (see first example).

   This also means the the left hand side of an assignment operator may not be the name of an array of type char since this implies altering the address of the array. The only permitted char left hand side would be a variable pointer to char.

   The value copied to the pointer will be a public address of an array of char in the class containing the value of the global reference. This reference is valid only until another reference to the same global object. This usage is not preferred. Instead, used the shift form or strcpy():

   char out[STR_MAX]; strcpy(out, gbl(a,b,c));

   The overloaded cast assignment form may may be used within larger programming structures such as:

   int i; test("1") = 10; // initialize while ( ( i = test("1") ) > 0 ) { cout << i << endl; test("1") --; }

   The above will print numbers 10 through 1.

Returns the average of the values of data bearing nodes beneath the given global array reference. Example:

The above prints 5.5 - the average value of numeric data bearing nodes beneath A("100"). If there are non-numeric data elements, they are treated as a zero values and contribute to the result.

The global array object must be specified with indices (i.e., a parenthesized list must follow the name of the global array object. An empty list means the entire array.

Returns an integer which is the starting point in the string of pattern or -1 if the pattern is not found. Throws: PatternException if the pattern is in error.

extern "C" int bmg_fullsearch(char * search_string, char * buffer_base);
int bmg_fullsearch(string search_string, string buffer_base);
int bmg_fullsearch(mstring search_string, mstring buffer_base);
int bmg_fullsearch(mstring search_string, global buffer_base);
int bmg_fullsearch(mstring search_string, global buffer_base);

Returns the number of non-overlapping instances of "search_string" in "buffer_base". This function is covered by the LGPL license. The string, global and mstring versions are less efficient than the char * version since they copy the contents of the string, global or mstring variable to a character array.

Note: if you use the char * version, the "buffer_base" may NOT be a character constant or pointer to character constant. The search routines modify this string and using a character constant will generate a segmentation fault on most machines.

Examples:

All use the following functions which are not covered by the GPL/LGPL:

These functions are publically available from:

ftp://ftp.uu.net/usenet/comp.sources.unix/volume5/bmgsubs.Z

and are believed to be contributed source and are unrestricted with respect to use and redistribution, and, that most, if not all, the code was written by employee(s) of the United States and thus in the public domain. The distribution contains, in part, the following notes:

Here are routines to perform fast string searches using the Boyer-Moore-Gosper algorithm; they can be used in any Unix program (and should be portable to non-Unix systems). You can search either a file or a buffer in memory. The code is mostly due to James A. Woods (jaw@ames-aurora.arpa) although I have modified it heavily, so all bugs are my fault. The original code is from his sped-up version of egrep, recently posted on mod.sources and available via anonymous FTP from ames-aurora.arpa as pub/egrep.one and pub/egrep.two. That code handles regular expressions; mine does not. These have only been tested on 4.2BSD Vax systems. -Jeff Mogul mogul@navajo.stanford.edu decwrl!glacier!navajo!mogul BMGSUBS(3L) BMGSUBS(3L) NAME (bmgsubs) bmg_setup, bmg_search, bmg_fsearch - Boyer-Moore-Gosper string search routines SYNOPSIS bmg_setup(search_string, case_fold_flag) char *search_string; int case_fold_flag; bmg_fsearch(file_des, action_func) int file_des; int (*action_func)(); bmg_search(buffer_base, buffer_length, action_func) char *buffer_base; int buffer_length; int (*action_func)(); DESCRIPTION These routines perform fast searches for strings, using the Boyer- Moore-Gosper algorithm. No meta-characters (such as `*' or `.') are interpreted, and the search string cannot contain newlines. Bmg_setup must be called as the first step in performing a search. The search_string parameter is the string to be searched for. Case_fold_flag should be false (zero) if characters should match exactly, and true (non-zero) if case should be ignored when checking for matches. Once a search string has been specified using bmg_setup, one or more searches for that string may be performed. Bmg_fsearch searches a file, open for reading on file descriptor file_des (this is not a stdio file.) For each line that contains the search string, bmg_fsearch will call the action_func function specified by the caller as action_func(matching_line, byte_offset). The match- ing_line parameter is a (char *) pointer to a temporary copy of the line; byte_offset is the offset from the beginning of the file to the first occurence of the search string in that line. Action_func should return true (non-zero) if the search should continue, or false (zero) if the search should terminate at this point. Bmg_search is like bmg_fsearch, except that instead of searching a file, it searches the buffer pointed to by buffer_base; buffer_length specifies the number of bytes in the buffer. The byte_offset parameter to action_func gives the offset from the beginning of the buffer. If the user merely wants the matching lines printed on the standard output, the action_func parameter to bmg_fsearch or bmg_search can be NULL. AUTHOR Jeffrey Mogul (Stanford University), based on code written by James A. Woods (NASA Ames) BUGS Might be nice to have a version of this that handles regular expres- sions. There are large, but finite, limits on the length of both pattern strings and text lines. When these limits are exceeded, all bets are off. The string pointer passed to action_func points to a temporary copy of the matching line, and must be copied elsewhere before action_func returns. Bmg_search does not permanently modify the buffer in any way, but dur- ing its execution (and therefore when action_func is called), the last byte of the buffer may be temporarily changed. The Boyer-Moore algorithm cannot find lines that do not contain a given pattern (like "grep -v") or count lines ("grep -n"). Although it is fast even for short search strings, it gets faster as the search string length increases. 16 May 1986 BMGSUBS(3L)

BTREE() is a macro permitting direct access to the underlying btree system. The first argument, "code" is an integer indicating the operation to be performed (see below). The second argument is the key to be stored consisting of a null-terminated array printable ASCII characters. The length of the key should be no greater than one quarter of the btree block size whose default value is 8192 (i.e., max key length is about 2048 bytes in the default case). The third argument is the data to be stored with the key. It is a null-terminated string of printable ASCII characters not greater than the system defined limit STR_MAX (defaults to 4096). An empty string is interpreted as no data to be stored. Note that the second and third arguments must be unsigned char *. The macro returns an integer indicating success. It may also alter "key" or "data" to return values or for other purposes. The contents of "key" and "data" are not preserved across in invocation of BTREE() Examlples of using BTREE() are given in mumpsc/doc/examples/btree.

Permitted btree operations:

1. STORE - store a key and data value in the btree; retuns zero if successful, non-zero otherwise:

         unsigned char key[]="test key";
         unsigned char data[]="test data";
         if ( BTREE(STORE,key,data) == 0 ) cout << "stored" << endl;
         else cout << "not stored" << endl;
   

2. RETRIEVE - retrieve data stored with a key; returns zero if successful, non-zero otherwise:

         unsigned char key[]="test key";
         unsigned char data[STR_MAX];
         if ( BTREE(RETRIEVE,key,data) == 0 ) cout << "retrieved: " << data << endl;
         else cout << "not retrieved." << endl;
   

3. CLOSE - close the btree data base; returns zero:

         unsigned char key[]="";
         unsigned char data[]="";
         BTREE(CLOSE,key,data);
   

4. XNEXT/PREVIOUS - retrieve next ascendina/descending key; returns one. Value of second and third arguments become the value of the next ascendina/descendingg key. An initial value of the empty string for the second argument will retrieve the first/last key and the value of the second argument becomes the empty string when there are no more ascending/descending values. An initial value of the empty string for the second argument will retrieve the first/last key.

         unsigned char key[]="";
         unsigned char data[STR_MAX];
         printf("\nbegin retrieve...\n");
         while(1) { // rerteive keys in ascending order
               i=BTREE(XNEXT,key,data);
               if (strlen( (char *) data)==0) break;
               cout << key << endl;
               }
   
   

A centroid vector B is calculated for the invoking two dimensional global array. The centroid vector is the average value for each for each column of the matrix. Any previous contents of the global array named to receive the centroid vector are lost. The invoking global array (A) must contain at least two dimensions. For example:

The above yields a vector giving the average value of each named column of the matrix "A" (5 in this case since each column is initialized with 5).

"CleanLocks()" removes all locks for the current process. "CleanAllLocks()" removes all locks for all processes for which the current directory is the default directory. Locks are implemented by entries in a file named "Mumps.Locks" created and maintained in the current directory. This file must be read/write enabled for the current process. You may also delete all locks by removing this file. Locks are discussed elsewhere but, in brief, they are used to signal ownership of a portion of a global array. When a lock has been applied to a node, no other process may lock this node, any descendant node or any parent node. Locking does not actually prevent access, it merely marks a resource as locked.

Returns a char * to a NULL terminated character string containing the same value as the mstring variable.

"command()" is a macro that takes a quoted string constant argument. The macro surrounds the string with an extra set of quotes and processes any embedded quotes to backslash-quote. It then invokes a function (__command__()) which strips the extra surrounding quotes. The net effect of this is that you can pass a quoted string containing quotes without the need for "leaning toothpick" notation. Example:

Normal usage: 

$pattern(source_str, "3n1\"-\"2n1\"-\"4n") 
strcpy(target, "for i=1:1:10 write \"test \",i,!"); 

with command(): 

$pattern(source_string, command("3n1"-"2n1"-"4n")) 
xecute(command("for i=1:1:10 "test ",i,!")); 
strcpy(target, command("for i=1:1:10 write "test ",i,!")); 

The argument must be a character string constant.

The comparison operators >, >=, <, <=, ==, and != are defined for global arrays. The determination of the mode of the comparison is based on the other operand. That is, if a global array is compared with an integer, integer comparison will be used; if it is compared with a character string, character string comparison will be used. The contents of the data stored at the global array node must be compatible with the comparison mode. When two gloabl array elements are compared, the comaprison will be a string comparison, regardless of the contents. For example:

Note that the mode of comparison is dependent upon the second operand. In the case of string comparisons, an ASCII comparison takes place thus "123" is less than "2".

char *cvt(long i)
char *cvt(double i)
char *cvt(float i)
char *cvt(int i)

These functions return a null terminated varying length character string containing in printable version of the argument. The functions contain short static character arrays and, consequently, are not threadsafe. Note that char * can be assigned to variable of typ string. These functions are mainly useful to get string values for global array indices. BEcause these functions use static character arrays, do not use these functions directly as indices to global arrays. Example:

This macro closes the global array files. The global arrays must be closed on exit or they will be corrupt. The macro causes the file system to flush all its buffers and cache and close the file system. Normally, a "GlobalClose" is executed automatically when your program ends except if your program is terminated by SIGKILL or SIGSTOP (which cannot be trapped). If your program is using a large memory based cache (cache's can be 1 GB or more, on some systems), there may be a noticeable delay in file system shutdown due to the time required to write the cache to disk.

void global::TermCorrelate(global B)
void global::DocCorrelate(global B, string fcnname, double threshold)
void global::DocCorrelate(global B, mstring fcnname, double threshold)
void global::DocCorrelate(global B, char * fcnname, double threshold)

These functions build document indexing correlation matrices. The invoking global is assumed to be a two dimensional document-term matrix whose rows are documents and whose columns represent the occurrence of terms in the documents (either weights or frequencies).

TermCorrelate() builds a square term-term correlation matrix in B from the invoking document-term matrix.

DocCorrelate() builds a square document-document correlation matrix from the invoking document-term matrix. The name of the function to be used in calculating the document-document similarity is given in fcn and may be Cosine, Jaccard, Dice, or Sim1. The minimum corrrelation threshold is given in threshold which defaults to 0.80 if omitted.

The above gives the number of co-occurences of each word with each other word. For example, the words "computer" and "memory" co-occur in two vectors (2 nd 3) while the words "laptop" and "computer" co-occur in all three vectors. If each vector is thought of as a document, the strength of the co-occurences between words is a measure of similarity for indexing purposes.

The above program calculates the similarities between the document vectors according to the Cosine method.

Returns the number of data bearing nodes beneath the given global array reference. Example:

int $data(global)
int global.Data()

The functions $data() and global::Data() function returns an integer which indicates whether the global array node is defined. The value returned is 0 if the global array node is undefined, 1 if it is defined and has no descendants; 10 if it is defined but has no value stored at the node (but does have descendants); and 11 it is defined and has descendants.

If a global array with no indices is passed to these functions, a value of "10" will be returned if the array exists and "0" if the array does not exist. For example:

Locates the pattern in the invoking mstring and inserts left immediately to the left of the string that matched the pattern and inserts right immediately to the right of the found pattern. Returns 1 if the pattern was found and the insertions were made, -1 if the pattern was not found, and less than -1 for other errors (see PCRE documentation concerning pcre_exec() return codes). Throws: PatternException().

Encodes the argument string according to HTML rules and returns the result. Alphabetics and numbers are unchanged. Blanks become plus signs and all other characters replaced by "%xx" where "xx" is the hexadecimal value of the character in the ASCII collating sequence. The function is used mainly in connection with parameters passed with URL's which may not contain blanks or special characters. the code in cgi.h is used to decode these strings. Example:

Returns an integer giving the character position (relative to zero) immediately following the strincg that matched pattern. Returns -1 if the string did not match. Throws: PatternException.

extern "C" void ErrorMessage(char * message, int line_number)

This function (written in C and part of the underlying legacy library) will print and error message, close the global array files and terminate the program. The integer "line_number" will be printed with the message. The pre-processor predefined macro "__LINE__" can be used here. Example:

ErrorMessage("Cannot locate patient",__LINE__);

The toolket generates (throws) exceptions for certain conditions. For example, when you access global arrays with the toolkit, the accesses may result in the thrown error exceptions:

1. ConversionException.
2. GlobalNotFoundException
3. MumpsSymbolTableException.
4. NumericRangeException.

The first can occur in any context that attempts to retrieve data from a global array where none exists. The second occurs if you attempt to convert the contents of a global to a numeric type where the contents of the global are not valid data for the conversion.

If uncaught, both exceptions will result in program termination.

The following are the exceptions thrown by the toolkit:

1. ConversionException() - usually occurs when you attempt to store a value from a global array into a numeric variable but the string in the global is not a valid number.
2. GlobalNotFoundException() - thrown by an attempt to reference non-existent global array data.
3. MumpsSymbolTableException() - thrown by an attempt to fetch the value of a non-esistent variable from the Mumps runtime symbol table.
4. NumericRangeException() - thrown by attempts to divide by zero or using arguments with values less that or equal to zero to log functions.

Returns a pointer to a substring substring of the first argument. The substring begins at the position noted by the second operand. If the third operand is omitted, the substring consists only of the "start" character of "source_string". If the third argument is present, the substring begins at position "start" and ends at position "end". If only "source_string" is given, the function returns the first character of the string "source_string". If "end" specifies a position beyond the end of "source_string", the substring ends at the end of "source_string". String position counting begins at one. Global arrays may be used in any argument position but only one instance of the same global may appear (see note in Accessing global arrays) section. For example:

$find() searches the first argument for an occurrence of the second argument. If one is found, the value returned is one greater than the end position of the second argument in the first argument. If "start" is specified, the search begins at position "start" in argument 1. If the second argument is not found, the value returned is 0. String position counting begins at position one. For example:

Global arrays may be used in any argument position but only one instance of the same global may appear (see note in Accessing global arrays) section.

mstring GlobalGet (mstring global_ref)
string GlobalGet (string global_ref)
char * GlobalGet (char * global_ref)

mstring GlobalOrder (mstring global_ref, int direction)
string GlobalOrder (string global_ref, int direction)
char * GlobalOrder (char * global_ref, int direction)

int GlobalData (mstring global_ref)
int GlobalData (char * global_ref)
int GlobalData (string global_ref)

int GlobalSet (mstring global_ref, mstring source)
int GlobalSet (mstring global_ref, char * source)
int GlobalSet (char * global_ref, mstring source)
int GlobalSet (string global_ref, string source)
int GlobalSet (string global_ref, char * source)
int GlobalSet (char * global_ref, string source)
int GlobalSet (char * global_ref, char * source)

These function use the interpreter. These functions are used to permit runtime construction and access to global arrays. In both cases global_ref is a string containing a global array reference. This string can be dynamically constructed at runtime or may be read from a file or another global. Note: as this facility uses the interpreter, global array references must be preceded by the circumflex character (^).

In the case of the GlobalGet() functions, the string global array reference is interpreted and the value stored at the reference returned. If the reference is invalid or no data is stored, the value returned is the empty string and $test is set to false (zero). If a value is found, $test is set to true and the value is returned.

GlobalOrder() gives the next or prior value of the last index of the global array reference depending upon if direction is 1 (next) or -1 (prior). $test is set to 0 in the event of an error and 1 if there is no error. See $order().

GlobalData() returns a number indicating if the node exists and has descendants (see $data()). $test is set to 0 if there i>s an error, 1 otherwise. In the case of the GlobalSet() functions, the second argument is a string of data to be stored at the global array reference. The runtime routines will interpret the global_ref and assign the source to it. The value returned is one if successful ($test is set to 1), zero if not successful ($test set to 0). Examples:

These functions can be used to allow a program to create a text string global array reference and then use the string to address the global. Note that the target must contain either quoted literals or variables previously instantiated to the interpreter environment (see $SymSet() and $SymGet()).

Generally speaking, these functions will be only used for dynamically constructed global array references. Most access to globals will be by overloaded shift or assignment operators.

double HitRatio(void)

Calculates the native global array processor cache hit ratio since the beginning of the program or the last call to "HitRatio()". The native global array file processor, as opposed to the Berkeley Data Base, keeps track of how many file I/O requests are satisfied from data already in the file system's cache. This function gives the percentage of cache hits. It only works with the native global array processor.

char * hash(char * str)
long lhash(char * str)

hash() returns either a null terminated character string up to 10 characters in length containing a numeric hash code of the string passed as an argument. The argument may be up to STR_MAX characters in length. lhash() returns an unsigned long value of the hash value. See also: Hash class.

char * $horolog

Returns a pointer to a static null terminated array of character containing of two numbers. The first is the number of days since December 31, 1840 and the second is the number of seconds since the most recent midnight. These values are relative to Greenwich Mean Time.

void global::IDF(doubleDocCount)

The IDF() function calculates for the global array vector provided the inverse document frequency weight of each term. The vector should be indexed by words and have stored the number of documents in which each word occurs. The document count will be replaced by the calculated IDF value. The IDF is log2(DocCount/Wn)+1 where Wn is the number of documents in which a term appears (the document freqwuency). The value DocCount is the total number of documents present in the collection. Example:

$justify() right justifies the first argument in a string field whose length is given by the second argument. If the third argument is -1, the first argument is interpreted as a string. If the third argument is a positive integer, the first argument is right justified in a field whose length is given by the second argument with "precision" decimal places. The three argument form imposes a numeric interpretation upon the first argument. Both the "field_width" and "precision" MUST be present. For example:

Global arrays may be used in any argument position but only one instance of the same global may appear (see note in Accessing global arrays) section.

These functions delete a node and all its descendants. Examples:

The function returns the string length of its argument. For example:

If a second argument is given, the function returns the number of non-overlapping occurrences of "pattern_string" in "source_string" plus 1.

Global arrays may be used in any argument position but only one instance of the same global may appear (see note in Accessing global arrays) section.

Creates a lock on the named node. If successful, "$test" will be true (1), false (0) otherwise. Both forms return a 1 if the lock succeeds and a 0 otherwise.

The "Lock()" function marks a portion of the data base for exclusive access for an individual user. The "UnLock()" frees prior locks (see below). The locks are stored in a file named "Mumps.Locks" which is opened for exclusive access by the locking/unlocking job. The contents of the file may be deleted to remove all locks. A lock does not actually prevent access to a global but merely marks it as locked. If another task attempts to place a lock on a locked node, the descendant of a locked node or a direct parent of a locked node, the lock attempt will fail. Examples:

See also: CleanLocks(), CleanAllLocks(), and UnLock().

Returns the maximum numeric value of the data bearing nodes beneath the given reference. Non-numeric values are treated as zeros. Example:

Copies the first global and its descendants to the second global. The Merge() function copies from one array to another. Examples:

Returns the minimum numeric value of the data bearing nodes beneath the given reference. Non-numeric values are treated as zeros. Example:

For the non-member versions, the two dimensional matrix named in the string A is multiplied by the two dimensional matrix named in the string B and the result becomes the contents of two dimensional matrix named in the string C. The number of columns of A must equal the number of rows of B. The resulting matrix C will have "n" rows and "m" columns where "n" is the number of rows of "A" and "m" is the number of columns of "B".

For the member version, the invoking object is multiplied by B and the result is place in C. The dimensionality of "C" is as above.

In all cases C will be deleted before the operation commences. The data stored at each node must be numeric. All calculations are performed in double arithmetic. Each matrix must be two dimensional. Example:

Returns a null terminated pointer to array of characters containing of the global reference with all variables and expressions in the indices evaluated. Example:

char * $order(global, int direction)
char * global.Order(int direction)
int global.Order_Next(char * result)
int global.Order_Prior(char * result)

The order functions give the next ascending or descending value of the last index in a global array reference. The direction, ascending or descending, is given by either the name of the function or an integer "direction" which is either 1 - next ascending index, or -1 - next descending index. For example, if an array named "test" has nodes:

Use the empty string ("") to get the initial value of an index. When there are no further values, the empty string is returned.

The "order()" functions traverse an array from one sibling node to the next in key ascending or descending order. The result returned is the next value of the last index of the global or local array given as the first argument. The default traversal is in key ascending order except if the second argument evaluates to "-1" in which case the traversal is in descending key order. If the second argument has a value of "1", the traversal will be in ascending key order.

Note: all keys are stored in ASCII character collating order. This means that numeric keys are sorted alphabetically rather than numerically. Example:

int global.Order_Next(char * result)

Returns next ascending value of the last index (c) - direction implied - and sets "result" to the value of the index. Use the empty string ("") to get the initial value. When there are no further values, the empty string is returned in result and the value of the function is zero.

int global.Order_Prior(char * result)

Returns next descending value of the last index (c) - direction implied - and sets "result" to the value of the index. Use the empty string ("") to get the initial value. When there are no further values, the empty string is returned in result and the value of the function is zero.

A global array may participate in "cout" stream output. For example:

gbl("A","B","C") << "test test test";
cout << gbl("A","B","C") << endl;

The above will print "test test test" (without quotes) followed by the newline character. Alternatively:

cout << gbl("A","B","C").Get() << endl;

will do the same thing (the Get() function returns "char *" which is already defined for "cout").

Evaluates the source_string according to the pattern_string and returns 0 (does not match) or 1 (does match). Pattern_string rules are as as shown below but you must remember to place a backslash before quotes in the pattern string (as per usual C++ rules). The pattern match function is used to determine if a string conforms to a certain pattern. Pattern match operations are converted to Perl Compatible Regular Expressions and are executed by functions in the PCRE library which must be present. You may access the PCRE directly, using Perl expression format with the "perl_pm(string, pattern, 1, svPtr)" function discussed in Appendix D.

The pattern codes are:

A for the entire upper and lower case alphabet.
C for the 33 control characters.
E for any of the 128 ASCII characters.
L for the 26 lower case letters.
N for the numerics
P for the 33 punctuation characters.
U for the 26 upper case characters.
A literal string.

A pattern code is made up of one or more of the above, each preceded by a count specifier. The count specifier indicates how many of the named item must be present. Alternatively, an indefinite specifier - a decimal point - may be used to indicate any count (including zero). For example:

Full pattern matching syntax, including support for alternation, are supported as described in Appendix D of the Compiler manual. The macro "command()" will handle the required backslash escape characters required before quote marks.

The regular expression in the null terminated character array pointed to by regex is applied to the null terminated character array pointed to by string. If the pattern match succeeds, true (1) is returned, false (0) otherwise and $test is set accordingly. This macro also sets variables in the run-time symbol table. See $SymGet() and $SymPut() for details on accessing the symbol table. See Appendix D for examples of using this function.

Global arrays may be used in any argument position but only one instance of the same global may appear (see note in Accessing global arrays) section.

The $piece() function returns a substring of the first argument delimited by the instances of the second argument. The substring returned in the three argument case is that substring of the first argument that lies between the "start" minus one and "start" occurrence of the second argument. In the four argument form, the string returned is that substring of the first argument delimited by the "start" minus one instance of the second argument and the i4'th instance of the second argument. If only two arguments are given, i3 is assumed to be 1. For example:

$PIECE("A.BX.Y",".",2) YIELDS "BX"
$PIECE("A.BX.Y",",",1) YIELDS "A"
$PIECE("A.BX.Y",".",2,3) YIELDS "BX"

Global arrays may be used in any argument position but only one instance of the same global may appear (see note in Accessing global arrays) section.

char * global.Query()
char * global.Query(char)
$query(global)
$queryX(global,char))

Returns a character string pointer to the next global array reference in the data base or the empty string. In the forms global::Query(char) and $queryX(global,char), the char argumnet is a pattern character that will replace commas and parentheses in the returned result. Global array references are returned with the elements of the global separated by commas and parentheses for Query() and $query(). Example:

$query("A(1,1)") yields A(1,2) where A(1,2) follows A(1,1) in the data base.

A(1,1).Query() yields A(1,2) where A(1,2) follows A(1,1) in the data base.

Global array references are returned with commas and parentheses replaced by a pattern character for Query(char pat) and $queryX(global ref,char pat). Example:

$queryX("A(1,1)",'#') yields A#1#2# where A(1,2) follows A(1,1) in the data base.

A(1,1).Query('#') yields A(1,2) where A#1#2# follows A(1,1) in the data base.

Note that text indices returned by these functions are not quoted. If you build a new global array reference (as shown below), you will need to enclose any text indices in double quotation marks. Numeric indices do not need to be quoted.

Replaces the string matching pattern with replacement. Returns 1 if successfull, 01 if there was no match and less than -1 on error (See PCRE documentation for pcre_exec()). Throws: PatternException.

Returns a char * to a character string containing the same value as the mstring variable.

The Shred() function shreds the input string str into fragments of length size upon successive calls. The function returns a string of length zero when there are no more fragments of length size remaining (thus, short fragements at the end of a string are not returned). Shred() copies the input string to an internal buffer upon the first call. Subsequent calls retrieve from this buffer. When the buffer is consumed, the fuction will copy the contents of the next string submitted to the buffer. Example:

The ShredQuery() function shreds size shifted copies of the input string str into fragments of length size upon successive calls. That is, the function first returns all the size fragments of the string in the same manner as Shred(). However, it then shifts the starting point of the input string to the right by one and returns all the size length fragments relative to the shifted starting point. It repeats this process a total of size times.

The function returns a string of length zero when there are no more fragments of length size remaining (thus, short fragements at the end of a string are not returned). ShredQuery() nitially copies the input string to an internal buffer upon the first call. Subsequent calls retrieve from this buffer. When the buffer is consumed, the fuction will copy the contents of the next string submitted to the buffer. Example:

double global::Sim1(global B)
double global::Cosine(global B)
double global::Jaccard(global B)
double global::Dice(global B)

The global arrays referenced by the invoking object and the passed object are compared and a similarity value is computed. The functions compute the similarities of the data bearing nodes beneath the global array references.

double global::Sim1(global B) computes the simple pairwise sum of the products of the values stored at nodes having the same suffix array reference. For example:

double global::Cosine(global B) is invoked in the same manner and computer the Cosine similarity metric. Likewise, Dice and are other commonly used similarity metrics invoked in the same manner (see Salton, G; and McGill, M, Introduction to Modern Information Retrieval, McGraw Hill, 1983).

int sw(mstring s, mstring t, [int show_aligns=0, int show_mat=0, int gap=-1, int mismatch=-1, int match=2])
int sw(string s, string t, [int show_aligns=0, int show_mat=0, int gap=-1, int mismatch=-1, int match=2])
int sw(char *s, char *t, [int show_aligns=0, int show_mat=0, int gap=-1, int mismatch=-1, int match=2])

Calculate the Smith-Waterman Alignment between strings "s" and "t". Result returned is the highest alignment score achieved. Parameters other than the first two are optional. If only some of the optional parameters are supplied, only trailing parameters may be omitted, as per C/C++ rules.

If you compare very long strings (>100,000 character), you may exceed stack space. This can be increased under Linux with the command:

ulimit -s unlimited

(Other options are ulimit -a and ulimit -aH to show limits).

If "show_aligns" is zero, no printout of alternative alignments is produced (default). If "show_aligns" is not zero, a summary of the alternative alignments will be printed. If "show_mat" is zero, intermediate matrices will not be printed (default). The gap and mismatch penalties are -1 and the match reward is +2. The parameters "gap", "mismatch" and "match" are the gap and mismatch penalties (negative integers) and the match reward (a positive integer). These values default to -1, -1 and 2 resectively. If insufficient memory is available, a segmentation violation will be raised. The first character of each sequence string MUST be blank. Example:

Returns the original word or the english linguistic root stem of the word, if one can be found. The char* form alters the word passed if a linguitsic stem is found.

The global array nodes beneath the referenced global array are summed. Non numeric quantities are treated as zero. Example:

mstring $SymGet(mstring name)
string $SymGet(string name)
char * $SymGet(char * name)
mstring $SymPut(mstring name, mstring value)
string $SymPut(string name, string value)
char * $SymPut(char * name, char * value)

These macros retrieve and store values from/to the run-time symbol table. In all, name is a a string containing the name of the variable and value is the value to be stored. The SymPut() functions return the string stored. A MumpsSymbolTableException exception is raised if $SymGet() fails. If $SymPut() fails, the program terminates (out of memory).

char **global.Select(char * [,char *, ... ])
char ** global.Select(string [,string &, ...])
char ** global.Select(mstring [,mstring &, ...])

Used in connection with a relational treatment of a global array. The Select() functions locate the next ascending row of the named global and set the specified variables to the corresponding columns of the row. If the next row has fewer columns than there are variables specified, the excess variables are set to the empty string. If a row has more columns than there are variables specified, only the variables specified are set. The function returns an array of pointers to char * that point to the text values of all existing columns successively. Pointers for non-existing columns have the value of NULL. That is, if the row has 5 columns, there will be 5 pointer numbered 0 through 4. Pointers above 4 will be NULL. If pointer 0 is NULL, there were no more rows for this global array. Example:

The above program creates a global array s() of 100,00 elements. The array is then accessed row by row selecting only those rows where the first column has the value "1". Rows selected are copied to another array named tmp() which is ultimately printed.

This facility can be used to manipulate global arrays as relational tables.

void StopInit(mstring file)
void StopInit(string file)
void StopInit(char * file)
int StopLookup(mstring word)
int StopLookup(string word)
int StopLookup(char * word)

StopInit() reads the sorted file "file" of stoplist words into the stoplist container (one word per line). StopLookup() returns 0 if "word" is not found and 1 if "word" is found in the stoplist.

int SynInit(mstring filename)
int SynInit(string filename)
int SynInit(char * filename)
mstring SYN(mstring word)
string SYN(string word)
char * SYN(char * word)

SysInit() opens and reads a synonym file and returns the number of lines read. The maximum number of synonyms permitted is determined by "SYNMAX" in libmpscpp.h (default is 20,000). Each line of the synonym file consists of multiple words, in lower case, separated from on another by a single blank. The first word is the root alias and the remaining words are alternative synonyms. The function SYN() looks up a word. If the word is an alternative synonym, the root alias is returned. If not, the original word is returned.

Prints the global array in tablular form. If"indt" is given, it is the number of positions between columns. If "indtchr" is given, it is the character repeated between columns. If not given, the character between columns is space.

Returns integer 1 or 0 indicating the success or failure of certain previous commands. Some, but not all, commands set "$test".

Returns a pointer to the next word token from the input string. This function is passed a line of text. For each subsequent call, a pointer is returned to the next lexical word from the string with punctuation removed. When there are no more words, a pointer to the empty string is returned. After the pointer to the empty string is returned (or when initially called), the function will accept and store a new line of text. Lexical words are alphanumeric strings delimited by punctuation and white space.

For the non-member versions, the first two dimensions of the array named as in is transposed into the array named out. The array names are specified as unsubscripted null terminated character strings. For the member version, the invoking object is transposed and the result is placed in out. In all versions, out is deleted before the operation commences. Example:

The invoking object is printed as an indented tree. If one argument is present (indt), it is the amount of indentation. If the second argument is present (indtchr) it is the character used in the indentation. The default indentation character is blank and the default amount of indentation is one. Example:

UnLock() removes a lock from the designated node.

These functions invoke the Mumps interpreter which executes command. Returns 1 of successful, 0 otherwise. The macro Xecute() is a special case. It is used with character string constants. It will pre-process a character string constant command and insert the backslash escape character prior to any embedded quotes thus permitting more normal appearing text (see similar macro command()). Global arrays created by C++ programs are fully compatible with the interpreter except that, in the interpreter, global array names are prefixed by the circumflex character in the normal manner. Examples:

    mstring c;
    Xecute("for  s i=$Order(^a(i)) q:i="" s sum=sum+^a(i)");
    c="for i=1:1:10 write i,!";
    xecute(c);
    c=command("for i=1:1:10 write "ans=",i,!");
    xecute(c);

/*+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ #+ #+ Mumps Bioinformatics Software Library #+ Copyright (C) 2003 by Kevin C. O'Kane #+ #+ Kevin C. O'Kane #+ okane@cs.uni.edu #+ #+ This program is free software; you can redistribute it and/or modify #+ it under the terms of the GNU General Public License as published by #+ the Free Software Foundation; either version 2 of the License, or #+ (at your option) any later version. #+ #+ This program is distributed in the hope that it will be useful, #+ but WITHOUT ANY WARRANTY; without even the implied warranty of #+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #+ GNU General Public License for more details. #+ #+ You should have received a copy of the GNU General Public License #+ along with this program; if not, write to the Free Software #+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA #+ #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*/ #include <mumpsc libmpscpp.h> //================================================================== // Globals must be declared in the following manner. // A global is defined by doing two things: (1) defining // a preprocessor macro for it and, (2) instantiating // an instance of "global" for it. The macro (#define) // needs to appear at the beginning of the program but the // instatiations may be occur either globally or internal // to the functions that use them. // The macros are named "char_global" and "int_global". // The "char_global" macro is for global arrays whose indices // will all be strings (type "char *") while "int_global" // is for globals all of whose indices will by integers ("long"). // Note: global array names do not begin with the "^" character // as "^" is an operator in C/C++. // The following declares three globals: "df", "abc" and "ABC". global df("df"); global abc("abc"); global ABC("ABC"); global *gptr; int main() { //================================================================== // Kill (delete) all previous data in global "df". Note: the empty // string is required if there is no argument. The following // command deletes any prior "df" array. The following contains // two ways to "kill" globals. Both do the same thing. kill (df()); // kill all "df" //================================================================== // Storing data into globals. Indices MUST be null terminated // char arrays. { long i=10,j=20; char a[32] = "88"; string s1 = "test test"; // shift operator assignments df(a) &lt;&lt; "999"; // char string df(a) &lt;&lt; 999.0; // double df(a) &lt;&lt; 999; // long df(a) &lt;&lt; s1; // string // assignment operator assignments df(a) = "999"; // char string df(a) = 999.0; // double df(a) = 999; // long df(a) = s1; // string df(a) = i+j; // from expressions df(a) = df(a) * i; // with expressions df(a) += 5; // increments the global by 5 df(a)++; // increments in "double" mode df(a)--; // decrements in "double" mode cout &lt;&lt; df(a) &lt;&lt; endl; gptr = new global ("df"); cout &lt;&lt; (*gptr)(a) &lt;&lt; endl; (*gptr)("1234") = "test with pointer"; cout &lt;&lt; (*gptr)("1234") &lt;&lt; endl; } //==================================================================== // Values stored at array nodes are strings but // other data types are automatically converted. // Note: the following example uses the int_global // macro definition so integer indices are permitted: { long i,j; for (i=1; i&lt;10; i++) for (j=1; j&lt;10; j++) { string s1=cvt(i); string s2=cvt(j); abc(s1,s2) &lt;&lt; i+j; } cout &lt;&lt; "Numeric indices " &lt;&lt; endl; for (i=1; i&lt;10; i++) for (j=1; j&lt;10; j++) { string s1=cvt(i); string s2=cvt(j); cout &lt;&lt; i &lt;&lt; " " &lt;&lt; j &lt;&lt; " " &lt;&lt; abc(s1,s2) &lt;&lt; endl; } } //================================================================== // Retrieving and manipulating global array data { string S,S1; char s[32]; long i; float x; double z; char a[]="88"; kill (df()); df("88") &lt;&lt; 123; // initialize q node // shift operator assignments df(a) &gt;&gt; s; // assigns "123" to s df(a) &gt;&gt; S; // assigns "123" to S df(a) &gt;&gt; i; // assigns 123 to i df(a) &gt;&gt; x; // assigns 123. to x df(a) &gt;&gt; z; // assigns 123. to z // asignment operator assignments. // Note: do not use this form with a "char *" target. S = df(a); // assigns "123" to S i = df("88"); // assigns 123 to i x = df("88"); // assigns 123. to x z = df("88"); // assigns 123. to z i = df("88") + 1; // stores 124 in i z = df("88")++; // stores 124 in i and increments the global z = --df("88"); // decrements the global and stores 123 in i // Note: ++ and -- operate in "double" mode // only and assignment to non-doubles will // result in a warning. // Output of globals. cout &lt;&lt; "expect 123 " &lt;&lt; df(a) &lt;&lt; endl; //================================================================== // $data() - two variations (each does the same thing) cout &lt;&lt; $data(df(a)) &lt;&lt; endl; cout &lt;&lt; df(a).Data() &lt;&lt; endl; i = $data(df(a)); cout &lt;&lt; i &lt;&lt; endl; //================================================================== // $query() function: cout &lt;&lt; "expect df(88) " &lt;&lt; $query(df()) &lt;&lt; endl; //================================================================== // $piece() function: cout &lt;&lt; $piece("abc def ghi"," ",2) &lt;&lt; endl; df("1")="aaa bbb ccc"; cout &lt;&lt; "expect bbb " &lt;&lt; $piece(df("1")," ",2) &lt;&lt; endl; //================================================================== // $ascii() function cout &lt;&lt; "$ascii(\"ABC\") expect 65: " &lt;&lt; $ascii("ABC") &lt;&lt; endl; cout &lt;&lt; "$ascii(\"ABC\",1) expect 65: " &lt;&lt; $ascii("ABC",1) &lt;&lt; endl; cout &lt;&lt; "$ascii(\"ABC\",2) expect 66: " &lt;&lt; $ascii("ABC",2) &lt;&lt; endl; cout &lt;&lt; "$ascii(\"\") expect -1: " &lt;&lt; $ascii() &lt;&lt; endl; S="ABC"; cout &lt;&lt; "$ascii(S) expect 65: " &lt;&lt; $ascii("ABC") &lt;&lt; endl; cout &lt;&lt; "$ascii(S,1) expect 65: " &lt;&lt; $ascii("ABC",1) &lt;&lt; endl; cout &lt;&lt; "$ascii(S,2) expect 66: " &lt;&lt; $ascii("ABC",2) &lt;&lt; endl; //================================================================== // $pattern() function: strcpy(s, "123-34-6789"); cout &lt;&lt; "pattern test: expect 1 " &lt;&lt; $pattern(s,"3n1\"-\"2n1\"-\"4n") &lt;&lt; endl; S=s; cout &lt;&lt; "pattern test: expect 1 " &lt;&lt; $pattern(S,"3n1\"-\"2n1\"-\"4n") &lt;&lt; endl; //================================================================== // $justify() function cout &lt;&lt; "justify char * const expect 1.23 " &lt;&lt; $justify("01.234567",4,2) &lt;&lt; endl; df("1")="01.234567"; cout &lt;&lt; "justify global expect 1.23 " &lt;&lt; $justify(df("1"),4,2) &lt;&lt; endl; S = "01.234567"; cout &lt;&lt; "justify string expect 1.23 " &lt;&lt; $justify(S,4,2) &lt;&lt; endl; //================================================================== // $length() function cout &lt;&lt; "$length() expect 3: " &lt;&lt; $length("ABC") &lt;&lt; endl; S="ABC"; cout &lt;&lt; "$length() expect 3: " &lt;&lt; $length(S) &lt;&lt; endl; cout &lt;&lt; "$length() expect 4: " &lt;&lt; $length("abcabcabc","abc") &lt;&lt; endl; S="abcabcabc"; S1="abc"; cout &lt;&lt; "$length() expect 4: " &lt;&lt; $length(S,S1) &lt;&lt; endl; //================================================================== // $extract() function cout &lt;&lt; "extract: expect 34 " &lt;&lt; $extract("123456789",3,4) &lt;&lt; endl; cout &lt;&lt; "extract: expect 3 " &lt;&lt; $extract("123456789",3) &lt;&lt; endl; cout &lt;&lt; "extract: expect 1 " &lt;&lt; $extract("123456789") &lt;&lt; endl; S="123456789"; cout &lt;&lt; "extract: expect 34 " &lt;&lt; $extract(S,3,4) &lt;&lt; endl; cout &lt;&lt; "extract: expect 3 " &lt;&lt; $extract(S,3) &lt;&lt; endl; cout &lt;&lt; "extract: expect 1 " &lt;&lt; $extract(S) &lt;&lt; endl; //================================================================== // $find() function cout &lt;&lt; "find: expect 4 " &lt;&lt; $find("kevin","v") &lt;&lt; endl; cout &lt;&lt; "find: expect 0 " &lt;&lt; $find("kevin","v",4) &lt;&lt; endl; S="kevin"; S1="v"; cout &lt;&lt; "find: expect 4 " &lt;&lt; $find(S,"v") &lt;&lt; endl; cout &lt;&lt; "find: expect 4 " &lt;&lt; $find("kevin",S1) &lt;&lt; endl; cout &lt;&lt; "find: expect 0 " &lt;&lt; $find(S,S1,4) &lt;&lt; endl; //================================================================== // $name() function strcpy(a, "88"); cout &lt;&lt; "expect df(88) " &lt;&lt; $name(df(a)) &lt;&lt; endl; //================================================================== // Xecute a Mumps code string. The first parameter is the string // to execute and the remaining parameters are variables. The // contents of the variables will be copied to the Mumps // interpreter environment when the interpreter is invoked // and their values will be copied back on exit. In the // example, the value of "a" is copied to, and used by, the // interpreter. The value created in the interpreter ("s") // is copied back on return. Values in the interpreter are // persistent across invocations. // the macro command() permits normal (as oppossed to \") quote use // Note: the variables passed to/from the Mumps environment MUST // null terminated character strings. xecute("set s=^df(a)",a,s); cout &lt;&lt; "expect 123: " &lt;&lt; s &lt;&lt; endl; char t[]="123"; xecute(command("write "t=",t,!"),t); cout &lt;&lt; "expect 1 thru 10 \n"; xecute("for s=1:1:10 write s,!",s); cout &lt;&lt; "s after loop: " &lt;&lt; s &lt;&lt; endl; //================================================================== // All indices and data must be character strings for "df" // based on the way it was declared. The following creates // a two dimensional array and then retrieves the results: kill (df()); for (i=0; i&lt;10; i++) { char s[12]; ltoa(s,i); df(s)=s; } for (i=0; i&lt;10; i++) { char s[12]; ltoa(s,i); cout &lt;&lt; df(s) &lt;&lt; " "; } cout &lt;&lt; endl; //================================================================== // $order() (forwards) - two forms - both return the next value // of the last subscript or the empty string. Note that the // initial value if you want the first subscript must be the // empty string. strcpy(s,""); cout &lt;&lt; "order forwards: expect 0: " &lt;&lt; $order(df(s),1) &lt;&lt; endl; cout &lt;&lt; "order forwards: expect 0: " &lt;&lt; df(s).Order(1) &lt;&lt; endl; cout &lt;&lt; "forwards thru an array\n"; strcpy(s,""); while(1) { strcpy(s, $order(df(s),1)); // forwards if (!$test) break; cout &lt;&lt; "s = " &lt;&lt; s &lt;&lt; endl; } cout &lt;&lt; "forwards thru an array\n"; strcpy(s,""); while(1) { strcpy(s, df(s).Order(1)); // forwards if (!$test) break; cout &lt;&lt; "s = " &lt;&lt; s &lt;&lt; endl; } //================================================================== // $order() (prior) - multiple forms: cout &lt;&lt; "next thru array\n"; strcpy(s,""); while(1) { strcpy(s, $order(df(s),1) ); // forwards if (!$test) break; cout &lt;&lt; "s = " &lt;&lt; s &lt;&lt; endl; } cout &lt;&lt; "prior thru array\n"; strcpy(s,""); while(1) { strcpy(s, $order(df(s),-1) ); // backwards if (!$test) break; cout &lt;&lt; "s = " &lt;&lt; s &lt;&lt; endl; } //================================================================== // Merge command. The following copies "abc()" to "ABC()": ABC().Merge(abc()); cout &lt;&lt; "merged output\n"; for (i=1; i&lt;10; i++) for ( long j=1; j&lt;10; j++) { string s1=cvt(i); string s2=cvt(j); cout &lt;&lt; i &lt;&lt; " " &lt;&lt; j &lt;&lt; " " &lt;&lt; ABC(s1,s2) &lt;&lt; endl; } //================================================================== // Lock command. CleanAllLocks(); // remove all locks abc("1","2","3").Lock(); // locks abc(1,2,3) and descendants cout &lt;&lt; "After lock expect 1 " &lt;&lt; $test &lt;&lt; endl; abc("1","2","3").Lock(); // will fail because lock exists cout &lt;&lt; "After lock expect 0 " &lt;&lt; $test &lt;&lt; endl; abc("1","2","3").UnLock(); // releases this lock cout &lt;&lt; "test after unlock expect 1 " &lt;&lt; $test &lt;&lt; endl; abc("1","2","3").Lock(); // now will succeed cout &lt;&lt; "After lock expect 1 " &lt;&lt; $test &lt;&lt; endl; CleanLocks(); // remove all locks for this job cout &lt;&lt; "encode html " &lt;&lt; EncodeHTML("abc def ( 1 + 2 )") &lt;&lt; endl; GlobalClose; // close Mumps Globals - required return 1; } }

Appendix B

Perl Compatible Regular Expression Library License

Programs written with the MDH may call upon the Perl Compatible Regular Expression Library. In some cases, this library is distributed with the Mumps Compiler. The PCRE Library is not covered by the GNU GPL/LGPL Licenses but, rather, by the license shownn below. The following is the PCRE license:

PCRE LICENCE
------------
PCRE is a library of functions to support regular expressions whose syntax
and semantics are as close as possible to those of the Perl 5 language.
Written by: Philip Hazel 
University of Cambridge Computing Service,
Cambridge, England. Phone: +44 1223 334714.
Copyright (c) 1997-2001 University of Cambridge
Permission is granted to anyone to use this software for any purpose on any
computer system, and to redistribute it freely, subject to the following
restrictions:
1. This software is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
2. The origin of this software must not be misrepresented, either by
   explicit claim or by omission. In practice, this means that if you use
   PCRE in software which you distribute to others, commercially or
   otherwise, you must put a sentence like this
     Regular expression support is provided by the PCRE library package,
     which is open source software, written by Philip Hazel, and copyright
     by the University of Cambridge, England.
   somewhere reasonably visible in your documentation and in any relevant
   files or online help data or similar. A reference to the ftp site for
   the source, that is, to
     ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/
   should also be given in the documentation.
3. Altered versions must be plainly marked as such, and must not be
   misrepresented as being the original software.
4. If PCRE is embedded in any software that is released under the GNU
   General Purpose Licence (GPL), or Lesser General Purpose Licence (LGPL),
   then the terms of that licence shall supersede any condition above with
   which it is incompatible.
The documentation for PCRE, supplied in the "doc" directory, is distributed
under the same terms as the software itself.
End

Appendix C

Using Perl Regular Expressions
Author: Matthew Lockner

In addition to Mumps 95 pattern matching using the '?' operator, it is also possible to perform pattern matching against Perl regular expressions via the perlmatch function. Support for this functionality is provided by the Perl-Compatible Regular Expressions library (PCRE), which supports a majority of the functionality found in Perl's regular expression engine.

The perlmatch function works in a somewhat similar fashion to the '?' operator. It is provided with a subject string and a Perl pattern against which to match the subject. The result of the function is boolean and may be used in boolean expression contexts such as the "If" statement.

Some subtleties that differ significantly from Mumps pattern matching should be noted:

1. A Mumps match expects that the pattern will match against the entire subject string, in that successful matching implies that no characters are left unmatched even if the pattern matched against an initial segment of the subject string. Using perlmatch, it is sufficient that the entire Perl pattern matches an initial segment of the subject string to return a successful match.

2. The perlmatch function has the side effect of creating variables in the local symbol table to hold backreferences, the equivalent concept of $1, $2, $3, ... in Perl. Up to nine backreferences are currently supported, and can be accessed through the same naming scheme as Perl ($1 through $9). These variables remain defined up to a subsequent call to perlmatch , at which point they are replaced by the backreferences captured from that invocation. Undefined backreferences are cleared between invocations; that is, if a match operation captured five backreferences, then $6 through $9 will contain the null string.

Examples

This program asks the user to input a telephone number. If the data entered looks like a valid telephone number, it extracts and prints the area code portion using a backreference; otherwise, it prints a failure message and exits.

   Zmain
   Write "Please enter a telephone number:",!
   Read phonenum
   If $$^perlmatch(phonenum,"^(1-)?(\(?\d{3}\)?)?(-| )?\d{3}-?\d{4}$") Do
   . Write "+++ This looks like a phone number.",!
   . Write "The area code is: ",$2,!
   Else  Do
   . Write "--- This didn't look like a phone number.",!
   Halt

The output of several sample runs of the program follows:

Please enter a telephone number:
1-123-555-4567
+++ This looks like a phone number.
The area code is: 123
Please enter a telephone number:
(123)-555-1234
+++ This looks like a phone number.
The area code is: (123)
Please enter a telephone number:
(123) 555-0987
+++ This looks like a phone number.
The area code is: (123)

As in Perl, sections of the regular expression contained in parentheses define what is contained in the backreferences following a match operation. The backreference variables are named in a left-to-right order with respect to the expression, meaning that $1 is assigned the portion matched against the leftmost parenthesized section of the regular expression, with further references assigned names in increasing order. For a much more in-depth treatment of the subject of Perl regular expressions, refer to the perlre manpage distributed with the Perl language (also widely available online).

Appendix E

Mumps 95 Pattern Matching
Author: Matthew Lockner

Mumps 95 compliant pattern matching (the '?' operator) is implemented in this compiler as given by the following grammar:

 pattern         ::= {pattern_atom}
 pattern_atom    ::= count pattern_element
 count           ::= int | '.' | '.' int
                   | int '.' | int '.' int
 pattern_element ::= pattern_code {pattern_code} | string | alternation
 pattern_code    ::= 'A' | 'C' | 'E' | 'L' | 'N' | 'P' | 'U'
 alternation     ::= '(' pattern_atom {',' pattern_atom} ')'

The largest difference between the current and previous standard is the introduction of the alternation construct, an extension that works as in other popular regular expressions implementations. It allows for one of many possible pattern fragments to match a given portion of subject text.

A string literal must be quoted. Also note that alternations are only allowed to contain pattern atoms and not full patterns; while this is a possible shortcoming, it is in accordance with the standard. It is a trivial matter to extend alternations to the ability to contain full patterns, and this may be implemented upon sufficient demand.

Pattern matching is supported by the Perl-Compatible Regular Expressions library (PCRE). Mumps patterns are translated via a recursive-descent parser in the Mumps library into a form consistent with Perl regular expressions, where PCRE then does the actual work of matching. Internally, much of this translation is simple character-level transliteration (substituting '|' for the comma in alternation lists, for example). Pattern code sequences are supported using the POSIX character classes supported in PCRE and are mostly intuitive, with the possible exception of 'E', which is substituted with [[:print][:cntrl:]]. Currently, this construct should cover the ASCII 7-bit character set (lower ASCII).

Due to the heavy string-handling requirements of the pattern translation process, this module uses a separate set of string-handling functions built on top of the C standard string functions, using no dynamic memory allocation and fixed-length buffers for all operations whose length is given by the constant STR_MAX in sysparms.h. If an operation overflows during the execution of a Mumps compiled binary, a diagnostic is output to stderr and the program terminates. If such termination occurs too frequently, simpl