# CHAPTER 4: Manual Pages

This chapter provides the manual pages for the utilities and the mx routines. The utility manual pages can also be found in the `$EMPRESSPATH/man` directory and can be printed using the command:

- For UNIX, using `nroff -man filename`.

- For Windows, using `type` or `more` command.

The following is the list of manual pages for the utilities:

  Category | Sub-Category | Command
  C/C++ API |  | `empc++`
  |  | `empcc (UNIX)`

The following is the list of manual pages for the mx routines in alphabetical order:

  msclean | msend | msexit
  msexitcleanup | msinit |
  mxaclose | mxadd |
  mxchkattr | mxclose | mxcompare
  mxcopyi |  |
  mxdel |  |
  mxget | mxgetbegin | mxgetend
  mxgetvi | mxgetvs |
  mxigeta |  |
  mxopen |  |
  mxprev | mxput | mxputi
  mxputvi | mxputvs |
  mxqand | mxqatr | mxqcon
  mxqconi | mxqieq | mxqmch
  mxqnot | mxqnul | mxqor
  mxqrng | mxqrngi | mxqseq
  mxreget | mxreprev |
  mxsetnull | mxsrtbegin |
  mxtrcancel | mxtrcommit | mxtrrollback
  mxtrsave | mxtrstart |

# msclean

DESCRIPTION | Place a named procedure on the stack to be called by `msexit` and executed immediately before the program is terminated. The procedure passed to `msclean` is the last but one called by `msexit`.
SYNOPSIS |
    void   msclean (void (* proc) (void))
USAGE | `msclean (proc ());`
`proc` | The procedure to be called
RETURNS | None.
WARNINGS | Please note that this routine will become obsolete and be replaced in the near future with the mutli-threading capability. This routine is not thread-safe and should not be used inside threads.

# msend

DESCRIPTION | This routine call the cleanup procedures without terminating the program.
SYNOPSIS |
    void   msend (void)
USAGE | `msend ();`
RETURNS | None.
WARNINGS | This routine is not thread-safe and should not be used inside threads.

# msexit

DESCRIPTION | This routine calls `msexitcleanup` before terminating the program. It passes a value to the shell.
SYNOPSIS |
    void   msexit (int value)
USAGE | `msexit (value);`
`value` | Integer value passed to the shell.
RETURNS | None.
WARNINGS | The last procedure called by `msexit` checks to see if all user procedure space is freed; if not, a warning message about space allocated is printed.

# msexitcleanup

DESCRIPTION | This routine executes all the clenup procedures without terminating the program.
SYNOPSIS |
    void msexitcleanup (void)
USAGE |
    msexitcleanup ();
RETURNS | None.
WARNINGS | None.

# msinit

DESCRIPTION | Initialize for `mscall`, mx and mr routines.
SYNOPSIS |
    msbool   msinit (void)
USAGE |
    flag = msinit ();
RETURNS | Return false if `msinit` has been called; true otherwise.
WARNINGS | None.

# mxaclose

DESCRIPTION | Close all tables and de-allocate all existing mx-related variables. This procedure should be used before terminating a program due to an error condition or a trapped interrupt.
SYNOPSIS |
    void   mxaclose (void)
USAGE |
    mxaclose ();
RETURNS | None.
WARNINGS | Indiscriminate use of this procedure defeats all the built-in error checking mechanisms of the mx routines.

# mxadd

DESCRIPTION | Insert a record into a given table. The record should have been constructed using `mxputv`.
SYNOPSIS |
    msbool   mxadd (char* table)
USAGE |
    flag = mxadd (table);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`table` | The name of the table
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The table must be opened in update mode or the insert will fail.

# mxchkattr

DESCRIPTION | Check whether a particular attribute is in an opened table.
SYNOPSIS |
    msbool   mxchkattr (char* attribute)
USAGE |
    flag = mxchkattr (attribute);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute being checked.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | If the same attribute name appears in more than one opened table, the attribute name must be qualified with the table name (and database name if necessary) to ensure that the correct attribute is checked for.

# mxclose

DESCRIPTION | Close a table after all operations have been performed on it.
SYNOPSIS |
    msbool   mxclose (char* table)
USAGE |
    mxclose (table);
`table` | The name of a table.
RETURNS | True if table is currently opened and false otherwise.
WARNINGS | None.

# mxcompare

DESCRIPTION | Find whether a constant is equal to, less than, or greater than an attribute value.
SYNOPSIS |
    int   mxcompare (char* attribute, char* value)
USAGE |
    result = mxcompare (attribute, value);
`result` | Integer result of the comparison.
`attribute` | The name of an attribute.
`value` | The constant the attribute is to be compared with, in external comparison.
RETURNS | Zero if the constant is equal to the attribute value, 1 if the attribute value is greater than the constant, and -1 if the attribute value is less than the constant. If an error occurs (due to incompatible data types) an error message is printed and the calling program terminated.
WARNINGS | None.

# mxcopyi

DESCRIPTION | Copy the internal representation of an attribute value to a variable.
SYNOPSIS |
    msbool   mxcopyi (char* attribute, addr var_ptr)
USAGE |
    flag = mxcopyi (attribute, &var);
`flag` | Indicator (`msbool`) to show whether the value is `NULL`.
`attribute` | The name of the attribute.
`var` | A variable of suitable type for storing the internal representation of the attribute value.
RETURNS | Returns true (1) if the value is not `NULL`, false (0) if it is.
WARNINGS | Using this routine results in non-portable code.

# mxdel

DESCRIPTION | Delete a record from a table.
SYNOPSIS |
    msbool   mxdel (char* table)
USAGE |
    flag = mxdel (table);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`table` | The name of a table.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The record to be deleted must first have been specified in a call to `mxgetbegin` and then retrieved by a successful call to `mxget`.

# mxget

DESCRIPTION | Retrieve a record from a table; successive calls retrieve different records.
SYNOPSIS |
    int   mxget (void)
USAGE |
    flag = mxget ();
`flag` | Indicator (`int`) to show success or failure of the routine
RETURNS | True (1) if successful; false (0) if all records have been retrieved. If the record is locked and `mxerret` is set, it returns -1; if the record is locked and `mxerret` is not set, it prints an error message and terminates the calling program.
WARNINGS | `mxgetbegin` must be called once before any calls to `mxget` are made. `mxgetend` must be called after one or more calls to `mxget` to do cleaning up.

# mxgetbegin

DESCRIPTION | Associate a given qualification with one or more records.
SYNOPSIS |
    msbool   mxgetbegin (char* table_1, [ ..., char* table_n,] (char*)0)
USAGE |
    flag = mxgetbegin (table_1, table_2, ... , CHARNIL);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`table_1` | The name of an opened table.
`table_2` | The name of an opened table.
`CHARNIL` | `(char*)0` as defined in the header file `mscc.h`.
RETURNS | True (1) if successful; false (0) if it is unable to access all appropriate records and `mxerret` is set. If it cannot access all appropriate records and `mxerret` is not set, it prints an error message and terminates the calling program.
WARNINGS | Nested calls to `mxgetbegin` must be set up carefully.

# mxgetend

DESCRIPTION | Clean up after retrieving records from a table.
SYNOPSIS |
    void   mxgetend (void)
USAGE |
    mxgetend ();
RETURNS | None.
WARNINGS | Failure to call `mxgetend` after retrieving records may affect future record retrievals.

# mxgetvi

DESCRIPTION | Retrieve an attribute value as an integer; terminate the calling program on failure.
SYNOPSIS |
    int   mxgetvi (char* attribute)
USAGE |
    value = mxgetvi (attribute);
`value` | Integer containing the value returned.
`attribute` | The name of an attribute.
RETURNS | The attribute value as an integer. If the value cannot be converted to an integer, an error message is printed and the calling program terminated.
WARNINGS | None.

# mxgetvs

DESCRIPTION | Retrieve an external format attribute value.
SYNOPSIS |
    char*   mxgetvs (char* attribute)
USAGE |
    value = mxgetvs (attribute);
`value` | Pointer `(char *)` to the value returned.
`attribute` | The name of the attribute.
RETURNS | A pointer (`char *`) to an attribute value; a pointer to a null string if the value is `NULL`.
WARNINGS | The value found by `mxgetvs` should be used immediately, since the next call to `mxgetvs`, `mxputvs` or `mxputvi` for the same attribute re-uses the buffer it is placed in.

# mxigeta

DESCRIPTION | Find the name of an attribute given its number in a table.
SYNOPSIS |
    char*   mxigeta (char* table, int number)
USAGE |
    name = mxigeta (table, number);
`name` | The name of the attribute `(char*)`.
`table` | The name of the table.
`number` | The number of the attribute in the table.
RETURNS | The name of the attribute; `CHARNIL` if unsuccessful.
WARNINGS | None.

# mxopen

DESCRIPTION | Open and lock a table for use with the mx routines.
SYNOPSIS |
    msbool   mxopen (char* database, char* table, char* mode)
USAGE |
    flag = mxopen (database, table, mode);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`database` | The name of the database directory.
`table` | The name of the table.
`mode` | The string "`r`", "`u`", "`d`", "`n`" or "`N`" for read, update, deferred, dirty read or deferred dirty read, respectively. The dirty read mode will retrieve records bypass all locking (Refer to Empress: Database Administrator's Guide). The deferred mode opens the table for update but places a read lock when data is retrieved; this read lock is replaced with an update lock when an `mxdel` or `mxput` is executed.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | It is generally unwise to specify the current directory when calling `mxopen` (i.e., you should not run applications in the database directory), because of the danger of damaging files in the database when new files are created. If read mode is specified and the person executing the program has no read permission on the table, or if update mode is specified and the person executing the program does not have read and write permission on the table, `mxopen` will fail.

# mxprev

DESCRIPTION | Retrieve the previous record from a table; successive calls retrieve different records.
SYNOPSIS |
    int   mxprev (void)
USAGE |
    flag = mxprev ();
`flag` | Indicator (`int`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if all records have been retrieved. If the record is locked and `mxerret` is set, it returns -1; if the record is locked and `mxerret` is not set, it prints an error message and terminates the calling program.
WARNINGS | `mxgetbegin` must be called once before any calls to `mxprev` are made. `mxgetend` must be called after one or more calls to `mxprev` to do cleaning up.

# mxput

DESCRIPTION | Update a record.
SYNOPSIS |
    msbool   mxput (char* table)
USAGE |
    flag = mxput (table);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`table` | The name of the table
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The record to be replaced must be first obtained by calls to `mxgetbegin` and `mxget`, otherwise `mxput` will fail.

# mxputi

DESCRIPTION | Assign an internal format value to an attribute.
SYNOPSIS |
    msbool   mxputi (char* attribute, addr var_ptr)
USAGE |
    flag = mxputi (attribute, &var_ptr);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute.
`var` | A variable containing a value in Empress internal format to be assigned to the attribute, or `ADDRNIL` (defined in the header file `mscc.h`) for a `NULL` value.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | Use of this routine results in non-portable code. The pointer must point to a variable compatible with the Empress internal representation of the attribute in question or a conversion error will result.

# mxputvi

DESCRIPTION | Assign an integer value to an attribute.
SYNOPSIS |
    msbool   mxputvi (char* attribute, int value)
USAGE |
    flag = mxputvi (attribute, value);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute.
`value` | An integer to be assigned to the attribute.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | None.

# mxputvs

DESCRIPTION | Assign an external format value to an attribute.
SYNOPSIS |
    msbool   mxputvs (char* attribute, char* value)
USAGE |
    flag = mxputvs (attribute, value);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute.
`value` | An external-format value `(char*)` to be assigned to the attribute.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | None.

# mxqand

DESCRIPTION | Perform an `AND` operation on the top two values of the stack holding qualifications created by calls to the `mxq` routines.
SYNOPSIS |
    void   mxqand (void)
USAGE |
    mxqand ();
RETURNS | None.
WARNINGS | There must be at least two qualifications on the stack or `mxqand` will fail, print an error message, and terminate the calling program.

# mxqatr

DESCRIPTION | Compare an attribute value to another attribute value and store the result on a stack.
SYNOPSIS |
    msbool   mxqatr (char* operator, char* attr_1, char* attr_2)
USAGE |
    flag = mxqatr (operator, attr_1, attr_2);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`operator` | One of the following: "`>`", "`<`", "`>=`", "`<=`", "`=`", or "`!=`". for negation, either tilde (~) or exclamation mark (!) may be used.
`attr_1` | The name of the first attribute.
`attr_2` | The name of the second attribute.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The two attributes compared must be compatible, otherwise `mxqatr` will fail.

# mxqcon

DESCRIPTION | Compare an attribute value to an external format constant and store the result on a stack.
SYNOPSIS |
    msbool   mxqcon (char* operator, char* attribute, char* string)
USAGE |
    flag = mxqcon (operator, attribute, string);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`operator` | One of the following: "`>`", "`<`", "`>=`", "`=`", or "`!=`".
`attribute` | The name of the attribute.
`string` | The value the attribute is to be compared to, in external format `(char *)`.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The routine will fail and print a "Conversion Error'' message if the attribute and value are not compatible.

# mxqconi

DESCRIPTION | Compare an attribute value to an internal format constant and store the result on a stack.
SYNOPSIS |
    msbool   mxqconi (char* operator, char* attribute, addr var_ptr)
USAGE |
    flag = mxqconi (operator, attribute, &var);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`operator` | One of the following: "`>`", "`<`", "`>=`", "`<=`", "`=`", or "`!=`".
`attribute` | The name of the attribute.
`var` | A variable containing the value the attribute is to be compared to, in internal format.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | Using this routine results in non-portable code. The routine will fail and print "Conversion Error'' message if the attribute and value are not compatible.

# mxqieq

DESCRIPTION | Compare an integer to an attribute value and store the result on a stack.
SYNOPSIS |
    void   mxqieq  (char* attribute, int integer)
USAGE |
    mxqieq (attribute, integer);
`attribute` | The name of the attribute.
`integer` | An integer value.
RETURNS | None.
WARNINGS | If the attribute and the integer cannot be compared, the routine will fail and terminate the calling program.

# mxqmch

DESCRIPTION | Compare an attribute value to a pattern, and store the result on a stack.
SYNOPSIS |
    msbool   mxqmch (char* operator, char* attribute, char* pattern)
USAGE |
    flag = mxqmch (operator, attribute, pattern);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`operator` | One of the following: `MATCH`, `SMATCH`, `!MATCH`, or `!SMATCH`. For negation, either tilde (~) or exclamation mark (!) may be used.
`attribute` | The name of the attribute.
`pattern` | Pointer `(char *)` to a pattern.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | If the arguments are incompatible the routine will fail.

# mxqnot

DESCRIPTION | Reverse the sense of the qualification on the top of the stack.
SYNOPSIS |
    void   mxqnot (void);
USAGE |
    mxqnot ();
RETURNS | None.
WARNINGS | There must be at least one qualification on the stack or the routine will fail, print an error message, and terminate the calling program.

# mxqnul

DESCRIPTION | Compare an attribute value to `NULL`, and store the result on a stack.
SYNOPSIS |
    msbool   mxqnul (char* operator, char* attribute)
USAGE |
    flag = mxqnul (operator, attribute);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute.
`operator` | One of "`=`" or "`!=`". For negation, either tilde (~) or exclamation mark (!) may be used.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | Routine will fail if the arguments are inappropriate.

# mxqor

DESCRIPTION | Perform an `OR` operation on the top two elements of the stack holding qualifications created by the `mxq` routines.
SYNOPSIS |
    void   mxqor (void)
USAGE |
    mxqor ();
RETURNS | None.
WARNINGS | There must be at least two qualifications on the stack or `mxqor` will fail, print an error message, and terminate the calling program.

# mxqrng

DESCRIPTION | Compare an attribute value to a given range of values in external format.
SYNOPSIS |
    msbool   mxqrng (char* attribute, char* lower_limit, char* limit_type_1,
                     char* upper_limit, char* limit_type_2)
USAGE |
    flag = mxqrng (attribute, lower_limit, limit_type_1,
                   upper_limit, limit_type_2);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute.
`lower_limit` | The lower limit of the range in external format.
`limit_type_1` | The string "`i`" or "`e`", indicating that the lower limit is inclusive or exclusive, respectively.
`upper_limit` | The upper limit of the range in external format.
`limit_type_2` | The string "`i`" or "`e`", indicating that the upper limit is inclusive or exclusive, respectively
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The program will fail if the arguments are incompatible.

# mxqrngi

DESCRIPTION | Compare an attribute value to a given range of values in internal format.
SYNOPSIS |
    msbool   mxqrngi (char* attribute, addr lower_ptr, char* limit_type_1,
                      addr upper_ptr, char* limit_type_2)
USAGE |
    flag = mxqrngi (attribute, &lower, limit_type_1,
                    &upper, limit_type_2);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attribute` | The name of the attribute.
`lower` | The lower limit of the range in internal format.
`limit_type_1` | The string "`i`" or "`e`", indicating that the lower limit is inclusive or exclusive, respectively.
`upper` | The upper limit of the range in internal format.
`limit_type_2` | The string "`i`" or "`e`", indicating that the upper limit is inclusive or exclusive, respectively.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | The routine will fail if the arguments are incompatible. Using this routine results in non-portable code.

# mxqseq

DESCRIPTION | Compare an attribute with a string.
SYNOPSIS |
    void   mxqseq (char* attribute, char* string)
USAGE |
    mxqseq (attribute, string);
`attribute` | The name of the attribute.
`string` | The string to which the attribute is compared.
RETURNS | None.
WARNINGS | If the attribute and the string are not compatible (e.g., the attribute is a numeric data type and the string contains letters), the routine will fail, print an error message, and terminate the calling program.

# mxreget

DESCRIPTION | Retrieve a record from a table when a prior call with `mxget` failed; successive calls to `mxreget` all attempt to retrieve the same record.
SYNOPSIS |
    int   mxreget (void)
USAGE |
    flag = mxreget ();
`flag` | Indicator (`int`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if all records have been retrieved. If the record is locked and `mxerret` is set, it returns -1; if the record is locked and `mxerret` is not set, it prints an error message and terminates the calling program.
WARNINGS | `mxgetbegin` must be called once before any calls to `mxreget` are made. `mxgetend` must be called after one or more calls to `mxreget` to do cleaning up.

# mxreprev

DESCRIPTION | Retrieve the previous record from a table when a prior call with `mxprev` failed; successive calls to `mxreprev` all attempt to retrieve the same record.
SYNOPSIS |
    int   mxreprev (void)
USAGE |
    flag = mxreprev ();
`flag` | Indicator (`int`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if all records have been retrieved. If the record is locked and `mxerret` is set, it returns -1; if the record is locked and `mxerret` is not set, it prints an error message and terminates the calling program.
WARNINGS | `mxgetbegin` must be called once before any calls to `mxreprev` are made. `mxgetend` must be called after one or more calls to `mxreprev` to do cleaning up.

# mxsetnull

DESCRIPTION | Assign a `NULL` value to all attributes in a record.
SYNOPSIS |
    void   mxsetnull (char* table)
USAGE |
    mxsetnull (table);
`table` | The name of an opened table.
RETURNS | None.
WARNINGS | None.

# mxsrtbegin

DESCRIPTION | Associate a given qualification with one or more records, and indicate how retrieved values should be sorted.
SYNOPSIS |
    msbool   mxsrtbegin (char* indicator,
                         char* table_1, [ ... char* table_n,] (char*)0,
                         char* attr_1, char* type,
                         [char* attr_2, char* type, ...] (char*)0)
USAGE |
    flag = mxsrtbegin (indicator, table_1, table_2, ... , CHARNIL,
                       attr_1, type, attr_2, type, ... , CHARNIL);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`indicator` | The string "`u`" or "`s`", to denote a unique or non-unique sort, respectively. for a unique sort, the records will be unique only on the attributes listed; the order of records where unlisted attributes are duplicated is not determined.
`table_1` | The name of an opened table.
`table_2` | The name of an opened table.
`CHARNIL` | `(char*)0` as defined in the header file `mscc.h`.
`attr_1` | The name of an attribute to be sorted on.
`type` | The string "`ascending`" or "`descending`", denoting the sort type for the preceding attribute. "`Ascending`" and "`descending`" may be abbreviated to "`a`"and "`d`", respectively.
`attr_2` | The name of an attribute to be sorted on.
RETURNS | True (1) if successful; false (0) if unsuccessful and `mxerret` is set; if unsuccessful and `mxerret` is not set, an error message is printed and the calling program terminated.
WARNINGS | Nested calls to `mxsrtbegin` must be set up carefully.

# mxtrcancel

DESCRIPTION | Cancel a transaction; return database to pre-transaction state.
SYNOPSIS |
    msbool   mxtrcancel (void)
USAGE |
    flag = mxtrcancel ();
`flag` | Indicator (`msbool`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if not.
WARNINGS | Do not cancel a transaction in the middle of a retrieval loop (i.e., between calls to `mxgetbegin` and `mxgetend`) unpredictable results will ensue.

# mxtrcommit

DESCRIPTION | Commit a transaction making all changes permanent.
SYNOPSIS |
    msbool   mxtrcommit (void)
USAGE |
    flag = mxtrcommit ();
`flag` | Indicator (`msbool`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if not.
WARNINGS | Do not commit a transaction in the middle of a retrieval loop (i.e., between calls to `mxgetbegin` and `mxgetend`) unpredictable results will ensue.

# mxtrrollback

DESCRIPTION | Roll back the transaction to the save point.
SYNOPSIS |
    msbool   mxtrrollback (char* savepoint)
USAGE |
    flag = mxtrrollback (savepoint);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`savepoint` | Pointer `(char*)` to the name of the save point. The name must be a string starting with a letter. If the save point is `CHARNIL` ("") this is equivalent to an `mxtrcancel`.
RETURNS | True (1) if successful; false (0) if unsuccessful.
WARNINGS | A transaction must be in progress and the save point must be set.

# mxtrsave

DESCRIPTION | Set a save point in the transaction.
SYNOPSIS |
    msbool   mxtrsave (char* savepoint)
USAGE | `flag = mxtrsave (savepoint);`
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`savepoint` | Pointer `(char*)` to the name of the save point. The name must be a string starting with a letter.
RETURNS | True (1) if successful; false (0) if unsuccessful.
WARNINGS | A transaction must be in progress.

# mxtrstart

DESCRIPTION | Start a transaction.
SYNOPSIS |
    msbool   mxtrstart (void)
USAGE |
    flag = mxtrstart ();
`flag` | Indicator (`msbool`) to show success of failure of the routine.
RETURNS | True (1) if successful; false (0) if not. Failure usually means a transaction is already in progress.
WARNINGS | Do not start a transaction in the middle of a retrieval loop (i.e., between calls to `mxgetbegin` and `mxgetend`) - unpredictable effects will ensue.