# CHAPTER 4: Manual Pages

This chapter provides the manual pages for the utilities and the mr 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 mr routines in alphabetical order:

  msclean | msdtfsta | msend
  msexit | msexitcleanup | msinit
  mspsm_free | mspsm_malloc | mspsm_realloc
  mspsm_trig_abort_operation | mspsm_trig_get_record_info |  |
  mradd | mraddend |
  mrbuktxtcrt | mrbuktxtlen |
  mrcldict | mrclose | mrcompare
  mrcontrol | mrcopyi | mrcopyr
  mrcopyv | mrcvt | mrcvti
  mrcvti2 | mrcvtin | mrcvtv
  mrcvtv2 |  |
  mrdel | mrdelend |
  mreabort | mrebegin | mrecons
  mrecvarg | mreend | mrefree
  mrefunc | mreicvar | mreivar
  mrenull | mrerecattr | mrerrmsg
  mrerun |  |
  mrfree | mrfrrec |
  mrganame | mrgdtpar | mrget
  mrgetbegin | mrgetend | mrgeti
  mrgetptr | mrgetrec | mrgetvi
  mrgetvs | mrgfunc |
  mrigeta |  |
  mrlkrec | mrlktab |
  mrmalloc | mrmkrec | mrmptvi
  mrmptvs | mrmutexlock | mrmutexunlock
  mrngeta | mrnullr | mrnullv
  mropdict | mropen |
  mrprev | mrprterr | mrput
  mrputi | mrputvi | mrputvs
  mrqand | mrqatr | mrqcon
  mrqdb | mrqexpr | mrqieq
  mrqlst | mrqmch | mrqnot
  mrqnul | mrqor | mrqrng
  mrqseq |  |
  mrrealloc | mrreget | mrreprev |
  mrsetnr | mrsetnv | mrspv
  mrsrtbegin | mrsubbegin | mrsubend
  mrsubgeti | mrsubputi |
  mrtadd | mrtdel | mrtget
  mrtgfunc | mrtgtbegin | mrtopdict
  mrtopen | mrtprev | mrtput
  mrtqatr | mrtqcon | mrtqmch
  mrtqnul | mrtqrng | mrtrcancel
  mrtrcommit | mrtrrollback | mrtrsave
  mrtrstart | mrtsrbegin |
  mrulrec | mrultab |
  mrsetstmtoption |  |

# 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 multi-threading capability. This routine is not thread-safe and should not be used inside threads.

# msdtfsta

DESCRIPTION | This routine is used to improve the performance of inserts and updates into `TEXT`, `NLSTEXT` and `BULK` attributes.
SYNOPSIS |
    void   msdtfsta (msbool enable)
USAGE |
    msdtfsta (enable);
`enable` | If the value is `true`, the insert or update will be done directly from the internal Empress buffers to the database files, without the immediate use of a disk file. If the value is `false`, a temporary disk file will be used for storing the overflow data.
RETURNS | None.
WARNINGS | Please note that if you are using `msdtfsta` you must guarantee that the buffer used to convey the bulk or text data is static or unaltered until `mradd` or `mrput` is called by the program. This routine is intended to be used only with programming language (mx, mr, Precompiler) in Empress. It should not be used with any Data Definition Language (DDL) command such as `CREATE TABLE`, `ALTER TABLE`, etc. As a result these program must not use any `mscall`routine which executes a DDL statement.

# msend

DESCRIPTION | This routine call the cleanup procedures without terminating the program.
SYNOPSIS |
    void   msend (void)
USAGE | `msend ();`
RETURNS | None.
WARNINGS | None.

# 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. This routine is not thread-safe and should not be used inside threads.

# msexitcleanup

DESCRIPTION | This routine call the cleanup 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 |
    msinit ();
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mspsm_free

DESCRIPTION | Free the space allocated by mspsm_malloc.
SYNOPSIS |
    void   mspsm_free (char* space)
USAGE |
    mspsm_free (space);
`space` | Pointer (char*) returned by `mspsm_malloc`.
RETURNS | None.
WARNINGS | This routine should be used only in Persistent Stored Modules (PSM). This routine is not thread-safe and should not be used inside threads.

# mspsm_malloc

DESCRIPTION | Allocate space for storing data in Persistent Stored Modules (PSM).
SYNOPSIS |
    void*   mspsm_malloc (int size)
USAGE |
    space = mspsm_malloc (size);
`space` | Pointer (void*) to space allocated for storage used in Persistent Stored Module (PSM).
`size` | Integer (int) that defines a size of allocated space.
RETURNS | Pointer (void*) to space allocated for storage used in Persistent Stored Module (PSM).
WARNINGS | The space will remain allocated until freed internally by Empress RDBMS. If there is a need to free the space inside the PSM, Empress routine `mspsm_free` should be used. This routine is not thread-safe and should not be used inside threads.

# mspsm_realloc

DESCRIPTION | Changes the size of the space allocated by `mspsm_malloc`.
SYNOPSIS |
    void*   mspsm_realloc (void* space, int size)
USAGE |
    realloc_space = mspsm_realloc (space, size);
`realloc_space` | Pointer (void*) to space allocated for storage used in Persistent Stored Module (PSM).
`space` | Pointer (void*) to space previously allocated for storage used in Persistent Stored Module (PSM).
`size` | Integer (`int`) that defines a size of allocated space.
RETURNS | Pointer (void*) to space allocated for storage used in Persistent Stored Module (PSM).
WARNINGS | The space will remain allocated until freed internally by Empress RDBMS. This routine is not thread-safe and should not be used inside threads.

# mspsm_trig_abort_operation

DESCRIPTION | This routine is used in trigger procedure to abort the corresponding operation.
SYNOPSIS |
    void   mspsm_trig_abort_operation (void)
USAGE |
    mspsm_trig_abort_operation ();
RETURNS | None.
WARNINGS | The operation will be aborted only if the trigger is fired before the operation. This routine is not thread-safe and should not be used inside threads.

# mspsm_trig_get_record_info

DESCRIPTION | This routine is used to get the table descriptor and the record descriptor in a trigger procedure.
SYNOPSIS |
    void   mspsm_trig_get_record_info (void** pmr,
                                   void** poldrec,
                                   void** pnewrec)
| USAGE |
    mspsm_trig_get_record_info (pmr, poldrec, pnewrec);
`pmr` | Indirect pointer to table descriptor.
`poldrec` | Indirect pointer to old record descriptor (the record before operation).
`pnewrec` | Indirect pointer to new record descriptor (the record after operation).
RETURNS | None.
WARNINGS | The space for descriptors is allocated and deallocated by the system. The trigger that is invoking this routine must be a row trigger, i.e. it must be defined with `FOR EACH ROW` option. Refer to definition of CREATE TRIGGER in Manual A4: Empress SQL Reference for explanation on this option. The validity of `poldrec` and `pnewrec` depends on the type of the trigger. for `UPDATE` triggers, you can refer to old (existing) record `poldrec`, and new record `pnewrec`. for `INSERT` triggers, you can only refer to new record. The value of old record is not meaningful. for `BEFORE DELETE` triggers, you can only refer to old record. The value of the new record is not meaningful. for `AFTER DELETE` triggers, the value of neither the old record nor the new record is meaningful. This routine is not thread-safe and should not be used inside threads.

# mradd

DESCRIPTION | Insert a record into a given table; terminate calling program on failure.
SYNOPSIS |
    void   mradd (addr record_desc)
USAGE |
    mradd (record_desc);
RETURNS | None.
WARNINGS | `mraddend` should be called to clean up after one or more calls to `mradd`.

# mraddend

DESCRIPTION | End a group of insertions.
SYNOPSIS |
    msbool	mraddend (addr record_desc)
USAGE |
    flag = mraddend (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrbuktxtcrt

DESCRIPTION | This routine creates a user specified space in an existing overflow (`.dtf`) file. Since the data segment updating routine `mrsubputi` won't change the size of the bulk or text attribute value it operates on, using `mrbuktxtcrt` is the only way of preparing a space on disk to hold incoming data segment for insert or update to a larger object. This routine, `mrbuktxtcrt`, does not allocate system memory, so there is no problem with creating data segment that is much larger than existing system memory. The allocated overflow `.dtf` extents will be filled with null values.
SYNOPSIS |
    long   mrbuktxtcrt (mrrdes* rec, mrades* mra, long size)
USAGE |
    flag = mrbuktxtcrt (rec, mra, size);
`rec` | Record descriptor.
`mra` | `BULK` or `TEXT` attribute descriptor.
`size` | User specified space. It does not include the end of sting terminator for `TEXT` data.
RETURNS | Return `-1` on failure.
WARNINGS | None.

# mrbuktxtlen

DESCRIPTION | This routine returns the length of the `BULK` or `TEXT` data in bytes.
SYNOPSIS |
    long   mrbuktxtlen(mrrdes* rec, mrades* mra)
USAGE |
    flag = mrbuktxtlen (rec, mra);
`rec` | Record descriptor.
`mra` | `BULK` or `TEXT` attribute descriptor.
RETURNS | On success, returns the total length of the data in bytes. On failure, a -1 indicating that the attribute is not a `BULK` or `TEXT` data type.
WARNINGS | If the attribute is text holding a C -style zero terminated string, the length returned will not include the zero terminator.

# mrcldict

DESCRIPTION | Close data dictionary.
SYNOPSIS |
    void   mrcldict (void)
USAGE |
    mrcldict (void);
RETURNS | None.
WARNINGS | None.

# mrclose

DESCRIPTION | Close a table, unlocking it if it is locked.
SYNOPSIS |
    msbool   mrclose (addr table_desc)
USAGE |
    flag = mrclose (table_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`table_desc` | Pointer (`addr`) to a table descriptor.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrcompare

DESCRIPTION | Compare an attribute value with a constant in file format. A pointer to a file format constant returned by one of the `mrcvt` routines may be used.
SYNOPSIS |
    int   mrcompare (addr record_desc,
                     addr attr_desc,
                     addr var_ptr)
USAGE |
    result = mrcompare (record_desc, attr_desc,
                        &var);

    result = mrcompare (record_desc, attr_desc,
                        mrcvt (attr_desc, string));
`result` | Integer result of the comparison.
`record_des` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
`var` | A variable containing a constant in file format.
`string` | Pointer (`char*`) to an external format value.
RETURNS | -1 if the attribute value is less than the constant; zero if the attribute value is equal to the constant; 1 if the attribute value is greater than the constant.
WARNINGS | None.

# mrcontrol

DESCRIPTION | Used to set the lower and upper bounds for a subsequent retrieval of a variable length data type value.
SYNOPSIS |
    msbool   mrcontrol (addr attr_desc,
                      int lower_bound,
                      int upper_bound)
USAGE |
    flag = mrcontrol (attr_desc, lower_bound,
               upper_bound)
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`attr_desc` | Pointer (`addr`) returned by `mrngeta` or `mirgeta`.
`lower_bound` | The number of the first byte to be read into the program buffer (`integer`).
`upper_bound` | The number of the last byte to be read into the program buffer (`integer`).
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrcopyi

DESCRIPTION | Copy the internal format of an attribute value to a variable. Used only in fixed applications; produces machine-dependent code.
SYNOPSIS |
    msbool   mrcopyi (addr record_desc,
                      addr attr_desc,
                      addr var_ptr)
USAGE |
    flag = mrcopyi (record_desc, attr_desc, &var);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
`var` | A variable of suitable type for storing the internal format of the attribute value.
RETURNS | True (1) if the value is not `NULL`, false (0) otherwise.
WARNINGS | Use of this routine results in non-portable code. The variable must be of the right type and length to store the attribute value retrieved, or the routine will fail. You must know how each Empress data type is stored on the machine for which you are writing.

# mrcopyr

DESCRIPTION | Copy the attribute values from one record into another. This routine is normally used when updating records.
SYNOPSIS |
    msbool   mrcopyr (addr new_rec_desc,
                    addr old_rec_desc)
USAGE |
    flag = mrcopyr (new_rec_desc, old_rec_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`new_rec_desc` | Pointer (`addr`) returned by `mrmkrec.` This must not be the same record_descriptor as `old_rec_desc`, but may be any other record_descriptor from the same table.
`old_rec_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | Both record_descriptors must refer to the same table.

# mrcopyv

DESCRIPTION | Assign an external format attribute value to the space allocated for it.
SYNOPSIS |
    msbool   mrcopyv (addr record_desc,
                      addr attr_desc,
                      char* space)
USAGE |
    flag = mrcopyv (record_desc, attr_desc,
                    space);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`space` | Pointer (`char*`) to the space allocated for the storage of an external format attribute value, returned by `mrspv`.
RETURNS | True (1), if the value of the attribute is not null; false (0), if the value of the attribute is null.
WARNINGS | Should not be used to retrieve `TEXT` or `BULK` data type attributes. `mrcopyv ()` terminates the calling program if the pointer passed as argument does not have space allocated to it.

# mrcvt

DESCRIPTION | Convert an external format attribute value to file format (public buffer).
SYNOPSIS |
    addr   mrcvt (addr attr_desc, char* string)
USAGE |
    value = mrcvt (attr_desc, string);
`value` | Pointer (`addr`) to a file format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`string` | Pointer (`char*)` to an external format attribute value.
RETURNS | Pointer (`addr`) to a file format attribute value if the conversion was successful, otherwise a zero pointer.
WARNINGS | `mrcvt` should be called immediately before the file format value is used, as the next call to many other mr routines will destroy the converted value.

# mrcvti

DESCRIPTION | Convert an internal format attribute value to file format (semi-private buffer).
SYNOPSIS |
    addr   mrcvti (addr attr_desc, addr var_ptr)
USAGE |
    value = mrcvti (attr_desc, var_ptr);
`value` | Pointer (`addr`) to a file format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`string` | Pointer (`char*`) to an external format attribute value.
RETURNS | Pointer (`addr`) to a file format attribute value if the conversion was successful, otherwise a zero pointer.
WARNINGS | `mrcvti` shares a buffer with `mrcvtv`, so the next call to either of these routines will destroy the converted value.

# mrcvti2

DESCRIPTION | Convert an internal format attribute value to file format (semi-private buffer).
SYNOPSIS |
    addr   mrcvti2 (addr attr_desc, addr var_ptr)
USAGE |
    value = mrcvti2 (attr_desc, var_ptr);
`value` | Pointer (`addr`) to a file format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`var_ptr` | Pointer (`addr`) to an internal format attribute value.
RETURNS | Pointer (`addr`) to a file format attribute value if the conversion was successful, otherwise a zero pointer.
WARNINGS | `mrcvti2` shares a buffer with `mrcvtv2`, so the next call to either of these routines will destroy the converted value.

# mrcvtin

DESCRIPTION | Convert an internal format attribute value to file format (public buffer).
SYNOPSIS |
    addr   mrcvtin (addr attr_desc, addr var_ptr)
USAGE |
    value = mrcvtin (attr_desc, var_ptr);
`value` | Pointer (`addr`) to a file format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`var_ptr` | Pointer (`addr`) to an internal format attribute value.
RETURNS | Pointer (`addr`) to a file format attribute value if the conversion was successful, otherwise a zero pointer.
WARNINGS | `mrcvtin` should be called immediately before the converted value is to be used, since it shares a buffer with several other mr routines, and the next call to any of them will destroy the converted value.

# mrcvtv

DESCRIPTION | Convert an external format attribute value to file format.
SYNOPSIS |
    addr   mrcvtv (addr attr_desc, char* string)
USAGE |
    value = mrcvtv (attr_desc, string);
`value` | Pointer (`addr`) to a file format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`string` | Pointer (`char*`) to an external format attribute value.
RETURNS | Pointer (`addr`) to a file format attribute value if the conversion was successful, otherwise a zero pointer.
WARNINGS | `mrcvtv` shares a buffer with `mrcvti`, so that the next call to either of these routines will destroy the converted value.

# mrcvtv2

DESCRIPTION | Convert an external format attribute value to file format.
SYNOPSIS |
    addr   mrcvtv2 (addr attr_desc, char* string)
USAGE |
    value = mrcvtv2 (attr_desc, string);
`value` | Pointer (`addr`) to a file format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`string` | Pointer (`char*`) to an external format attribute value.
RETURNS | Pointer (`addr`) to a file format attribute value if the conversion was successful, otherwise a zero pointer.
WARNINGS | `mrcvtv2` shares a buffer with `mrcvti2`, so that the next call to either of these routines will destroy the converted value.

# mrdel

DESCRIPTION | Delete a record from a table; terminate calling program on failure.
SYNOPSIS |
    void   mrdel (addr record_desc)
USAGE |
    mrdel (record_desc);
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | None.
WARNINGS | The record must first have been specified in a call to `mrgetbegin` and then retrieved by a successful call to `mrget`. `mrdelend` should be called to do cleaning up after one or more calls to `mrdel`. If the table was opened in deferred mode and an update lock cannot be made on the table, the routine will fail.

# mrdelend

DESCRIPTION | Clean up after deleting records from a table.
SYNOPSIS |
    msbool   mrdelend (addr record_desc)
USAGE |
    flag = mrdelend (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mreabort

DESCRIPTION | Abort building an expression. To be used in case any erroneous condition is detected while building an expression (this may be determined by the success or failure of the routines which add functions/operators or arguments/operands to the expression). Use of this routine precludes the use of `mreend`.
SYNOPSIS |
    void   mreabort (void)
USAGE |
    mreabort ();
RETURNS | None.
WARNINGS | None.

# mrebegin

DESCRIPTION | Start building an expression. This initializes an internal data structure.
SYNOPSIS |
    void   mrebegin (void)
USAGE |
    mrebegin ();
RETURNS | None.
WARNINGS | Must be the first call when building an expression.

# mrecons

DESCRIPTION | Add a constant argument/operand of type `type_desc` to the expression. Note that although the constant is in external format (a string), it may represent any other data type, including such data types as date and decimal, for instance.
SYNOPSIS |
    msbool   mrecons (char* string,
                      addr type_desc)
USAGE |
    flag = mrecons (string, type_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`string` | Pointer (`char*`) to the constant in external format (ie. a string).
`type_desc` | Pointer (`addr`) to the data type descriptor. This can be obtained with the routine `mrgdtpar`, or one of the generic data types given in the "Expressions" section of Chapter 3 can be used.
RETURNS | True if the addition is successful, false otherwise.
WARNINGS | None.

# mrecvarg

DESCRIPTION | Add a data type conversion operator to the expression.
SYNOPSIS |
    msbool   mrecvarg (addr type_desc)
USAGE |
    flag = mrecvarg (type_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`type_desc` | Pointer (`addr`) to the data type descriptor for the data type to which the expression value should be changed. Either a data type descriptor returned by the routine `mrgdtpar`, or one of the values for generic data type descriptors listed in the "Expressions" section of Chapter 3, should be used.
RETURNS | True if conversion is possible, false otherwise.
WARNINGS | None.

# mreend

DESCRIPTION | Finish building an expression and return its descriptor. If the expression descriptor is used directly (that is, by calling `mrerun`) then `mrefree` must be used to free the descriptor when the expression is no longer needed. If the expression is used in a qualification the descriptor will be freed automatically by Empress.
SYNOPSIS |
    addr   mreend (void)
USAGE |
    expr_desc = mreend ();
`expr_desc` | A descriptor (`addr`) for the expression.
RETURNS | Pointer (`addr`) to the expression descriptor.
WARNINGS | None.

# mrefree

DESCRIPTION | Free the expression descriptor. Must be called after the expression is not required any more.
SYNOPSIS |
    msbool   mrefree (addr expr_desc)
USAGE |
    flag = mrefree (expr_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`expr_desc` | Pointer (`addr`) to the expression descriptor.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrefunc

DESCRIPTION | Add a function or operator (i.e., an Empress supplied function/operator or user defined function/operator in Empress SQL). The name of the function, the number of arguments the function takes, and the types of arguments are checked against the arguments available. If any of these is invalid the function is not inserted in the expression. A failed call does not affect the expression stack.
SYNOPSIS |
    msbool   mrefunc (char* func, int nargs)
USAGE |
    flag = mrefunc (func, nargs);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`func` | Pointer (`char*`) to the name of the function.
`nargs` | Number of arguments the function takes.
RETURNS | True if the function addition is successful, false otherwise.
WARNINGS | None.

# mreicvar

DESCRIPTION | Associate a control variable with the most recent variable. It is usually called immediately after `mreivar` is called. If the parameter mode of the variable is IN/INOUT, the control variable is used to indicate the input value; if the parameter mode of the variable is `OUT`/ `INOUT`, the control variable is used to indicate the output. The data type of a control variable is `long` of C data type, a pointer to control variable is passed to the function. The possible values of a control variable are:
`MRECVAR_VALUE` | indicates the corresponding operand is a value.
`MRECVAR_NULL` | indicates the corresponding operand is null.
`MRECVAR_ERROR` | indicates error occurred with the corresponding operand.
SYNOPSIS |
    msbool   mreicvar (long* icvar)
USAGE |
    flag = mreicvar (icvar);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`icvar` | A pointer to the control variable. The type of the control variable is `long` of C data type.
RETURNS | True if successful; false otherwise.
WARNINGS | None.

# mreivar

DESCRIPTION | Add a variable argument/operand to the expression, using an indirect pointer to it. When the expression is evaluated, the current value of the variable is used in the expression. The type of the C variable used must correspond to the data type descriptor passed. Refer to Chapter 2 under "Data Type Correspondences".
SYNOPSIS |
    void   mreivar (addr* ivar, addr type_desc)
USAGE |
    mreivar (ivar, type_desc);
`ivar` | Indirect pointer (`addr`) to the variable; i.e., `ivar` points to a pointer that points to the value. The type of the variable is restricted to the types supported by C.
`type_desc` | Pointer (`addr`) to the data type descriptor of the data type of the variable. This can be a pointer returned by the routine `mrgdtpar`, or a value corresponding to one of the generic data types as listed in the "Expressions" section of Chapter 3.
RETURNS | None.
WARNINGS | None.

# mrenull

DESCRIPTION | Add a function which checks whether the most recent argument/operand placed on the stack is `NULL`.
SYNOPSIS |
    msbool   mrenull (char* func)
USAGE |
    flag = mrenull (func);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`func` | Pointer (`char*`) to the function. The only functions of use here are "`=`" or "`!`".
RETURNS | True if the function addition is successful, false otherwise.
WARNINGS | None.

# mrerecattr

DESCRIPTION | Add an attribute argument/operand to the expression. The value of the attribute is taken from the specified record at the time the expression is evaluated.
SYNOPSIS |
    msbool   mrerecattr (addr record_desc,
                       addr attr_desc)
USAGE |
    flag = mrerecattr (record_desc, attr_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) to the record_descriptor returned by `mrmkrec ()` routine from which the attribute value is to be taken.
`attr_desc` | Pointer (`addr`) to the attribute_descriptor returned by either `mrngeta ()` or `mrigeta ()` routines.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrerrmsg

DESCRIPTION | Return a string describing the current error condition.
SYNOPSIS |
    char*   mrerrmsg (void)
USAGE |
    string = mrerrmsg ();
`string` | Pointer (`char*`) to the text message.
RETURNS | A pointer (`char*`) to the text message describing the current error condition.
WARNINGS | `mrerrmsg` should be called immediately after an error; the string it reads may be corrupted by the next mr call. This routine is not thread-safe and should not be used inside threads.

# mrerun

DESCRIPTION | Run the expression and return a pointer to the result. The type of the result is the type of the expression. This routine may be called more than once with referenced variables and/or attribute values updated between calls. This routine should not be used if the expression is part of a qualification. If the result is stored in a C variable, the variable must be of the appropriate type. Refer to Chapter 2 under "Data Type Correspondences".
SYNOPSIS |
    addr   mrerun (addr expr_desc)
USAGE |
    result = mrerun (expr_desc);
`result` | Pointer (`addr`) to the result of the expression.
`expr_desc` | Pointer (`addr`) to the expression descriptor.
RETURNS | Pointer (`addr`) to the result if successful, otherwise `NIL`.
WARNINGS | None.

# mrfree

DESCRIPTION | Free the space allocated by `mrspv` `mrmalloc`, `mrrealloc`.
SYNOPSIS |
    void   mrfree (char* space)
USAGE |
    mrfree (space);
`space` | Pointer (`char*`) returned by `mrspv`.
RETURNS | None.
WARNINGS | None.

# mrfrrec

DESCRIPTION | Free space used for storing a record.
SYNOPSIS |
    msbool   mrfrrec (addr record_desc)
USAGE |
    flag = mrfrrec (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrganame

DESCRIPTION | Obtain the name of an attribute, given the attribute_descriptor.
SYNOPSIS |
    char*   mrganame (addr attr_desc)
USAGE |
    name = mrganame (attr_desc);
`name` | Pointer (`char*`) to the name of the attribute.
`attr_desc` | Pointer (`addr`) to the specified attribute.
RETURNS | Pointer (`char*`) to the name of the specified attribute.
WARNINGS | None.

# mrgdtpar

DESCRIPTION | Get data type descriptor for the attribute given the attribute_descriptor.
SYNOPSIS |
    addr   mrgdtpar (addr attr_desc)
USAGE |
    type_desc = mrgdtpar (attr_desc);
`type_desc` | Pointer (`addr`) to the data type descriptor.
`attr_desc` | Pointer (`addr`) to the attribute_descriptor.
RETURNS | Pointer (`addr`) to a data type descriptor.
WARNINGS | None.

# mrget

DESCRIPTION | Retrieve a record from a table.
SYNOPSIS |
    msbool   mrget (addr retrieval_desc)
USAGE |
    flag = mrget (retrieval_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin`.
RETURNS | True (1) if successful; false (0) if unsuccessful, i.e., if all records have been retrieved. The calling program is terminated if the call fails. If the record is locked the call fails.
WARNINGS | `mrgetend` should be called after one or more calls to `mrget` to do cleaning up.

# mrgetbegin

DESCRIPTION | Associate a given qualification with one or more records; terminate the calling program on failure.
SYNOPSIS |
    addr   mrgetbegin (addr qual_desc, addr record_desc_1,
                       [ ... addr record_desc_n,] (addr)0)
USAGE |
    retrieval_desc = mrgetbegin (qual_desc, record_desc_1,
                                 record_desc_2, ...., ADDRNIL);
`retrieval_desc` | Pointer (`addr`) to the retrieval_descriptor to be passed to `mrget`.
`qual_desc` | Pointer (`addr`) to a qualification_descriptor returned by any of the `mrq` routines. If no qualification is present, it is replaced by `ADDRNIL`.
`record_desc_1` | Pointer (`addr`) returned by `mrmkrec`.
`record_desc_2` | Pointer (`addr`) returned by `mrmkrec`.
`ADDRNIL` | `(addr) 0` as defined in the header file `mscc.h`.
RETURNS | Pointer (`addr`) to the retrieval_descriptor to be passed to `mrget`.
WARNINGS | Use of two or more records implies a cross-product or join (see `mrget`). Hence the record_descriptors must be derived from different table_descriptors. All the attribute_descriptors in the `mrq` routines used to generate the qualification_descriptor should belong to the table_descriptor(s) corresponding to the record_descriptor(s) given as arguments to `mrgetbegin`, or the procedure will fail. Any qualification_descriptor passed to `mrgetbegin` will be destroyed, and cannot be re-used.

# mrgetend

DESCRIPTION | Clean up after retrieving records from a table.
SYNOPSIS |
    void   mrgetend (addr retrieval_desc)
USAGE |
    mrgetend (retrieval_desc);
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin` or `mrsrtbegin`.
RETURNS | None.
WARNINGS | None.

# mrgeti

DESCRIPTION | Obtain a pointer to a buffer containing an internal format attribute value.
SYNOPSIS |
    addr   mrgeti (addr record_desc,
                   addr attr_desc)
USAGE |
    result = mrgeti (record_desc, attr_desc);
`result` | Pointer (`addr`) to a buffer with the internal format attribute value.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | A pointer (`addr`) to a buffer containing the internal format attribute value. The value so found should be used immediately, or else the buffer copied, since the next call to `mrgetvs` or `mrgeti` destroys its contents.

# mrgetptr

DESCRIPTION | Obtain a pointer to a record for later use.
SYNOPSIS |
    long   mrgetptr (addr record_desc)
USAGE |
    record_ptr = mrgetptr (record_desc);
`record_ptr` | Pointer (`long`) to the record.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | A pointer (`long`) to the record currently referred to by the record_descriptor.
WARNINGS | This routine is only meaningful for tables and simple views.

# mrgetrec

DESCRIPTION | Obtain a record given a pointer to it.
SYNOPSIS |
    int   mrgetrec (addr record_desc,
                    long record_ptr)
USAGE |
    flag = mrgetrec (record_desc, record_ptr);
`flag` | Indicator (`int`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`record_ptr` | Pointer (`long`) to the record.
RETURNS | True (1) if successful, false (0) if unsuccessful, and -1 if the record is locked.
WARNINGS | None.

# mrgetvi

DESCRIPTION | Retrieve an integer attribute value.
SYNOPSIS |
    int   mrgetvi (addr record_desc,
                   addr attr_desc)
USAGE |
    result = mrgetvi (record_desc, attr_desc);
`result` | The attribute value as an integer.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | The attribute value as an integer.
WARNINGS | The routine will fail and terminate the calling program if the attribute value cannot be converted to an integer.

# mrgetvs

DESCRIPTION | Obtain a pointer to a buffer containing an external format attribute value.
SYNOPSIS |
    char*   mrgetvs (addr record_desc,
                     addr attr_desc)
USAGE |
    result = mrgetvs (record_desc, attr_desc);
`result` | Pointer (`char*`) to the internal buffer with the external format attribute value.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | A pointer (`char*`) to an internal buffer containing the external format attribute value.
WARNINGS | The value so found should be used immediately, or the buffer copied, since the next call to `mrgetvs` or `mrgeti` destroys its contents.

# mrgfunc

DESCRIPTION | Find the result of an aggregate function for an attribute.
SYNOPSIS |
    char*   mrgfunc (char* function,
                     addr retrieval_desc,
                     addr record_desc,
                     addr attr_desc)
USAGE |
    value = mrgfunc (function, retrieval_desc,
                     record_desc,
                     attr_desc);
`value` | Pointer (`char*`) to the value of the function.
`function` | String `(char*)` containing one of `COUNT`, `SUM`, `AVG`, `MIN`, or `MAX`.
`retrieval_desc` | Pointer (`addr`) returned by one of the `mrgetbegin` routines
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | A pointer (`char*`) to the value of the function. If there are no records, an empty string is returned.
WARNINGS | `mrgetend` must be called to do cleaning up after `mrgfunc`, and the value found should be freed with `mrfree`.

# mrigeta

DESCRIPTION | Obtain an attribute_descriptor for attribute`i`, where `i` is the number of the attribute.
SYNOPSIS |
    addr   mrigeta (addr table_desc,
                    int  attr_number)
USAGE |
    attr_desc = mrigeta (table_desc,
                         attr_number);
`attr_desc` | Pointer (`addr`) to the specified attribute.
`table_desc` | Pointer (`addr`) to an opened table returned by `mropen`.
`attr_number` | The number of the attribute specified. The first attribute in the table is 1, the second 2, and so on. The attribute order is that shown by a Query Language `DISPLAY TABLE` command.
RETURNS | Pointer (`addr`) to the attribute_descriptor if successful, and a zero pointer if `attr_number` is invalid.
WARNINGS | None.

# mrlkrec

DESCRIPTION | Hold a record level lock on a retrieved record.
SYNOPSIS |
    msbool   mrlkrec (addr record_desc)
USAGE |
    flag = mrlkrec (record_desc);
`flag` | Indicator (`msbool`) of success or failure to lock the record.
`record_desc` | Pointer (`addr`) to a record returned by `mrmkrec`.
RETURNS | True (1) if successful; false (0) if unable to lock the record.
WARNINGS | This routine will have effect only if the locking level for the table is `RECORD`. However, in case of non-`RECORD` lock level, this routine still returns true.

# mrlktab

DESCRIPTION | Lock a table to restrict access by others while an application is running.
SYNOPSIS |
    msbool   mrlktab (addr table_desc)
USAGE |
    flag = mrlktab (table_desc);
`flag` | Indicator (`msbool`) of success or failure to lock the table.
`table_desc` | Pointer (`addr`) to an opened table returned by `mropen`.
RETURNS | True (1) if successful; false (0) if unable to lock the table.
WARNINGS | If the locking level for the table is `NULL`, `mrlktab` will have no effect (the routine still returns `true`).

# mrmalloc

DESCRIPTION | Space allocation for data storage which will subsequently be used by Empress RDBMS.
SYNOPSIS |
    void*   mrmalloc (int size)
USAGE |
    space = mrmalloc (size);
`space` | Pointer (`void*`) to the space allocated.
`size` | Integer (`int`) that defines a size of allocated space.
RETURNS | Pointer (`void*`) to the space allocated.
WARNINGS | The space will remain allocated until specifically freed using `mrfree`.

# mrmkrec

DESCRIPTION | Allocate space for storage of a record.
SYNOPSIS |
    addr   mrmkrec (addr table_desc)
USAGE |
    record_desc = mrmkrec (table_desc);
`record_desc` | Pointer (`addr`) to the space for storing a record of the specified table.
`table_desc` | Pointer (`addr`) to an opened table returned by `mropen`.
RETURNS | Pointer (`addr`) to the record_descriptor.
WARNINGS | The space allocated for the `record_desc` will stay allocated unless specifically freed using `mrfrrec`.

# mrmptvi

DESCRIPTION | Assign a C integer to a given attribute in a record; terminate the calling program on failure.
SYNOPSIS |
    void   mrmptvi (addr record_desc,
                    addr attr_desc,
                    int value)
USAGE |
    mrmptvi (record_desc, attr_desc,
             integer);
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`integer` | A C integer or an integer variable.
RETURNS | Nothing; the calling program is terminated if `mrmptvi` fails.
WARNINGS | None.

# mrmptvs

DESCRIPTION | Assign a value to a given attribute in a record; terminate calling program on failure.
SYNOPSIS |
    void   mrmptvs (addr record_desc,
                    addr attr_desc,
                    char* value)
USAGE |
    mrmptvs (record_desc, attr_desc, value);
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`value` | Pointer `(char*)` to the external format value to be assigned to the attribute.
RETURNS | Nothing; the calling program is terminated if `mrmptvs` fails.
WARNINGS | None.

# mrmutexlock

DESCRIPTION | To mark the starting point of mutual exclusion (mutex) piece of code. All the code between `mrmutexlock ()` and `mrmutexunlock` are thread safe.
SYNOPSIS |
    void   mrmutexlock (void)
USAGE |
    mrmutexlock ()
RETURNS | None.
WARNINGS | None.

# mrmutexunlock

DESCRIPTION | To mark the end point of mutual exclusion (mutex) piece of code. All the code between `mrmutexlock ()` and `mrmutexunlock` are thread safe.
SYNOPSIS |
    void   mrmutexunlock (void)
USAGE |
    mrmutexunlock ()
RETURNS | None.
WARNINGS | None.

# mrngeta

DESCRIPTION | Obtain an attribute_descriptor for the named attribute.
SYNOPSIS |
    addr   mrngeta (addr table_desc,
                    char* attr_name)
USAGE |
    attr_desc = mrngeta (table_desc, attr_name);
`attr_desc` | Pointer (`addr`) to the specified attribute.
`table_desc` | Pointer (`addr`) to an opened table returned by `mropen`.
`attr_name` | Pointer `(char*)` to the name of the attribute.
RETURNS | Pointer (`addr`) to the attribute_descriptor if successful, and a zero pointer if unsuccessful (e.g., invalid name).
WARNINGS | None.

# mrnullr

DESCRIPTION | See if a whole record is `NULL`.
SYNOPSIS |
    msbool   mrnullr (addr record_desc)
USAGE |
    flag = mrnullr (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | True (1) if the record is `NULL`; false (0) if not.
WARNINGS | None.

# mrnullv

DESCRIPTION | See if an attribute value in the record is `NULL`.
SYNOPSIS |
    msbool   mrnullv (addr record_desc, addr attr_desc)
USAGE |
    flag = mrnullv (record_desc, attr_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
RETURNS | True (1) if the attribute value is `NULL`; false (0) if not.
WARNINGS | None.

# mropdict

DESCRIPTION | Open a data dictionary for internal access by the mr routines; terminate the calling program on failure.
SYNOPSIS |
    void   mropdict (char* database_name,
                     char mode)
USAGE |
    mropdict   (database_name, mode);
`database_name` | Pointer `(char*)` to the name of the database directory.
`mode` | Either '`r`' or '`u`', indicating read or update, respectively. The single quotes are mandatory.
RETURNS | None.
WARNINGS | It is generally unwise to specify the current directory when calling `mropdict` (i.e., you should not run applications while 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 data dictionary tables, or if update mode is specified and the person executing the program has no read and write permission on the data dictionary tables, `mropdict` will fail and terminate the program calling it.

# mropen

DESCRIPTION | Open a table for use with the mr routines; terminate on failure. The table is set up for locking at the level indicated in the data dictionary. If table level locking is set, the table is locked by this routine.
SYNOPSIS |
    addr   mropen (char* database_name,
                   char* table_name,
                   char mode)
USAGE |
    table_desc = mropen (database_name,
                         table_name, mode);
`table_desc` | Pointer (`addr`) to a table_descriptor.
`database_name` | Pointer `(char*)` to the name of the database directory.
`table_name` | Pointer `(char*)` to the name of the table.
`mode` | Either '`r`', '`u`', '`d`', '`n`' or '`N`' indicating read, update, deferred, dirty read or deferred dirty read respectively. The single quotes are mandatory. 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 `mrdel`, `mrput`, `mrtdel` or `mrtput` is executed.
RETURNS | Pointer (`addr`) to a table_descriptor if successful. If unsuccessful, nothing is returned and the program calling it is terminated.
WARNINGS | It is generally unwise to specify the current directory when calling `mropen` (i.e., you should not run applications while 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 data dictionary tables, or if update mode is specified and the person executing the program has no read and write permission on the data dictionary tables, `mropen` will fail and terminate the program calling it.

# mrprev

DESCRIPTION | Retrieve the previous record from a table.
SYNOPSIS |
    msbool   mrprev (addr retrieval_desc)
USAGE |
    flag = mrprev (retrieval_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin`.
RETURNS | True (1) if successful; false (0) if unsuccessful, i.e., if all records have been retrieved. If the record is locked the call fails. The calling program is terminated if the call fails.
WARNINGS | `mrgetend` should be called after one or more calls to `mrprev` to do cleaning up.

# mrprterr

DESCRIPTION | Print an error message depending on a previous error; terminate the calling program.
SYNOPSIS |
    void   mrprterr (void)
USAGE |
    mrprterr ();
RETURNS | None.
WARNINGS | This routine is not thread-safe and should not be used inside threads.

# mrput

DESCRIPTION | Update a record.
SYNOPSIS |
    void   mrput   (addr new_rec_desc,
                    addr old_rec_desc)
USAGE |
    mrput (new_rec_desc, old_rec_desc);
`new_rec_desc` | Pointer (`addr`) returned by `mrmkrec`. This points to the record with the updated attribute values.
`old_rec_desc` | Pointer (`addr`) returned by `mrmkrec`. This points to the record with the originally retrieved attribute values.
RETURNS | None.
WARNINGS | The `old_rec_desc` must point to a record which has been retrieved by calls to `mrgetbegin` and `mrget`, otherwise `mrput` will fail. If the table was opened in deferred mode and an update lock cannot be made on the table the routine will fail.

# mrputi

DESCRIPTION | Assign an internal format value to a given attribute in a record.
SYNOPSIS |
    msbool   mrputi (addr record_desc,
                     addr attr_desc,
                     addr var_ptr)
USAGE |
    flag = mrputi (record_desc, attr_desc,
                   var_ptr);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`var_ptr` | A pointer to a variable containing the internal format value to be assigned to the attribute.
RETURNS | True (1) if successful; false (0) if unable to convert the given value to fit the attribute.
WARNINGS | If the routine returns false (0), the value for the attribute in the space pointed to by the record_descriptor is not guaranteed to be unchanged. Use of this routine results in non-portable code. If there is a range check on the attribute, this routine does not check if the value is valid for the range.

# mrputvi

DESCRIPTION | Assign a C integer to a given attribute in a record.
SYNOPSIS |
    msbool   mrputvi (addr record_desc,
                      addr attr_desc,
                      int value)
USAGE |
    flag = mrputvi (record_desc, attr_desc,
                    integer);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`integer` | A C integer or integer variable.
RETURNS | True (1) if successful; false (0) if unable to convert the given value to fit the attribute.
WARNINGS | If the routine returns false (0), the value for the attribute in the space pointed to by the record_descriptor is not guaranteed to be unchanged.

# mrputvs

DESCRIPTION | Assign a value in external format to a given attribute in a record.
SYNOPSIS |
    msbool   mrputvs (addr record_desc,
                      addr attr_desc,
                      char* value)
USAGE |
    flag = mrputvs (record_desc, attr_desc,
                    value);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`value` | Pointer `(char*)` to the external format value to be assigned to the attribute.
RETURNS | True (1) if successful; false (0) if unable to convert the given value to fit the attribute.
WARNINGS | If the routine returns false (0), the value for the attribute in the space pointed to by the record_descriptor is not guaranteed to be unchanged.

# mrqand

DESCRIPTION | Perform an `AND` operation on two qualification_descriptors obtained from any of the `mrq` routines.
SYNOPSIS |
    addr   mrqand (addr qual_desc_1,
                   addr qual_desc_2)
USAGE |
    qual_desc = mrqand (qual_desc_1, qual_desc_2);
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`qual_desc_1` | Pointer (`addr`) returned by any of the `mrq` routines.
`qual_desc_2` | Pointer (`addr`) returned by any of the `mrq` routines.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | `mrqand` destroys the qualification_descriptors in its argument list and frees the space allocated to them, so they cannot be used again.

# mrqatr

DESCRIPTION | Compare an attribute value to another attribute value.
SYNOPSIS |
    addr   mrqatr (char* operator,
                   addr attr_desc_1,
                   addr attr_desc_2)
USAGE |
    qual_desc = mrqatr (operator, attr_desc_1,
                        attr_desc_2);
`operator` | String `(char*)` containing one of the following: "`>`", "`<`", "`>=`", "`<=`", "`=`", or "`!=`" ("`~=`" is a synonym for "`!=`").
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`attr_desc_1` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`attr_desc_2` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | The two attributes compared must be compatible, otherwise `mrqatr` will fail.

# mrqcon

DESCRIPTION | Compare an attribute value with a constant in file format. A pointer to a file format constant returned by one of the `mrcvt` routines may be used.
SYNOPSIS |
    addr   mrqcon (char* operator,
                   addr attr_desc,
                   addr var_ptr)
USAGE |
    qual_desc = mrqcon (operator, attr_desc, &var);

    qual_desc = mrqcon (operator, attr_desc,
                        mrcvt (attr_desc, string));
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`operator` | String `(char*)` containing one of the following: "`>`", "`<`", "`>=`", "`<=`", "`=`", or "`!=`" ("`~=`" is a synonym for "`!=`").
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`var` | Variable containing a constant in file format.
`string` | Pointer `(char*)` to an external format attribute value.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | None.

# mrqdb

DESCRIPTION | Check whether a given pathname is a valid Empress database.
SYNOPSIS |
    msbool   mrqdb (char* directory)
USAGE |
    flag = mrqdb (directory);
`flag` | Indicator (`msbool`) to show success or failure.
`directory` | String `(char*)` containing the name of the directory.
RETURNS | True (1) if the directory is an Empress database; false (0) if not.
WARNINGS | None.

# mrqexpr

DESCRIPTION | Put an expression in the qualification. This returns a qualification _descriptor which may then be passed to one of the retrieval initialization routines such as, `mrgetbegin`.
SYNOPSIS |
    addr   mrqexpr (addr expr_desc)
USAGE |
    qual_desc = mrqexpr (expr_desc)
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`expr_desc` | Pointer (`addr`) to the expression descriptor. The expression descriptor must represent a boolean expression.
RETURNS | Pointer to qualification_descriptor. If the expression descriptor is not a descriptor for a valid expression, the routine will fail terminating the calling program.

# mrqieq

DESCRIPTION | Compare an attribute value to a C integer.
SYNOPSIS |
    addr   mrqieq (addr attr_desc, int integer)
USAGE |
    qual_desc = mrqieq (attr_desc, integer);
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`integer` | An integer or an integer variable.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | None.

# mrqlst

DESCRIPTION | Qualify a set of previously found records.
SYNOPSIS |
    addr   mrqlst (addr table_desc, long array[])
USAGE |
    qual_desc = mrqlst (table_desc, array);
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by one of the `mrgetbegin` routines (retrieval initialization routines).
`table_desc` | Pointer (`addr`) to an opened table returned by one of the `mropen` routines.
`array` | An array of pointers (`long`) to records found by `mrgetptr`.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | None.

# mrqmch

DESCRIPTION | Compare an attribute value to a pattern.
SYNOPSIS |
    addr   mrqmch (char* operator,
                   addr attr_desc,
                   char* pattern)
USAGE |
    qual_desc = mrqmch (operator, attr_desc,
                        pattern);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor used by `mrgetbegin`.
`operator` | String `(char*)` containing one of the following: `MATCH`, `SMATCH`, `!MATCH` or `!SMATCH` ("`~`" may be used as a synonym for "`!`").
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`pattern` | Pointer `(char*)` to a pattern.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | None.

# mrqnot

DESCRIPTION | Perform a `NOT` operation on a qualification_descriptor, obtained from any of the `mrq` routines, to reverse its sense.
SYNOPSIS |
    addr   mrqnot (addr qual_desc)
USAGE |
    qual_desc = mrqnot (qual_desc);
`qual_desc` | Pointer (`addr`) returned by any of the `mrq` routines.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | `mrqnot` destroys its argument qualification_descriptor and frees the space allocated to it, so it cannot be used again.

# mrqnul

DESCRIPTION | Compare an attribute value to `NULL`.
SYNOPSIS |
    addr   mrqnul (char* operator, addr attr_desc)
USAGE |
    qual_desc = mrqnul (operator, attr_desc);
`qual_desc` | Pointer (`addr`) to a qualification_description used by `mrgetbegin`.
`operator` | String ``(char*)`` containing "`=`" or "`!=`" ("`~=`" is a synonym for "`!=`").
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | None.

# mrqor

DESCRIPTION | Perform an `OR` operation on two qualification_descriptors obtained from any of the `mrq` routines.
SYNOPSIS |
    addr   mrqor (addr qual_desc_1,
                  addr qual_desc_2)
USAGE |
    qual_desc = mrqor (qual_desc_1,
                       qual_desc_2);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor.
`qual_desc_1` | Pointer (`addr`) returned by any of the `mrq` routines.
`qual_desc_2` | Pointer (`addr`) returned by any of the `mrq` routines.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | `mrqor` destroys the qualification_descriptors in its argument list and frees the space allocated to them, so they cannot be used again.

# mrqrng

DESCRIPTION | Compare an attribute value to a given range. The limits of the range are specified as pointers to file format values. Pointers returned by the `mrcvt` routines may be used.
SYNOPSIS |
    addr   mrqrng (addr attr_desc, addr lower_limit,
                   char limit_type_1,
                   addr upper_limit,
                   char limit_type_2)
USAGE |
    qual_desc = mrqrng (attr_desc, lower_limit,
                        limit_type_1, upper_limit,
                        limit_type_2);

    qual_desc = mrqrng (attr_desc,
                        mrcvtv (attr_desc, string_1),
                        limit_type_1,
                        mrcvtv2 (attr_desc, string_2),
                        limit_type_2);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor used by `mrgetbegin`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`limit_type_1` | Either '`i`' or '`e`', indicating that the lower limit is inclusive or exclusive, respectively. The single quotes are mandatory.
`limit_type_2` | Either '`i`' or '`e`', indicating that the upper limit is inclusive or exclusive, respectively. The single quotes are mandatory.
`string_1` | Pointer `(char*)` to an external format attribute value.
`string_2` | Pointer `(char*)` to an external format attribute value.
`lower_limit` | Pointer (`addr`) to the file format value representing the lower limit of the range.
`upper_limit` | Pointer (`addr`) to the file format value representing the upper limit of the range.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | None.

# mrqseq

DESCRIPTION | Test if an attribute value is equal to a string.
SYNOPSIS |
    addr   mrqseq (addr attr_desc, char* string)
USAGE |
    qual_desc = mrqseq (attr_desc, string);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor used by `mrgetbegin`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`string` | Pointer `(char*)` to an external format attribute value.
RETURNS | Pointer (`addr`) to a qualification_descriptor.
WARNINGS | The routine will fail and terminate the calling program if the string cannot be converted to a legal attribute value of the correct data type.

# mrrealloc

DESCRIPTION | Changes the size of the space allocated by `mrmalloc`.
SYNOPSIS |
    void*   mrrealloc (void* space, int size)
USAGE |
    realloc_space = mrrealloc (space, size);
`realloc_space` | Pointer (void*) to the space allocated which will be used by Empress RDBMS.
`space` | Pointer (void*) to the space previously allocated.
`size` | Integer (`int`) that defines a size of allocated space.
RETURNS | Pointer (void*) to space allocated which will be used by Empress RDBMS.
WARNINGS | The space will remain allocated until freed by `mrfree`.

# mrreget

DESCRIPTION | Make a second or subsequent attempt to retrieve a record from a table.
SYNOPSIS |
    int   mrreget (addr retrieval_desc)
USAGE |
    flag = mrreget (retrieval_desc);
`flag` | Indicator (`int`) to show success or failure of the routine.
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin`.
RETURNS | 1 if successful; 0 when all records have been retrieved; and -1 if the record is locked. If the routine fails, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | `mrgetend` should be called after one or more calls to `mrreget` to do cleaning up.

# mrreprev

DESCRIPTION | Make a second or subsequent attempt to retrieve the previous record from a table.
SYNOPSIS |
    int   mrreprev (addr retrieval_desc)
USAGE |
    flag = mrreprev (retrieval_desc);
`flag` | Indicator (`int`) to show success or failure of the routine.
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin`.
RETURNS | 1 if successful; 0 when all records have been retrieved; and -1 if the record is locked. If the routine fails, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | `mrgetend` should be called after one or more calls to `mrreprev` to do cleaning up.

# mrsetnr

DESCRIPTION | Assign a `NULL` value to all attributes in a record.
SYNOPSIS |
    msbool   mrsetnr (addr record_desc)
USAGE |
    flag = mrsetnr (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrsetnv

DESCRIPTION | Assign a `NULL` value to a given attribute in a record.
SYNOPSIS |
    msbool   mrsetnv (addr record_desc, addr attr_desc)
USAGE |
    flag = mrsetnv (record_desc, attr_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrspv

DESCRIPTION | Allocate space to store an external format attribute value.
SYNOPSIS |
    char*   mrspv (addr attr_desc)
USAGE |
    space = mrspv (attr_desc);
`space` | Pointer `(char*)` to space allocated for storage of an external format attribute value.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | Pointer `(char*)` to space allocated for storage of the external format attribute value. If used on a text or bulk data type attribute, it returns a zero pointer.
WARNINGS | The space will remain allocated until explicitly freed by calling `mrfree`. The routine cannot be used to allocate space for `TEXT` or `BULK` data type attributes.

# mrsrtbegin

DESCRIPTION | Associate a given qualification with one or more records for sorted output; terminate the calling program on failure.
SYNOPSIS |
    addr   mrsrtbegin (addr qual_desc, char indicator,
                       addr record_desc_1,
                       [ ... addr record_desc_n,] (addr)0,
                       addr attr_desc_1, char type,
                       [ ... addr attr_desc_n, char type,]
                       (addr)0)
USAGE |
    retrieval_desc = mrsrtbegin (qual_desc, indicator,
                        record_desc_1, record_desc_2, ... , ADDRNIL,
                        attr_desc_1, type, attr_desc_2, type, .... ,
                        ADDRNIL);
`retrieval_desc` | Pointer (`addr`) to the retrieval_descriptor to be passed to `mrget`.
`qual_desc` | Pointer (`addr`) to qualification_descriptor returned by any of the `mrq` routines. If no qualification is present it is replaced by `ADDRNIL`.
`indicator` | Either '`u`' or '`s`', indicating a unique or non-unique sort, respectively. The single quotes are mandatory. 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.
`record_desc_1` | Pointer (`addr`) returned by `mrmkrec`.
`record_desc_2` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc_1` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
`attr_desc_2` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
`type` | Either '`a`' or '`d`', for an ascending or descending sort, respectively. The single quotes are mandatory.
`ADDRNIL` | `(addr) 0` as defined in the header `mscc.h`.
RETURNS | Pointer (`addr`) to a retrieval_descriptor which is used by `mrget`.
WARNINGS | Use of two records implies a cross-product or join (see `mrget`), so the two records should be from different tables. All the attribute_descriptors in the `mrq` routines used to generate the qualification_descriptor should belong to the table_descriptor(s) corresponding to the record_descriptor(s) given as arguments to `mrsrtbegin`, or the procedure will fail. Any qualification_descriptor passed to `mrsrtbegin` will be destroyed, and cannot be re-used.

# mrsubbegin

DESCRIPTION | Initiates the start of an update operation of data segment.
SYNOPSIS |
    msbool   mrsubbegin (addr record_desc)
USAGE |
    flag = mrsubbegin (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | `mrsubbegin` will activate locking for partial updates. It is recommended that this call is made before an `mradd` or `mrput` call inside the same insert or update loop. If you want proper locking behaviour you must put all your partial updates of data segment inside the record between `mrsubbegin` and `mrsubend`.

# mrsubend

DESCRIPTION | Indicates the end of an update operation of data segment.
SYNOPSIS |
    msbool   mrsubend (addr record_desc)
USAGE |
    flag = mrsubend (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrsubgeti

DESCRIPTION | This routine retrieves a segment of data from a `BULK` or `TEXT` attribute.
SYNOPSIS |
    long   mrsubgeti (mrrdes* rec, mrades* mra, addr* buktxtint,
                      long offset, long size)
USAGE |
    flag = mrsubgeti (rec, mra, buktxtint, offset, size);
`rec` | Record descriptor.
`mra` | `BULK` or `TEXT` attribute descriptor.
`buktxtint` | A pointer to a pointer of the region of memory to hold the retrieved data segment. This is the output parameter.
`offset` | Indicates the beginning of the data segment to be retrieved, in bytes from the beginning of the `BULK` or `TEXT` attribute.
`size` | Indicates how many bytes to read after the offset.
RETURNS | Returns `-1` on failure.
WARNINGS | In order to retrieve a data segment smaller than the entire data, the `.dtf` file checksum must be turned off (zero) for the table in question. Also notice that `buktxtint` is a pointer to a pointer, not the same as the simple pointer `buktxtint` in `mrsubputi`.

# mrsubputi

DESCRIPTION | This routine performs a data segment update for `BULK` or `TEXT` data type. It overwrites the sections of data within the attribute.
SYNOPSIS |
    long   mrsubputi (mrrdes* rec, mrades* mra,
                      addr buktxtint, long offset)
USAGE |
    flag = mrsubputi (rec, mra, buktxtint, offset);
`rec` | Record descriptor.
`mra` | `BULK` or `TEXT` attribute descriptor.
`buktxtint` | A pointer to the internal buffer of `BULK` or `TEXT` data.
`offset` | Indicates the beginning of the data segment to be updated, in bytes from the beginning of the `BULK` or `TEXT` attribute.
RETURNS | Returns `-1` on failure.
WARNINGS | None.

# mrtadd

DESCRIPTION | Insert a record into a given table, indicating whether the insertion was successful or not. `mrtadd` should be used when an attribute has a unique index on it.
SYNOPSIS |
    msbool   mrtadd (addr record_desc)
USAGE |
    flag = mrtadd (record_desc);
`flag` | Indicator (`msbool`) to show outcome of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | True (1) if successful; false (0) if unsuccessful. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | `mraddend` should be called to clean up after one or more calls to `mrtadd`.

# mrtdel

DESCRIPTION | Delete a record from a table; do not terminate if unsuccessful.
SYNOPSIS |
    msbool   mrtdel (addr record_desc)
USAGE |
    flag = mrtdel (record_desc);
`flag` | Indicator (`msbool`) to show outcome of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | True (1) if successful; false (0) if not. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | The record must first have been specified in a call to one of the `mrgetbegin` routines and then retrieved by a successful call to one of the `mrget` routines. `mrdelend` should be called to do cleaning up after one or more calls to `mrtdel`.

# mrtget

DESCRIPTION | Retrieve a record from a table; do not terminate calling program if unsuccessful.
SYNOPSIS |
    int   mrtget (addr retrieval_desc)
USAGE |
    flag = mrtget (retrieval_desc);
`flag` | Indicator (`int`) to show outcome of the call.
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin`.
RETURNS | 1 if successful; 0 when all records have been retrieved; and -1 if the record is locked. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file`mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | `mrgetend` should be called to do cleaning up after one or more calls to `mrtget`.

# mrtgfunc

DESCRIPTION | Find the count, sum, average, minimum, or maximum value for an attribute; do not terminate the calling program if unsuccessful.
SYNOPSIS |
    char*   mrtgfunc (char* function,
                      addr retrieval_desc,
                      addr record_desc,
                      addr attr_desc)
USAGE |
    value = mrtgfunc (function, retrieval_desc,
                      record_desc, attr_desc);
`value` | Pointer `(char*)` to the value of the function.
`function` | String `(char*)` containing one of `COUNT`, `SUM`, `AVG`, `MIN` or `MAX`.
`retrieval_desc` | Pointer (`addr`) returned by one of the `mrgetbegin` routines.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`; use `CHARNIL` if the function is `COUNT`.
RETURNS | A pointer `(char*)` to the value of the function, or `CHARNIL` if not all the appropriate records could be accessed. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure. If there are no records, an empty string is returned.
WARNINGS | `mrgetend` must be called to do cleaning up after `mrgfunc`, and the value found should be freed with `mrfree`.

# mrtgtbegin

DESCRIPTION | Associate a given qualification with one or more records. Do not terminate the calling program if unsuccessful.
SYNOPSIS |
    addr   mrtgtbegin (addr qual_desc, addr record_desc_1,
                       [ ... addr record_desc_n,] (addr)0)
USAGE |
    retrieval_desc = mrtgtbegin (qual_desc, record_desc_1,
                                 record_desc_2, .... , ADDRNIL);
`retrieval_desc` | Pointer (`addr`) to a retrieval_descriptor to be passed to one of the `mrget` routines.
`qual_desc` | Pointer (`addr`) to a qualification_descriptor returned by any of the `mrq` routines. If no qualification is present, it is replaced by `ADDRNIL`.
`record_desc_1` | Pointer (`addr`) returned by `mrmkrec`.
`record_desc_2` | Pointer (`addr`) returned by `mrmkrec`.
`ADDRNIL` | `(addr) 0` as defined in the header file `mscc.h`.
RETURNS | Pointer (`addr`) to a retrieval_descriptor to be passed to one of the `mrget` routines if all appropriate records could be accessed; `(addr)0` (`ADDRNIL`) otherwise. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | Use of two or more records implies a cross-product or join (see `mrget`), so the record_descriptors must be derived from different table_descriptors. All the attribute_descriptors in the `mrq` routines used to generate the qualification_descriptor must belong to the table_descriptor(s) corresponding to the record_descriptor(s) given as arguments to `mrtgtbegin`, or the procedure will fail. Any qualification_descriptor passed to `mrtgtbegin` will be destroyed, and cannot be re-used.

# mrtopdict

DESCRIPTION | Open a data dictionary for internal access by the mr routines; do not terminate the calling program if unsuccessful.
SYNOPSIS |
    msbool   mrtopdict (char* database_name,
                        char mode)
USAGE |
    flag = mrtopdict (database_name, mode);
`flag` | Indicator (`msbool`) to show outcome of the routine.
`database_name` | Pointer `(char*)` to the name of the database directory.
`mode` | Either '`r`' or '`u`', indicating read or update, respectively. The single quotes are mandatory.
RETURNS | True (1) if successful, false (0) on failure. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes listed in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | It is generally unwise to specify the current directory when calling `mropdict` (i.e., you should not run applications while 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 data dictionary tables, or if update mode is specified and the person executing the program has no read and write permission on the data dictionary tables, `mrtopdict` will fail.

# mrtopen

DESCRIPTION | Open a table for use with the mr routines; do not terminate if unsuccessful. The table is set up for locking at the level indicated in the data dictionary. If table level locking is set, the table is locked by this routine.
SYNOPSIS |
    addr   mrtopen (char* database_name,
                    char* table_name,
                    char mode)
USAGE |
    table_desc = mrtopen (database_name,
                          table_name, mode);
`table_desc` | Pointer (`addr`) to a table_descriptor.
`database_name` | Pointer `(char*)` to the name of the database directory.
`table_name` | Pointer `(char*)` to the name of the table.
`mode` | Either '`r`', '`u`', '`d`', '`n`' or '`N`' indicating read, update, deferred, dirty read or deferred dirty read respectively. The single quotes are mandatory. The dirty read mode will retrieve records bypass all locking (Refer to Empress: Database Administrator's Guide under Dirty Read). 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 `mrdel`, `mrput`, `mrtdel` or `mrtput` is executed.
RETURNS | Pointer (`addr`) to table_descriptor if successful; a zero pointer if unsuccessful. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | It is generally unwise to specify the current directory when calling `mrtopen` (i.e., you should not run applications while 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 data dictionary tables, or if update mode is specified and the person executing the program has no read and write permission on the data dictionary tables, `mrtopen` will not succeed.

# mrtprev

DESCRIPTION | Retrieve the previous record from a table; do not terminate calling program if unsuccessful.
SYNOPSIS |
    int   mrtprev (addr retrieval_desc)
USAGE |
    flag = mrtprev (retrieval_desc);
`flag` | Indicator (`int`) to show outcome of the routine.
`retrieval_desc` | Pointer (`addr`) returned by `mrgetbegin`.
RETURNS | 1 if successful; 0 when all records have been retrieved; and -1 if the record is locked. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | `mrgetend` should be called to do cleaning up after one or more calls to `mrtprev`.

# mrtput

DESCRIPTION | Update a record, indicating success or failure of the update. `mrtput` should be used when an attribute has a unique index on it.
SYNOPSIS |
    msbool   mrtput (addr new_rec_desc,
                     addr old_rec_desc)
USAGE |
    flag = mrtput (new_rec_desc, old_rec_desc);
`flag` | Indicator (`msbool`) to show outcome of the routine.
`new_rec_desc` | Pointer (`addr`) returned by `mrmkrec`. This points to the record with the updated attribute values.
`old_rec_desc` | Pointer (`addr`) returned by `mrmkrec`. This points to the record with the originally retrieved attribute values.
RETURNS | True (1) if successful; false (0) if unsuccessful. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | The original record_descriptor must point to a record which has been retrieved by calls to `mrgetbegin` and `mrget`, otherwise `mrtput` will fail.

# mrtqatr

DESCRIPTION | Compare an attribute value to another attribute value; report if unsuccessful.
SYNOPSIS |
    addr   mrtqatr (char* operator,
                    addr attr_desc_1,
                    addr attr_desc_2)
USAGE |
    qual_desc = mrtqatr (operator, attr_desc_1,
                         attr_desc_2);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor used by `mrgetbegin`.
`operator` | String `(char*)` containing one of the following: "`=`", "`>=`", "`>`", "`<=`", "`<`", or "`!=`" ("`~=`" is a synonym for "`!=`").
`attr_desc_1` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`attr_desc_2` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | Pointer (`addr`) to a qualification_descriptor; `ADDRNIL` `(addr)0` on failure. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | The two attributes compared must be compatible, otherwise `mrtqatr` will fail.

# mrtqcon

DESCRIPTION | Compare an attribute value with a constant in file format; report if unsuccessful. A pointer to a file format constant returned by one of the `mrcvt` routines may be used.
SYNOPSIS |
    addr   mrtqcon (char* operator,
                    addr attr_desc,
                    addr var_ptr)
USAGE |
    qual_desc = mrtqcon (operator, attr_desc,
                         &var);

    qual_desc = mrtqcon (operator, attr_desc,
                         mrcvt (attr_desc, string));
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`operator` | String `(char*)` containing one of the following: "`>`", "`<`", "`>=`", "`<=`", "`=`" or "`!=`" ("`~=`" is a synonym for "`!=`").
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`var` | Variable containing a constant in file format.
`string` | Pointer `(char*)` to an external format attribute value.
RETURNS | Pointer (`addr`) to a qualification_descriptor; `ADDRNIL` (`addr)0` on failure. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | None.

# mrtqmch

DESCRIPTION | Compare an attribute value to a pattern; report if unsuccessful.
SYNOPSIS |
    addr   mrtqmch (char* operator,
                    addr attr_desc,
                    char* pattern)
USAGE |
    qual_desc = mrtqmch (operator, attr_desc,
                         pattern);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor used by `mrgetbegin`.
`operator` | String `(char*)` containing one of the following: `MATCH`, `SMATCH`, `!MATCH` or `!SMATCH` ("`~`" may used as a synonym for "`!`").
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`pattern` | Pointer `(char*)` to a pattern.
RETURNS | Pointer (`addr`) to a qualification_descriptor; `ADDRNIL` `(addr)0` on failure. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | None.

# mrtqnul

DESCRIPTION | Compare an attribute value to `NULL`; report if unsuccessful.
SYNOPSIS |
    addr   mrtqnul (char* operator, addr attr_desc)
USAGE |
    qual_desc = mrtqnul (operator, attr_desc);
`qual_desc` | Pointer (`addr`) to qualification_descriptor used by `mrgetbegin`.
`operator` | String `(char*)` containing "`=`" or "`!=`" ("`~=`" is a synonym for "`!=`").
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
RETURNS | Pointer (`addr`) to a qualification_descriptor; `ADDRNIL` `(addr)0` on failure. If the routine is unsuccessful, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | None.

# mrtqrng

DESCRIPTION | Compare an attribute value to a given range; report if unsuccessful.
SYNOPSIS |
    addr   mrtqrng (addr attr_desc,
                    addr lower_limit,
                    char limit_type_1,
                    addr upper_limit,
                    char limit_type_2)
USAGE |
    qual_desc = mrtqrng (attr_desc, lower_limit,
                         limit_type_1, upper_limit,
                         limit_type_2);

    qual_desc = mrtqrng (attr_desc,
                         mrcvtv (attr_desc, string_1),
                         limit_type_1,
                         mrcvtv2 (attr_desc, string_2),
                         limit_type_2);
`qual_desc` | Pointer (`addr`) to a qualification_descriptor used by `mrgetbegin`.
`attr_desc` | Pointer (`addr`) returned by `mrigeta` or `mrngeta`.
`string_1` | Pointer `(char*)` to an external format attribute value.
`string_2` | Pointer `(char*)` to an external format attribute value.
`limit_type_1` | Either '`i`' or '`e`', indicating that the lower limit is inclusive or exclusive, respectively. The single quotes are mandatory.
`limit_type_2` | Either '`i`' or '`e`', indicating that the upper limit is inclusive or exclusive, respectively. The single quotes are mandatory.
`lower_limit` | Pointer (`addr`) to the file format value representing the lower limit of the range.
`upper_limit` | Pointer (`addr`) to the file format value representing the upper limit of the range.
RETURNS | Pointer (`addr`) to a qualification_descriptor; `ADDRNIL` `(addr)0` if unsuccessful. If the routine fails, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | None.

# mrtrcancel

DESCRIPTION | Cancel a transaction and return the database to its former condition.
SYNOPSIS |
    msbool   mrtrcancel (void)
USAGE |
    flag = mrtrcancel ();
`flag` | Indicator (`msbool`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if unsuccessful.
WARNINGS | None.

# mrtrcommit

DESCRIPTION | Commit a transaction and make all changes to the database permanent.
SYNOPSIS |
    msbool   mrtrcommit (void)
USAGE |
    flag = mrtrcommit ();
`flag` | Indicator (`msbool`) to show success or failure of the routine.
RETURNS | True (1) if successful; false (0) if unsuccessful.
WARNINGS | A transaction must be in progress.

# mrtrrollback

DESCRIPTION | Roll back the transaction to the save point.
SYNOPSIS |
    msbool   mrtrrollback (char* savepoint)
USAGE |
    flag = mrtrrollback (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 savepoint is `CHARNIL` (" ") this is equivalent to an `mrtrcancel`.
RETURNS | True (1) if successful; false (0) if unsuccessful.
WARNINGS | A transaction must be in progress and the save point must be set. If `mrtrrollback` is called after delete or update of a record within `mrgetbegin` and `mrgetend`, the content of the record becomes undefined.

# mrtrsave

DESCRIPTION | Set a save point in the transaction.
SYNOPSIS |
    msbool   mrtrsave (char* savepoint)
USAGE |
    flag = mrtrsave (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.

# mrtrstart

DESCRIPTION | Start a transaction.
SYNOPSIS |
    msbool   mrtrstart (void)
USAGE |
    flag = mrtrstart ();
`flag` | Indicator (`msbool`) to show success or failure of the routine.
RETURNS | True (1) if a transaction is started; false (0) if not. Failure usually means a transaction is already in progress.
WARNINGS | None.

# mrtsrbegin

DESCRIPTION | Associate a given qualification with one or more records for sorted output; do not terminate the calling program on failure.
SYNOPSIS |
    addr   mrtsrbegin (addr qual_desc, char indicator,
                       addr record_desc_1,
                       [ ... addr record_desc_n,] (addr)0,
                       addr attr_desc_1, char type,
                       [ ... addr attr_desc_n, char type,] (addr)0)
USAGE |
    retrieval_desc = mrtsrbegin (qual_desc, indicator, record_desc_1,
                     record_desc_2, .... , ADDRNIL, attr_desc_1, type,
                     attr_desc_2, type, .... , ADDRNIL);
`retrieval_desc` | Pointer (`addr`) to the retrieval_descriptor to be passed to `mrget`.
`qual_desc` | Pointer (`addr`) to a qualification_descriptor returned by any of the `mrq` routines. If no qualification is present, it is replaced by `ADDRNIL`.
`indicator` | Either '`u`' or '`s`', indicating a unique or non-unique sort, respectively. The single quotes are mandatory.
`record_desc_1` | Pointer (`addr`) returned by `mrmkrec`.
`record_desc_2` | Pointer (`addr`) returned by `mrmkrec`.
`attr_desc_1` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
`attr_desc_2` | Pointer (`addr`) returned by `mrngeta` or `mrigeta`.
`type` | Either '`a`' or '`d`', for an ascending or descending sort, respectively. The single quotes are mandatory.
RETURNS | Pointer (`addr`) to a retrieval_descriptor which is used by `mrget` if all appropriate records could be accessed; `ADDRNIL` `(addr)0` otherwise. If the routine fails, the variable `mroperr` will contain one of the `MRER`... codes described in the header file `mrerrno.h`, and may be examined to determine the cause of failure.
WARNINGS | Use of two records implies a cross-product or join (see `mrget`), so the two records should be from different tables. All the attribute_descriptors in the `mrq` routines used to generate the qualification_descriptor should belong to the table_descriptor(s) corresponding to the record_descriptor(s) given as arguments to `mrtsrbegin`, or the procedure will fail. Any qualification_descriptor passed to `mrtsrbegin` will be destroyed, and cannot be re-used.

# mrulrec

DESCRIPTION | Unlock a record. This routine is used to unlock records that have been retrieved using `mrgetrec`, and to release locks created with `mrlkrec`.
SYNOPSIS |
    msbool   mrulrec (addr record_desc)
USAGE |
    flag = mrulrec (record_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`record_desc` | Pointer (`addr`) returned by `mrmkrec`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | The routine will fail if the record is not locked.

# mrultab

DESCRIPTION | Unlock a table after running an application.
SYNOPSIS |
    msbool   mrultab (addr table_desc)
USAGE |
    flag = mrultab (table_desc);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`table_desc` | Pointer (`addr`) to an opened table returned by `mropen`.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.

# mrsetstmtoption

DESCRIPTION | Sets options on a statement handle. mrsetstmtoption will modify the expected behavior of mr routines that retrieve, insert, update and delete records. The concept of a connection and a statement handle will be introduced in the future. Current mrsetstmtoption routine uses a default statement handle MRSTMT_DEFAULT.
SYNOPSIS |
    msbool mrsetstmtoption (addr stmthandle, int option, addr arg)
USAGE |
    flag = mrsetstmtoption (stmthandle, option, arg>);
`flag` | Indicator (`msbool`) to show success or failure of the routine.
`stmthandle` | A statement handle. Currently, it allows only one value: MRSTMT_DEFAULT
`option` | Type of option to set. e.g. MRSTMT_QUERY_MAXROWS, MRSTMT_BOUNDED_RESPONSE_TIME_MRGETBEGIN
`arg` | An argument associated with the option.
Option Type | Argument Value
MRSTMT_QUERY_MAXROWS | A C long integer corresponding to the maximum number of records that a retrieval descriptor may point to (contain). Default value is zero. Zero means that there is no limit.
MRSTMT_BOUNDED_RESPONSE_TIME_MRGETBEGIN | A C double corresponding to the number of seconds to wait (time limit) for mrgetbegin or mrsrtbegin to execute before returning to the application. Default value is zero. Zero means that there is no limit.
MRSTMT_BOUNDED_RESPONSE_TIME_MRGET | A C double corresponding to the number of seconds to wait (time limit) for mrget to execute before returning to the application. Default value is zero. Zero means that there is no limit.
MRSTMT_BOUNDED_RESPONSE_TIME_MRPUT | A C double corresponding to the number of seconds to wait (time limit) for mrput to execute before returning to the application. Default value is zero. Zero means that there is no limit.
MRSTMT_BOUNDED_RESPONSE_TIME_MRDEL | A C double corresponding to the number of seconds to wait (time limit) for mrdel to execute before returning to the application. Default value is zero. Zero means that there is no limit.
MRSTMT_BOUNDED_RESPONSE_TIME_MRADD | A C double corresponding to the number of seconds to wait (time limit) for mradd to execute before returning to the application. Default value is zero. Zero means that there is no limit.
RETURNS | Return true if successful; false otherwise.
WARNINGS | None.