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.

void   msclean (void (* proc) (void))

msclean (proc ());

None.

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.

This routine is used to improve the performance of inserts and updates into TEXT, NLSTEXT and BULK attributes.

void   msdtfsta (msbool enable)

msdtfsta (enable);

None.

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 mscallroutine which executes a DDL statement.

This routine call the cleanup procedures without terminating the program.

void   msend (void)

msend ();

None.

None.

This routine calls msexitcleanup before terminating the program. It passes a value to the shell.

void   msexit (int value)

msexit (value);

None.

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.

This routine call the cleanup procedures without terminating the program.

void msexitcleanup (void)

msexitcleanup ();

None.

None.

Initialize for mscall, mx and mr routines.

msbool   msinit (void)

msinit ();

Return true if successful; false otherwise.

None.

Free the space allocated by mspsm_malloc.

void   mspsm_free (char* space)

mspsm_free (space);

None.

This routine should be used only in Persistent Stored Modules (PSM).

This routine is not thread-safe and should not be used inside threads.

Allocate space for storing data in Persistent Stored Modules (PSM).

void*   mspsm_malloc (int size)

space = mspsm_malloc (size);

Pointer (void*) to space allocated for storage used in Persistent Stored Module (PSM).

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.

Changes the size of the space allocated by mspsm_malloc.

void*   mspsm_realloc (void* space, int size)

realloc_space = mspsm_realloc (space, size);

Pointer (void*) to space allocated for storage used in Persistent Stored Module (PSM).

The space will remain allocated until freed internally by Empress RDBMS.

This routine is not thread-safe and should not be used inside threads.

This routine is used in trigger procedure to abort the corresponding operation.

void   mspsm_trig_abort_operation (void)

mspsm_trig_abort_operation ();

None.

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.

This routine is used to get the table descriptor and the record descriptor in a trigger procedure.

void   mspsm_trig_get_record_info (void** pmr, 
                               void** poldrec, 
                               void** pnewrec)

mspsm_trig_get_record_info (pmr, poldrec, pnewrec);

None.

1. The space for descriptors is allocated and deallocated by the system.

2. 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.

3. 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.

4. This routine is not thread-safe and should not be used inside threads.

Insert a record into a given table; terminate calling program on failure.

void   mradd (addr record_desc)

mradd (record_desc);

None.

mraddend should be called to clean up after one or more calls to mradd.

End a group of insertions.

msbool	mraddend (addr record_desc)

flag = mraddend (record_desc);

Return true if successful; false otherwise.

None.

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.

long   mrbuktxtcrt (mrrdes* rec, mrades* mra, long size)

flag = mrbuktxtcrt (rec, mra, size);

Return -1 on failure.

None.

This routine returns the length of the BULK or TEXT data in bytes.

long   mrbuktxtlen(mrrdes* rec, mrades* mra)

flag = mrbuktxtlen (rec, mra);

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.

If the attribute is text holding a C -style zero terminated string, the length returned will not include the zero terminator.

Close data dictionary.

void   mrcldict (void)

mrcldict (void);

None.

None.

Close a table, unlocking it if it is locked.

msbool   mrclose (addr table_desc)

flag = mrclose (table_desc);

Return true if successful; false otherwise.

None.

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.

int   mrcompare (addr record_desc, 
                 addr attr_desc, 
                 addr var_ptr)

result = mrcompare (record_desc, attr_desc, 
                    &var);

result = mrcompare (record_desc, attr_desc, 
                    mrcvt (attr_desc, string));

-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.

None.

Used to set the lower and upper bounds for a subsequent retrieval of a variable length data type value.

msbool   mrcontrol (addr attr_desc, 
                  int lower_bound,
                  int upper_bound)

flag = mrcontrol (attr_desc, lower_bound, 
           upper_bound)

Return true if successful; false otherwise.

None.

Copy the internal format of an attribute value to a variable. Used only in fixed applications; produces machine-dependent code.

msbool   mrcopyi (addr record_desc, 
                  addr attr_desc,
                  addr var_ptr)

flag = mrcopyi (record_desc, attr_desc, &var);

True (1) if the value is not NULL, false (0) otherwise.

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.

Copy the attribute values from one record into another. This routine is normally used when updating records.

msbool   mrcopyr (addr new_rec_desc, 
                addr old_rec_desc)

flag = mrcopyr (new_rec_desc, old_rec_desc);

Return true if successful; false otherwise.

Both record_descriptors must refer to the same table.

Assign an external format attribute value to the space allocated for it.

msbool   mrcopyv (addr record_desc, 
                  addr attr_desc, 
                  char* space)

flag = mrcopyv (record_desc, attr_desc, 
                space);

True (1), if the value of the attribute is not null; false (0), if the value of the attribute is null.

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.

Convert an external format attribute value to file format (public buffer).

addr   mrcvt (addr attr_desc, char* string)

value = mrcvt (attr_desc, string);

Pointer (addr) to a file format attribute value if the conversion was successful, otherwise a zero pointer.

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.

Convert an internal format attribute value to file format (semi-private buffer).

addr   mrcvti (addr attr_desc, addr var_ptr)

value = mrcvti (attr_desc, var_ptr);

Pointer (addr) to a file format attribute value if the conversion was successful, otherwise a zero pointer.

mrcvti shares a buffer with mrcvtv, so the next call to either of these routines will destroy the converted value.

Convert an internal format attribute value to file format (semi-private buffer).

addr   mrcvti2 (addr attr_desc, addr var_ptr)

value = mrcvti2 (attr_desc, var_ptr);

Pointer (addr) to a file format attribute value if the conversion was successful, otherwise a zero pointer.

mrcvti2 shares a buffer with mrcvtv2, so the next call to either of these routines will destroy the converted value.

Convert an internal format attribute value to file format (public buffer).

addr   mrcvtin (addr attr_desc, addr var_ptr)

value = mrcvtin (attr_desc, var_ptr);

Pointer (addr) to a file format attribute value if the conversion was successful, otherwise a zero pointer.

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.

Convert an external format attribute value to file format.

addr   mrcvtv (addr attr_desc, char* string)

value = mrcvtv (attr_desc, string);

Pointer (addr) to a file format attribute value if the conversion was successful, otherwise a zero pointer.

mrcvtv shares a buffer with mrcvti, so that the next call to either of these routines will destroy the converted value.

Convert an external format attribute value to file format.

addr   mrcvtv2 (addr attr_desc, char* string)

value = mrcvtv2 (attr_desc, string);

Pointer (addr) to a file format attribute value if the conversion was successful, otherwise a zero pointer.

mrcvtv2 shares a buffer with mrcvti2, so that the next call to either of these routines will destroy the converted value.

Delete a record from a table; terminate calling program on failure.

void   mrdel (addr record_desc)

mrdel (record_desc);

None.

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.

Clean up after deleting records from a table.

msbool   mrdelend (addr record_desc)

flag = mrdelend (record_desc);

Return true if successful; false otherwise.

None.

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.

void   mreabort (void)

mreabort ();

None.

None.

Start building an expression. This initializes an internal data structure.

void   mrebegin (void)

mrebegin ();

None.

Must be the first call when building an expression.

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.

msbool   mrecons (char* string, 
                  addr type_desc)

flag = mrecons (string, type_desc);

True if the addition is successful, false otherwise.

None.

Add a data type conversion operator to the expression.

msbool   mrecvarg (addr type_desc)

flag = mrecvarg (type_desc);

True if conversion is possible, false otherwise.

None.

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.

addr   mreend (void)

expr_desc = mreend ();

Pointer (addr) to the expression descriptor.

None.

Free the expression descriptor. Must be called after the expression is not required any more.

msbool   mrefree (addr expr_desc)

flag = mrefree (expr_desc);

Return true if successful; false otherwise.

None.

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.

msbool   mrefunc (char* func, int nargs)

flag = mrefunc (func, nargs);

True if the function addition is successful, false otherwise.

None.

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:

msbool   mreicvar (long* icvar)

flag = mreicvar (icvar);

True if successful; false otherwise.

None.

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".

void   mreivar (addr* ivar, addr type_desc)

mreivar (ivar, type_desc);

None.

None.

Add a function which checks whether the most recent argument/operand placed on the stack is NULL.

msbool   mrenull (char* func)

flag = mrenull (func);

True if the function addition is successful, false otherwise.

None.

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.

msbool   mrerecattr (addr record_desc, 
                   addr attr_desc)

flag = mrerecattr (record_desc, attr_desc);

Return true if successful; false otherwise.

None.

Return a string describing the current error condition.

char*   mrerrmsg (void)

string = mrerrmsg ();

A pointer (char*) to the text message describing the current error condition.

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.

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".

addr   mrerun (addr expr_desc)

result = mrerun (expr_desc);

Pointer (addr) to the result if successful, otherwise NIL.

None.

Free the space allocated by mrspv mrmalloc, mrrealloc.

void   mrfree (char* space)

mrfree (space);

None.

None.

Free space used for storing a record.

msbool   mrfrrec (addr record_desc)

flag = mrfrrec (record_desc);

Return true if successful; false otherwise.

None.

Obtain the name of an attribute, given the attribute_descriptor.

char*   mrganame (addr attr_desc)

name = mrganame (attr_desc);

Pointer (char*) to the name of the specified attribute.

None.

Get data type descriptor for the attribute given the attribute_descriptor.

addr   mrgdtpar (addr attr_desc)

type_desc = mrgdtpar (attr_desc);

Pointer (addr) to a data type descriptor.

None.

Retrieve a record from a table.

msbool   mrget (addr retrieval_desc)

flag = mrget (retrieval_desc);

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.

mrgetend should be called after one or more calls to mrget to do cleaning up.

Associate a given qualification with one or more records; terminate the calling program on failure.

addr   mrgetbegin (addr qual_desc, addr record_desc_1,
                   [ ... addr record_desc_n,] (addr)0)

retrieval_desc = mrgetbegin (qual_desc, record_desc_1,
                             record_desc_2, ...., ADDRNIL);

Pointer (addr) to the retrieval_descriptor to be passed to mrget.

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.

Clean up after retrieving records from a table.

void   mrgetend (addr retrieval_desc)

mrgetend (retrieval_desc);

None.

None.

Obtain a pointer to a buffer containing an internal format attribute value.

addr   mrgeti (addr record_desc, 
               addr attr_desc)

result = mrgeti (record_desc, attr_desc);

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.

Obtain a pointer to a record for later use.

long   mrgetptr (addr record_desc)

record_ptr = mrgetptr (record_desc);

A pointer (long) to the record currently referred to by the record_descriptor.

This routine is only meaningful for tables and simple views.

Obtain a record given a pointer to it.

int   mrgetrec (addr record_desc, 
                long record_ptr)

flag = mrgetrec (record_desc, record_ptr);

True (1) if successful, false (0) if unsuccessful, and -1 if the record is locked.

None.

Retrieve an integer attribute value.

int   mrgetvi (addr record_desc, 
               addr attr_desc)

result = mrgetvi (record_desc, attr_desc);

The attribute value as an integer.

The routine will fail and terminate the calling program if the attribute value cannot be converted to an integer.

Obtain a pointer to a buffer containing an external format attribute value.

char*   mrgetvs (addr record_desc, 
                 addr attr_desc)

result = mrgetvs (record_desc, attr_desc);

A pointer (char*) to an internal buffer containing the external format attribute value.

The value so found should be used immediately, or the buffer copied, since the next call to mrgetvs or mrgeti destroys its contents.

Find the result of an aggregate function for an attribute.

char*   mrgfunc (char* function, 
                 addr retrieval_desc,
                 addr record_desc, 
                 addr attr_desc)

value = mrgfunc (function, retrieval_desc, 
                 record_desc,
                 attr_desc);

A pointer (char*) to the value of the function. If there are no records, an empty string is returned.

mrgetend must be called to do cleaning up after mrgfunc, and the value found should be freed with mrfree.

Obtain an attribute_descriptor for attribute i, where i is the number of the attribute.

addr   mrigeta (addr table_desc, 
                int  attr_number)

attr_desc = mrigeta (table_desc, 
                     attr_number);

Pointer (addr) to the attribute_descriptor if successful, and a zero pointer if attr_number is invalid.

None.

Hold a record level lock on a retrieved record.

msbool   mrlkrec (addr record_desc)

flag = mrlkrec (record_desc);

True (1) if successful; false (0) if unable to lock the record.

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.

Lock a table to restrict access by others while an application is running.

msbool   mrlktab (addr table_desc)

flag = mrlktab (table_desc);

True (1) if successful; false (0) if unable to lock the table.

If the locking level for the table is NULL, mrlktab will have no effect (the routine still returns true).

Space allocation for data storage which will subsequently be used by Empress RDBMS.

void*   mrmalloc (int size)

space = mrmalloc (size);

Pointer (void*) to the space allocated.

The space will remain allocated until specifically freed using mrfree.

Allocate space for storage of a record.

addr   mrmkrec (addr table_desc)

record_desc = mrmkrec (table_desc);

Pointer (addr) to the record_descriptor.

The space allocated for the record_desc will stay allocated unless specifically freed using mrfrrec.

Assign a C integer to a given attribute in a record; terminate the calling program on failure.

void   mrmptvi (addr record_desc, 
                addr attr_desc, 
                int value)

mrmptvi (record_desc, attr_desc, 
         integer);

Nothing; the calling program is terminated if mrmptvi fails.

None.

Assign a value to a given attribute in a record; terminate calling program on failure.

void   mrmptvs (addr record_desc, 
                addr attr_desc, 
                char* value)

mrmptvs (record_desc, attr_desc, value);

Nothing; the calling program is terminated if mrmptvs fails.

None.

To mark the starting point of mutual exclusion (mutex) piece of code. All the code between mrmutexlock () and mrmutexunlock are thread safe.

void   mrmutexlock (void)

mrmutexlock () 

None.

None.

To mark the end point of mutual exclusion (mutex) piece of code. All the code between mrmutexlock () and mrmutexunlock are thread safe.

void   mrmutexunlock (void)

mrmutexunlock () 

None.

None.

Obtain an attribute_descriptor for the named attribute.

addr   mrngeta (addr table_desc, 
                char* attr_name)

attr_desc = mrngeta (table_desc, attr_name);

Pointer (addr) to the attribute_descriptor if successful, and a zero pointer if unsuccessful (e.g., invalid name).

None.

See if a whole record is NULL.

msbool   mrnullr (addr record_desc)

flag = mrnullr (record_desc);

True (1) if the record is NULL; false (0) if not.

None.

See if an attribute value in the record is NULL.

msbool   mrnullv (addr record_desc, addr attr_desc)

flag = mrnullv (record_desc, attr_desc);

True (1) if the attribute value is NULL; false (0) if not.

None.

Open a data dictionary for internal access by the mr routines; terminate the calling program on failure.

void   mropdict (char* database_name, 
                 char mode)

mropdict   (database_name, mode);

None.

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.

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.

addr   mropen (char* database_name, 
               char* table_name, 
               char mode) 

table_desc = mropen (database_name, 
                     table_name, mode);

Pointer (addr) to a table_descriptor if successful. If unsuccessful, nothing is returned and the program calling it is terminated.

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.

Retrieve the previous record from a table.

msbool   mrprev (addr retrieval_desc)

flag = mrprev (retrieval_desc);

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.

mrgetend should be called after one or more calls to mrprev to do cleaning up.

Print an error message depending on a previous error; terminate the calling program.

void   mrprterr (void)

mrprterr ();

None.

This routine is not thread-safe and should not be used inside threads.

Update a record.

void   mrput   (addr new_rec_desc, 
                addr old_rec_desc)

mrput (new_rec_desc, old_rec_desc);

None.

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.

Assign an internal format value to a given attribute in a record.

msbool   mrputi (addr record_desc, 
                 addr attr_desc, 
                 addr var_ptr)

flag = mrputi (record_desc, attr_desc, 
               var_ptr);

True (1) if successful; false (0) if unable to convert the given value to fit the attribute.

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.

Assign a C integer to a given attribute in a record.

msbool   mrputvi (addr record_desc, 
                  addr attr_desc, 
                  int value)

flag = mrputvi (record_desc, attr_desc, 
                integer);

True (1) if successful; false (0) if unable to convert the given value to fit the attribute.

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.

Assign a value in external format to a given attribute in a record.

msbool   mrputvs (addr record_desc, 
                  addr attr_desc, 
                  char* value)

flag = mrputvs (record_desc, attr_desc, 
                value);

True (1) if successful; false (0) if unable to convert the given value to fit the attribute.

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.

Perform an AND operation on two qualification_descriptors obtained from any of the mrq routines.

addr   mrqand (addr qual_desc_1, 
               addr qual_desc_2)

qual_desc = mrqand (qual_desc_1, qual_desc_2);

Pointer (addr) to a qualification_descriptor.

mrqand destroys the qualification_descriptors in its argument list and frees the space allocated to them, so they cannot be used again.

Compare an attribute value to another attribute value.

addr   mrqatr (char* operator, 
               addr attr_desc_1, 
               addr attr_desc_2)

qual_desc = mrqatr (operator, attr_desc_1, 
                    attr_desc_2);

Pointer (addr) to a qualification_descriptor.

The two attributes compared must be compatible, otherwise mrqatr will fail.

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.

addr   mrqcon (char* operator, 
               addr attr_desc, 
               addr var_ptr)

qual_desc = mrqcon (operator, attr_desc, &var);

qual_desc = mrqcon (operator, attr_desc, 
                    mrcvt (attr_desc, string));

Pointer (addr) to a qualification_descriptor.

None.

Check whether a given pathname is a valid Empress database.

msbool   mrqdb (char* directory)

flag = mrqdb (directory);

True (1) if the directory is an Empress database; false (0) if not.

None.

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.

addr   mrqexpr (addr expr_desc)

qual_desc = mrqexpr (expr_desc)

Pointer to qualification_descriptor. If the expression descriptor is not a descriptor for a valid expression, the routine will fail terminating the calling program.

Compare an attribute value to a C integer.

addr   mrqieq (addr attr_desc, int integer)

qual_desc = mrqieq (attr_desc, integer);

Pointer (addr) to a qualification_descriptor.

None.

Qualify a set of previously found records.

addr   mrqlst (addr table_desc, long array[])

qual_desc = mrqlst (table_desc, array);

Pointer (addr) to a qualification_descriptor.

None.

Compare an attribute value to a pattern.

addr   mrqmch (char* operator, 
               addr attr_desc, 
               char* pattern)

qual_desc = mrqmch (operator, attr_desc, 
                    pattern);

Pointer (addr) to a qualification_descriptor.

None.

Perform a NOT operation on a qualification_descriptor, obtained from any of the mrq routines, to reverse its sense.

addr   mrqnot (addr qual_desc)

qual_desc = mrqnot (qual_desc);

Pointer (addr) to a qualification_descriptor.

mrqnot destroys its argument qualification_descriptor and frees the space allocated to it, so it cannot be used again.

Compare an attribute value to NULL.

addr   mrqnul (char* operator, addr attr_desc)

qual_desc = mrqnul (operator, attr_desc);

Pointer (addr) to a qualification_descriptor.

None.

Perform an OR operation on two qualification_descriptors obtained from any of the mrq routines.

addr   mrqor (addr qual_desc_1, 
              addr qual_desc_2)

qual_desc = mrqor (qual_desc_1, 
                   qual_desc_2);

Pointer (addr) to a qualification_descriptor.

mrqor destroys the qualification_descriptors in its argument list and frees the space allocated to them, so they cannot be used again.

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.

addr   mrqrng (addr attr_desc, addr lower_limit, 
               char limit_type_1,  
               addr upper_limit, 
               char limit_type_2)

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);

Pointer (addr) to a qualification_descriptor.

None.

Test if an attribute value is equal to a string.

addr   mrqseq (addr attr_desc, char* string)

qual_desc = mrqseq (attr_desc, string);

Pointer (addr) to a qualification_descriptor.

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.

Changes the size of the space allocated by mrmalloc.

void*   mrrealloc (void* space, int size)

realloc_space = mrrealloc (space, size);

Pointer (void*) to space allocated which will be used by Empress RDBMS.

The space will remain allocated until freed by mrfree.

Make a second or subsequent attempt to retrieve a record from a table.

int   mrreget (addr retrieval_desc)

flag = mrreget (retrieval_desc);

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.

mrgetend should be called after one or more calls to mrreget to do cleaning up.

Make a second or subsequent attempt to retrieve the previous record from a table.

int   mrreprev (addr retrieval_desc)

flag = mrreprev (retrieval_desc);

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.

mrgetend should be called after one or more calls to mrreprev to do cleaning up.

Assign a NULL value to all attributes in a record.

msbool   mrsetnr (addr record_desc)

flag = mrsetnr (record_desc);

Return true if successful; false otherwise.

None.

Assign a NULL value to a given attribute in a record.

msbool   mrsetnv (addr record_desc, addr attr_desc)

flag = mrsetnv (record_desc, attr_desc);

Return true if successful; false otherwise.

None.

Allocate space to store an external format attribute value.

char*   mrspv (addr attr_desc)

space = mrspv (attr_desc);

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.

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.

Associate a given qualification with one or more records for sorted output; terminate the calling program on failure.

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)

retrieval_desc = mrsrtbegin (qual_desc, indicator,
                    record_desc_1, record_desc_2, ... , ADDRNIL,
                    attr_desc_1, type, attr_desc_2, type, .... , 
                    ADDRNIL);

Pointer (addr) to a retrieval_descriptor which is used by mrget.

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.

Initiates the start of an update operation of data segment.

msbool   mrsubbegin (addr record_desc)

flag = mrsubbegin (record_desc);

Return true if successful; false otherwise.

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.

Indicates the end of an update operation of data segment.

msbool   mrsubend (addr record_desc)

flag = mrsubend (record_desc);

Return true if successful; false otherwise.

None.

This routine retrieves a segment of data from a BULK or TEXT attribute.

long   mrsubgeti (mrrdes* rec, mrades* mra, addr* buktxtint,
                  long offset, long size)

flag = mrsubgeti (rec, mra, buktxtint, offset, size);

Returns -1 on failure.

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.

This routine performs a data segment update for BULK or TEXT data type. It overwrites the sections of data within the attribute.

long   mrsubputi (mrrdes* rec, mrades* mra, 
                  addr buktxtint, long offset)

flag = mrsubputi (rec, mra, buktxtint, offset);

Returns -1 on failure.

None.

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.

msbool   mrtadd (addr record_desc)

flag = mrtadd (record_desc);

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.

mraddend should be called to clean up after one or more calls to mrtadd.

Delete a record from a table; do not terminate if unsuccessful.

msbool   mrtdel (addr record_desc)

flag = mrtdel (record_desc);

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.

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.

Retrieve a record from a table; do not terminate calling program if unsuccessful.

int   mrtget (addr retrieval_desc)

flag = mrtget (retrieval_desc);

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 filemrerrno.h, and may be examined to determine the cause of failure.

mrgetend should be called to do cleaning up after one or more calls to mrtget.

Find the count, sum, average, minimum, or maximum value for an attribute; do not terminate the calling program if unsuccessful.

char*   mrtgfunc (char* function, 
                  addr retrieval_desc, 
                  addr record_desc, 
                  addr attr_desc)

value = mrtgfunc (function, retrieval_desc,
                  record_desc, attr_desc);

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.

mrgetend must be called to do cleaning up after mrgfunc, and the value found should be freed with mrfree.

Associate a given qualification with one or more records. Do not terminate the calling program if unsuccessful.

addr   mrtgtbegin (addr qual_desc, addr record_desc_1, 
                   [ ... addr record_desc_n,] (addr)0)

retrieval_desc = mrtgtbegin (qual_desc, record_desc_1,
                             record_desc_2, .... , ADDRNIL);

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.

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.

Open a data dictionary for internal access by the mr routines; do not terminate the calling program if unsuccessful.

msbool   mrtopdict (char* database_name, 
                    char mode)

flag = mrtopdict (database_name, mode);

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.

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.

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.

addr   mrtopen (char* database_name, 
                char* table_name, 
                char mode)

table_desc = mrtopen (database_name, 
                      table_name, mode);

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.

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.

Retrieve the previous record from a table; do not terminate calling program if unsuccessful.

int   mrtprev (addr retrieval_desc)

flag = mrtprev (retrieval_desc);

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.

mrgetend should be called to do cleaning up after one or more calls to mrtprev.

Update a record, indicating success or failure of the update. mrtput should be used when an attribute has a unique index on it.

msbool   mrtput (addr new_rec_desc, 
                 addr old_rec_desc)

flag = mrtput (new_rec_desc, old_rec_desc);

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.

The original record_descriptor must point to a record which has been retrieved by calls to mrgetbegin and mrget, otherwise mrtput will fail.

Compare an attribute value to another attribute value; report if unsuccessful.

addr   mrtqatr (char* operator, 
                addr attr_desc_1, 
                addr attr_desc_2)

qual_desc = mrtqatr (operator, attr_desc_1,
                     attr_desc_2);

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.

The two attributes compared must be compatible, otherwise mrtqatr will fail.

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.

addr   mrtqcon (char* operator, 
                addr attr_desc, 
                addr var_ptr)

qual_desc = mrtqcon (operator, attr_desc, 
                     &var);

qual_desc = mrtqcon (operator, attr_desc, 
                     mrcvt (attr_desc, string));

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.

None.

Compare an attribute value to a pattern; report if unsuccessful.

addr   mrtqmch (char* operator, 
                addr attr_desc, 
                char* pattern)

qual_desc = mrtqmch (operator, attr_desc, 
                     pattern);