# CHAPTER 6: Manual Pages

## 6.1 mf Routines

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

  mfacls | mfadd |
  mfcall | mfchka | mfcln
  mfclos | mfcomp | mfcpi
  mfdel |  |
  mferrt |  |
  mfget | mfgetb | mfgete
  mfgetv | mfgtvi |
  mfigta | mfinit |
  mfopen | mfoper |
  mfprev | mfprte | mfptvi
  mfptvs | mfput | mfputi |
  mfqand | mfqatr | mfqc
  mfqci | mfqieq | mfqmch
  mfqnot | mfqnul | mfqor
  mfqrg | mfqrgi | mfqseq
  mfrget | mfrprv |
  mfsetn | mfsrtb | mfstop
  mftrcm | mftrcn | mftrst

## mfacls

Description | Closes all tables and de-allocate all existing `mf`-related variables. This procedure is intended for use on terminating a program due to an error condition or at rapped interrupt.
Synopsis | `subroutine mfacls`
Usage | `call mfacls`
Warning | Indiscriminate use of this procedure defeats all the built-in error checking mechanisms of the `mf` routines.

## mfadd

Description | Inserts a record into a given table. The record should have been constructed using `mfptvs`, `mfptvi` and `mfput`.
Synopsis |
    logical function		mfadd(table)

    character*(*)			table
Usage | `flag = mfadd (table)`
`flag` | Indicator (logical) to show success or failure of the routine.
`table` | The name of the table (a character constant or character string).
Returns | `.TRUE.` if successful; `.FALSE.`if unsuccessful.
Warning | The table must be opened in deferred or update mode or the add will fail.

## mfcall

Description | Executes a Query Language command for the named database from a Fortran program.
Synopsis |
    integer*4 function	mfcall (database,command)

    character(*)*   database,command
Usage | `code = mfcall (database, command)`
`code` | Indicator of the status of the command.
`database` | The name of an Empress database (a character constant or character string).
`command` | A Query Language command (a character constant or character string).
Returns | The exit status of the `command`; 0 indicates the command was successful and any other value indicates failure.

## mfchka

Description | Checks whether a particular attribute is in an opened table.
Synopsis |
    logical function		mfchka(attribute)

    character*(*)			attribute
Usage | `flag = mfchka (attribute)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute being checked (a character constant or character string).
Returns | `.TRUE.` if the attribute exists;`.FALSE.` if it does not.

## mfcln

Description | Cleans up after `mf` routines.
Synopsis | `subroutine mfcln`
Usage | `call mfcln`
Returns | None.

## mfclos

Description | Closes a table after all operations have been performed on it.
Synopsis |
    subroutine			mfclos (table)

    character*(*)		table
Usage | `call mfclos (table)`
`table` | The name of an opened table (a character constant or character string).
Returns | None.

## mfcomp

Description | Finds whether a constant is equal to, less than, or greater than an attribute value.
Synopsis |
    integer*4 function mfcomp (attribute, value)
    character*(*)   attribute, value
Usage | `result = mfcomp (attribute, value)`
`result` | The result of the comparison.
`attribute` | The name of an attribute (a character constant or character string).
`value` | The constant the attribute is to be compared with,in external representation (a character constant or character string).
Returns | `0` if the constant is equal to the attribute value, `1` if the attribute value is greater than the constant, and `-1` if the attribute value is less than the constant.

## mfcpi

Description | Copies the internal representation of an attribute value to a variable.
Synopsis |
    logical function mfcpi (attribute, variable)

    character*(*) attribute

    ANYTYPE    variable
Usage | `flag = mfcpi (attribute, variable)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute (a character constant or character string).
`variable` | A variable of type suitable for storing the internal representation of the attribute value.
Returns | `.TRUE.` if value is not NULL, `.FALSE.` otherwise.
Warnings | Using this routine results in non-portable code.

## mfdel

Description | Deletes a record from a table.
Synopsis |
    logical function mfdel (table)

    character*(*)  table
Usage | `flag = mfdel (table)`
`flag` | Indicator (logical) to show success or failure of the routine.
`table` | The name of a table (a character constant or character string).
Returns | `.TRUE.` if successful, `.FALSE.` if unsuccessful.
Notes | The record to be deleted must first have been specified in a call to `mfgetb` and then retrieved by a successful call to `mfget`.

## mferrt

Description | Prevents the normal failures from terminating the calling program.
Synopsis |
    subroutine mferrt (value)

    integer*4  value
Usage | `call mferrt (value)`
`value` | `0` terminate on failure non-zero continue on failure
Warnings | The `msfer.h` header file must be used instead of `msf.h`.

## mfget

Description | Retrieves the next record from a table. Successive calls attempt to retrieve different records.
Synopsis |
    integer*4 function mfget
Usage | `flag = mfget`
`flag` | Indicator (logical) to status of the routine.`1` if successful; `0` on end of file; and `-1` if the record is locked.
Notes | `mfgetb` must be called once before any calls to `mfget` are made. `mfgete` must be called after one or more calls to `mfget` to do cleaning up.

## mfgetb

Description | Initializes a retrieval from one or more tables.
Synopsis |
    logical function mfgetb (table_1, [ ...table_n], '\0')

    character*(*)  table_1,... table_n
Usage | `flag = mfgetb (table_1, table_2, ... table_n, '\0')`
`flag` | Indicator (logical) to show success or failure of the routine.
`table` | The name of an opened table (a character constant or character string).
`'\0'` | Terminates the list of tables.
Returns | `.TRUE.` if successful, `.FALSE.` if unsuccessful.
Notes | Nested calls to `mfgetb` must be set up carefully. Possible problems are explained fully in Chapter 4.

## mfgete

Description | Cleans up after retrieving records from a table.
Synopsis |
    subroutine  mfgete
Usage | `call mfgete`
Returns | None.
| Failure to call `mfgete` after retrieving records may affect future record retrievals. Possible problems are explained fully in Chapter 4.

## mfgetv

Description | Retrieves the value (external representation) of an attribute from a record into a variable.
Synopsis |
    integer*4 function mfgetv (variable, length, attribute)

    integer*4    length

    character*(*)   variable, attribute
Usage | `vlen = mfgetv (variable, length, attribute)`
`vlen` | The actual length of the external representation. The length of the external representation of the attribute value.If `vlen` is greater than `length`, only part of the attribute value will have been retrieved.
`variable` | The variable to contain the value. It may be a character string or a character array. Note that the variable will be filled with trailing blanks; it is not NULL-terminated.
`length` | The length of the variable.
`attribute` | The name of an attribute (a character constant or character string).
Notes | It will be necessary to call `mfgetv` again with a longer variable to retrieve the full value.

## mfgtvi

Description | Retrieves the value of an attribute from a record as an integer.
Synopsis |
    integer*4 function mfgtvi (attribute)

    character*(*)   variable, attribute
Usage | `value = mfgtvi (attribute)`
`value` | The integer variable to contain the value.
`attribute` | The name of an attribute (a character constant or character string). The attribute value as an integer.
Warnings | The calling program will be terminated if the attribute value cannot be converted to an integer.

## mfigta

Description | Finds the name of an attribute given its number in a table.
Synopsis |
    integer*4 function mfigta (variable, length, table, number)

    integer*4    length, number

    character*(*)   variable, table
Usage | `vlen = mfigta (variable ,length, table, number)`
`vlen` | The actual length of the attribute name.
`variable` | The variable to contain the attribute name.
`length` | The length of the variable.
`table` | The name of the table (a character constant or character string).
`number` | The number of the attribute in the table.
Returns | The length of the attribute name (`0` if there is no attribute of that number in the table).
Notes | If `vlen` is greater than `length`, only part of the attribute name will have been retrieved. It will be necessary to call `mfigta` again with a longer variable to retrieve the full name.

## mfinit

Description | Initializes for `mf` routines.
Synopsis |
    subroutine mfinit
Usage | `call mfinit`
Returns | None.

## mfopen

Description | Opens and locks a table for use with the Empress Database Manipulation Language Interface (`mf` routines).
Synopsis |
    logical function mfopen (directory, table, mode)

    character*(*)  directory, table, mode
Usage | `flag = mfopen (directory, table, mode)`
`flag` | Indicator (logical) to show success or failure of the routine.
`directory` | The name of the database directory (a character constant or character string).
`table` | The name of the table (a character constant or character string).
`mode` | The string '`r`', '`u`' or '`d`' for read, update,or deferred, respectively. The deferred mode opens the table for update but places a read lock when data is retrieved; this read lock is replaced by an update lock when an `mfdel` or `mfput` is executed.
Returns | `.TRUE.` if successful, `.FALSE.`if unsuccessful.
Notes | If `mfopen` is unsuccessful, the program calling is terminated.
Warnings | It is not recommended to specify the current directory when calling `mfopen` (i.e., run applications in the database directory), due to the danger of damaging the files in the database when new files are created. If read mode is specified and the user has no read permission on the table, or if update mode is specified and the user has no read and write permission on the table, `mfopen` will fail.

## mfoper

Description | Find the error code set by failure of one of the other `mf` routines.
Synopsis |
    integer*4 function mfoper
Usage | `code = mfoper`
`code` | The integer error code.
Integer Error Codes
No | `Message`
`1` | Invalid table name.
`2` | Table already exists.
`3` | Table does not exist.
`4` | No read permission on table.
`5` | No read/write permission on table.
`6` | Database/table lock busy.
`7` | Operation invalid on view.
`8` | Invalid definition for view.
`9` | Recursive definition for view.
`10` | Not a database.
`11` | Invalid attribute name.
`12` | Attribute already exists.
`13` | Attribute does not exist.
`14` | Invalid data type/parameters.
`15` | Invalid index name.
`16` | Null value for attribute.
`17` | Duplicate value for attribute.
`18` | Too many duplicate values.
`19` | Bad value conversion for attribute.
`20` | No privilege for table.
`21` | No update privilege on attribute.
`22` | No create table privilege.
`23` | Invalid operator/function.
`24` | Incompatible attributes.
`25` | Invalid pattern.
`26` | Invalid range.

## mfprev

Description | Retrieves the previous record from a table. Successive calls attempt to retrieve different records.
Synopsis |
    integer*4 function mfprev
Usage | `flag = mfprev`
`flag` | Indicator (logical) to status of the routine. `1` if successful; `0` on end of file; and `-1` if the record is locked.
Notes | `mfgetb` must be called once before any calls to mfprev are made. `mfgete` must be called after one or more calls to `mfprev` to do cleaning up.

## mfprte

Description | Print an error message depending on a previous error; terminate the calling program.
Synopsis |
    subroutine  mfprte
Usage | `call mfprte`

## mfptvi

Description | Assigns an integer value to a given attribute in a record.
Synopsis |
    logical function mfptvi (attribute, value)

    character*(*) attribute

    integer*4 value
Usage | `flag = mfptvi (attribute, value)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute (a character constant or character string).
`value` | The integer value to be assigned to the attribute.
Returns | `.TRUE.` if successful; `.FALSE.` if unable to assign the value to the attribute.

## mfptvs

Description | Assigns an external format value to a given attribute in a record.
Synopsis |
    logical function mfptvs (attribute, value)

    character*(*)  attribute, value
Usage | `flag = mfptvs (attribute, value)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute (a character constant or character string).
`value` | The value (in external format) to be assigned to the attribute.
Returns | `.TRUE.` if successful; `.FALSE.` if unable to assign the value to the attribute.

## mfput

Description | Updates a record.
Synopsis |
    logical function mfput (table)

    character*(*)  table
Usage | `flag = mfput (table)`
`flag` | Indicator (logical) to show success or failure of the routine.
`table` | Variable containing the name of the table.
Returns | `.TRUE.` if successful; `.FALSE.` if unsuccessful.
Warnings | The record to be replaced must be first obtained by calls to `mfgetb` and `mfget`, otherwise `mfput` will fail.

## mfputi

Description | Assigns a value (internal representation) to a given attribute in a record.
Synopsis |
    logical function mfputi (attribute, variable)

    character*(*)  attribute

    anytype    variable
Usage | `flag = mfputi (attribute, variable)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute (a character constant or character string).
`variable` | A variable containing a value in Empress internal format to be assigned to the attribute.
Returns | `.TRUE.` if successful; `.FALSE.` if unable to assign the value to the attribute.
Warnings | The use of this routine results in non-portable code. The variable type must be compatible with the Empress internal representation of the attribute in question, or a conversion error will result.

## mfqand

Description | Performs an `AND` operation on the top two values of the stack holding qualifications created by calls to the `mfq` routines.
Synopsis |
    subroutine  mfqand
Usage | `call mfqand`
Warnings | There must be at least two qualifications on the stack, or `mfqand` will fail.

## mfqatr

Description | Compares an attribute value to another attribute value and stores result on a stack.
Synopsis |
    logical function mfqatr (operator, attribute_1, attribute_2)

    character*(*)  attribute_1, attribute_2

    character*(*)  operator
Usage | `flag = mfqatr (operator, attribute_1, attribute_2)`
`flag` | indicator (logical) to show success or failure of the routine.
`operator` | One of the following: ">", "<", "=", "<>", "<=" or "!=". For negation, either tilde (~) or exclamation mark (!) may be used.
`attribute_1` | The name of the first attribute (a character constant or character string).
`attribute_2` | The name of the second attribute (a character constant or character string).
Warnings | The two attributes compared must be compatible.

## mfqc

Description | Compares an attribute value to a constant and stores the result on a stack.
Synopsis |
    logical function mfqc (operator, attribute, value)

    character*(*)  attribute, value

    character*(*)  operator
Usage | `flag = mfqc (operator, attribute, value)`
`flag` | Indicator (logical) to show success or failure of the routine.
`operator` | One of the following: "<", ">", "=", "<>", or "!=". For negation, either tilde (~) or exclamation mark (!) may be used.
`attribute` | The name of the attribute (a character constant or character string).
`value` | The value the attribute is to be compared to.
Notes | A "Conversion Error" message will be printed if the attribute and value are not compatible.

## mfqci

Description | Compares an attribute value to a constant in internal representation and stores the result on a stack.
Synopsis |
    logical function mfqci (operator, attribute, variable)

    character*(*)  attribute, operator

    ANYTYPE    variable
Usage | `flag = mfqci (operator, attribute, variable)`
`flag` | Indicator (logical) to show success or failure of the routine.
`operator` | One of the following: ">", "<", "=", "<>", "=", or "!=". For negation, either tilde (~) or exclamation mark (!) may be used.
`attribute` | The name of the attribute (a character constant or character string).
`variable` | A variable containing the value the attribute is to be compared to, in internal format.
Warnings | Using this routine results in non-portable code. A "Conversion Error" message will be printed if the attribute and value are not compatible.

## mfqieq

Description | Compares an attribute value to an integer using an "equals" operator and stores the result on a stack.
Synopsis |
    subroutine   mfqieq ( attribute, variable)

    character*(*)  attribute

    integer*4   variable
Usage | `call mfqieq (attribute, variable)`
`attribute` | The name of the attribute (a character constant or character string).
`variable` | An integer variable containing the value.
Warnings | If the attribute and value are not compatible, the calling program is terminated and a "Conversion Error" message printed.

## mfqmch

Description | Compares an attribute value to a pattern, and stores the result on a stack.
Synopsis |
    logical function mfqmch (operator, attribute, pattern)

    character*(*)  operator, attribute, pattern
Usage | `flag = mfqmch ( operator, attribute, pattern)`
`flag` | Indicator (logical) to show success or failure of the routine.
`operator` | One of the following: `MATCH`, `SMATCH`, `!MATCH`, or `!SMATCH`. For either negation, either tilde (~) or exclamation mark (!) may be used.
`attribute` | Name of the attribute (a character constant or character string).
`pattern` | Variable containing a pattern.

## mfqnot

Description | Reverses the sense of (negate) the top qualification on the stack holding qualifications created by the `mfq` routines.
Synopsis |
    subroutine  mfqnot
Usage | `call mfqnot`
Warnings | There must be at least one qualification on the stack or `mfnot` will fail.

## mfqnul

Description | Compares an attribute value to NULL, and store the result on a stack.
Synopsis |
    logical function mfqnul (operator, attribute)

    character*(*)  operator, attribute
Usage | `flag = mfqnul (operator, attribute)`
`flag` | Indicator (logical) to show success or failure of the routine.
`operator` | One of "=" or "!=". For negation,either tilde (~) or exclamation mark (!) may be used.
`attribute` | The name of attribute (a character constant or character string).

## mfqor

Description | Performs an `OR` operation on the top two elements of the stack holding qualifications created by the `mfq` routines.
Synopsis |
    subroutine   mfqor
Usage | `call mfqor`
Warnings | There must be at least two qualifications on the stack or `mfqor` will fail.

## mfqrg

Description | Compares an attribute value to a given range of values.
Synopsis |
    logical function mfqrg (attribute, lower_value,
               indicator upper_value, indicator)

    character*(*)  attribute, lower_value, upper_value

    character*(*)  indicator
Usage | `flag = mfqrg (attribute, lower, indicator, upper, indicator)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute (a character constant or character string).
`indicator` | The string '`i`' or '`e`', indicating the preceding value is INCLUSIVE or EXCLUSIVE, respectively.
`lower` | The lower limit of the range (a character constant or character string).
`upper` | The upper limit of the range (a character constant or character string).

## mfqrgi

Description | Compares an attribute value to a given range of values.
Synopsis |
    logical function mfqrgi (attribute, lower, indicator,
                upper, indicator)

    character*(*)  attribute, indicator

    ANYTYPE   upper, lower
Usage | `flag = mfqrgi (attribute, lower, indicator, upper, indicator)`
`flag` | Indicator (logical) to show success or failure of the routine.
`attribute` | The name of the attribute (a character constant or character string).
`indicator` | The string '`i`' or '`e`', indicating the preceding value is INCLUSIVE or EXCLUSIVE, respectively.
`lower` | The lower limit of the range in internal format.
`upper` | The upper limit of the range in internal format.
Notes | Using this routine results in non-portable code.

## mfqseq

Description | Compares an attribute value to a character string using an "equals" operator.
Synopsis |
    subroutine   mfqseq (attribute, value)

    character*(*)attribute, value
Usage | `call mfqseq (attribute, string)`
`attribute` | The name of the attribute (a character constant or character string).
`string` | Character string variable containing the value.
Warnings | If the string and the attribute are incompatible, the calling program is terminated and a "Conversion Error" message printed.

## mfrget

Description | Attempts to retrieve the next record from a table. Successive calls attempt to retrieve the same record.
Synopsis |
    integer*4 function  mfrget
Usage | `flag = mfrget`
`flag` | Indicator (logical) to status of the routine.
Returns | `1` if successful; `0` on end of file; and `-1` if the record is locked.
Notes | `mfgetb` must be called once before any calls to `mfrget` are made. `mfgete` must be called after one or more calls to `mfrget` (or `mfget`) to do cleaning up.

## mfrprv

Description | Attempts to retrieve the previous record from a table. Successive calls attempt to retrieve the same record.
Synopsis |
    integer*4 function  mfrprv
Usage | `flag = mfrprv`
`flag` | Indicator (logical) to status of the routine.
Returns | `1` if successful; `0` on end of file; and `-1` if the record is locked.
Notes | `mfgetb` must be called once before any calls to `mfrprv` are made. `mfgete` must be called after one or more calls to `mfrprv` (or `mfprev`) to do cleaning up.

## mfsetn

Description | Assigns a NULL value to all attributes in a record.
Synopsis |
    subroutine  mfsetn (table)

    character*(*)  table
Usage | `call mfsetn (table)`
`table` | The name of an opened table (a character constant or character string).
Returns | None.

## mfsrtb

Description | Associates a given qualification with one or more records, and indicates how retrieved values should be sorted.
Synopsis |
    logical function mfsrtb (indicator, table_1,
         [... table_n], '\0', attribute, type,
         [attribute, type, ...] '\0')

    character*(*)  indicator, table_1, ... table_n, type,
         attribute
Usage |
    flag = mfsrtb (table_1, table_2, ... table_n, '\0',
           attribute_1, type, attribute_2, type,..., '\0')
`flag` | Indicator (logical) to show success or failure of the routine.
`indicator` | The string '`u`' or '`s`', to denote a unique or non-unique sort, respectively.
`table` | The name of an opened table (a character constant or NULL-terminated character string).
`'\0` | Terminates lists of names.
`attribute` | The name of an attribute to be sorted on (a character constant or NULL-terminated character string).
`type` | The string `ASCENDING` or `DESCENDING`, denoting the sort type for the preceding attribute. `ASCENDING` and `DESCENDING` may be abbreviated to '`a`' and '`d`'.
Returns | `.TRUE.` if successful; `.FALSE.` if not all appropriate records could be accessed.
Warnings | Nested calls to `mfsrtb` must be set up carefully.Possible problems are explained fully in Chapter 4.

## mfstop

Description | Cleans up after `mf` routines and stops the program.
Synopsis |
    subroutine  mfstop
Usage | `call mfstop`
Returns | None.

## mftrcm

Description | Commits a transaction; returns the database to its pre-transaction state.
Synopsis |
    logical function mftrcm
Usage | `flag = mftrcm`
`flag` | Indicator (logical) to show success or failure.
Returns | `.TRUE.` if successful; `.FALSE.` if not.

## mftrcn

Description | Cancels a transaction; returns the database to its pre-transaction state.
Synopsis |
    logical function mftrcn
Usage | `flag = mftrcn`
`flag` | Indicator (logical) to show success or failure.
Returns | `.TRUE.` if successful; `.FALSE.`if not.

## mftrst

Description | Starts a transaction.
Synopsis |
    logical function mftrst
Usage | `flag = mftrst`
`flag` | Indicator (logical) to show success or failure.
Returns | `.TRUE.` if successful; `.FALSE.` if not. Failure usually means a transaction is already in progress.

## 6.2 Fortran Precompiler

The following are the manual pages for the Standard Interface routines in alphabetical order.

  empbatch |  |
  empcc | empcmd |
  empecc | empef77 | empesql