# CHAPTER 4: Manual Pages

This chapter provides the manual pages for the following Empress internal routines in alphabetical order:

- cvaf
- cvai
- cval
- cvfx
- cvix
- cvlx
- dtalloc
- dtgetex
- dtgetgex
- dtgetgin
- dtgetin
- dtputex
- dtputgex
- dtputgin
- dtputin
- dtudferr
- dtxnuerr
- dtxnunul
- dtxnuval
- spfree
- strfree
- strsave

#

cvaf

DESCRIPTION | Convert a string to `FLOAT`.
SYNOPSIS | This is an Empress internal function that should be declared as extern in the function that invokes it.
    msbool   cvaf (&f, string);
             float  f;
             char   *string;
USAGE | `cvaf (&f, string);`
`f` | The `FLOAT` value to be converted from a string of digits.
`string` | A pointer (char *) to a character string.
RETURNS | 1 If successful. 0 If unsuccessful.
WARNINGS | None.
EXAMPLE |
    #include <../include/usrfns.h>

    char   *udf(argc, argv)
           int      argc;
           char     *argv[];
    {
       extern msbool cvaf();
       float f;
          .
          .

       cvaf (&f, argv[1]);
          .
          .
    }

#

cvai

DESCRIPTION | Convert a string to `INTEGER`.
SYNOPSIS | This is an Empress internal function that should be declared as extern in the function that invokes it.
    msbool   cvai (&i, string);
              int  i;
              char *string;
USAGE | `cvai (&i, string);`
`i` | The `INTEGER` value to be converted from a string of digits.
`string` | A pointer (char *) to a character string.
RETURNS | 1 If successful. 0 If unsuccessful.
WARNINGS | None.
EXAMPLE |
    #include <../include/usrfns.h>

    char   *udf(argc, argv)
           int      argc;
           char     *argv[];
    {
       extern msbool cvai();
       int  i;
          .
          .

       cvai (&i, argv[1]);
          .
          .
    }

#

cval

DESCRIPTION | Convert a string to `LONGINTEGER`.
SYNOPSIS | This is an Empress internal function that should be declared as extern in the function that invokes it.
    msbool   cval (&l, string);
              long   l;
              char   *string;
USAGE | `cval (&l, string);`
`l` | The `LONGINTEGER` value to be converted from a string of digits.
`string` | A pointer (char *) to a character string.
RETURNS | 1 If successful. 0 If unsuccessful.
WARNINGS | None.
EXAMPLE |
    #include <../include/usrfns.h>

    char   *udf(argc, argv)
           int      argc;
           char     *argv[];
    {
       extern msbool cval();
       long  l;
          .
          .

       cval (&l, argv[1]);
          .
          .
    }

#

cvfx

DESCRIPTION | Convert a floating point value to a string.
SYNOPSIS | This is an Empress internal function that should be declared as extern in the function that invokes it.
    char   *cvfx (string, f);
           float  f;
           char   *string;
USAGE | `cvfx (string, f);`
`f` | The `FLOAT` value to be converted to a character string.
`string` | A pointer (char *) to a character string.
RETURNS | None.
WARNINGS | None.
EXAMPLE |
    #include <../include/usrfns.h>

    char   *udf(argc, argv)
           int      argc;
           char     *argv[];
    {
       extern char *cvfx();
       char str[15];
       float f;
          .
          .

       f = 123.456;
       cvfx (str, f);
       return(str);
    }

#

cvix

DESCRIPTION | Convert a `INTEGER` value to a string.
SYNOPSIS | This is an Empress internal function that should be declared as extern in the function that invokes it.
    char   *cvix (string, i);
           int    i;
           char   *string;
USAGE | `cvix (string, i);`
`i` | The `INTEGER` value to be converted to a character string.
`string` | A pointer (char *) to a character string.
RETURNS | None.
WARNINGS | None.
EXAMPLE |
    #include <../include/usrfns.h>

    char   *udf(argc, argv)
           int      argc;
           char     *argv[];
    {
       extern char *cvix();
       char str[15];
       int  i;
          .
          .

       i = 123;
       cvix (str, i);
       return(str);
    }

#

cvlx

DESCRIPTION | Convert a `LONGINTEGER` value to a string.
SYNOPSIS | This is an Empress internal function that should be declared as extern in the function that invokes it.
    char   *cvlx (string, l);
           long   l;
           char   *string;
USAGE | `cvlx (string, l);`
`l` | The `LONGINTEGER` value to be converted to a character string.
`string` | A pointer (char *) to a character string.
RETURNS | None.
WARNINGS | None.
EXAMPLE |
    #include <../include/usrfns.h>

    char   *udf(argc, argv)
           int      argc;
           char     *argv[];
    {
       extern char *cvlx();
       char str[15];
       long l;
          .
          .

       l = 123456;
       cvlx (str, l);
       return(str);
    }

#

dtalloc

DESCRIPTION | Allocate space for performing internal calculations. This routine is generally used to allocate space that will be used for accumulating results for aggregate functions. `dtalloc()` is defined in `usrfns.h` as: `# define dtalloc(n) spmget(n)`
SYNOPSIS |
    space = dtalloc(n);

       addr    space;
       int     n;
USAGE | `opr->dtxrwksp = dtalloc(n);`
`n` | Size of space (integer) to be allocated for internal calculations in Empress
`opr->dtxrwksp` | Pointer (addr) to the space allocated by dtalloc().
RETURNS | Pointer (`addr`) to the space allocated for performing internal calculations.
WARNINGS | The space allocated by `dtalloc()` must be freed by calling `spfree()`.
EXAMPLE |
    typedef struct
    {
          double n;
          double
          xsum;
          double x2sum;
    } stats;

    static   msbool   udf( opr, param )
             dtxr     *opr;
             addr     param;
    {
             .
             .
       opr->dtxrwksp = dtalloc (sizeof(stats));
       return (true);
             .
             .
    }

#

dtgetex

DESCRIPTION | Convert a value to external format from file format in Empress. This routine is typically used to convert function arguments to the format that is required by the C routine.
SYNOPSIS |
    char   *dtgetex (dtp, *val);
           dtpar    *dtp;
           addr     *val;
USAGE | `dtgetex(opd->dtxddtp, *(opd->dtxdival));`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`*(opd->dtxdival)` | Pointer to the value.
RETURNS | None.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in external format. This value is set by the call to `dtgetex` if successful.
`extern long dtzex;` | The storage length of the value in external format if successful.
WARNINGS | None.
EXAMPLE | `dtgetex(opd->dtxddtp, *(opd->dtxdival));`

#

dtgetgex

DESCRIPTION | Convert a value to generic external format in Empress from file format. This routine is typically used to convert function arguments to the format that is required by the C routine.
SYNOPSIS |
    char   *dtgetgex (dtp, *val);
           dtpar    *dtp;
           addr     *val;
USAGE | `dtgetgex(opd->dtxddtp, *(opd->dtxdival));`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`*(opd->dtxdival)` | Pointer to the value.
RETURNS | None.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in generic external format. This value is set by the call to `dtgetgex` if successful.
`extern long dtzex;` | The storage length of the value in generic external format if successful.
WARNINGS | None.
EXAMPLE | `dtgetgex(opd->dtxddtp, *(opd->dtxdival));`

#

dtgetgin

DESCRIPTION | Convert a value to generic internal format in Empress from file format. This routine is typically used either to convert function arguments or to convert values to the appropriate return data type.
SYNOPSIS |
    char   *dtgetgin (dtp, *val);
           dtpar    *dtp;
           addr     *val;
USAGE | `dtgetgin (opd->dtxddtp, *(opd->dtxdival));`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`*(opd->dtxdival)` | Pointer to the value.
RETURNS | None.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in generic internal format. This value is set by the call to `dtgetgin` if successful.
`extern long dtzin;` | The storage length of the value generic internal format if successful.
WARNINGS | None.
EXAMPLE | `dtgetgin(opd->dtxddtp, *(opd->dtxdival));`

#

dtgetin

DESCRIPTION | Convert a value to internal format in Empress from file format. This routine is typically used to convert function arguments to the format that is required by the C routine.
SYNOPSIS |
    char   *dtgetin (dtp, *val);
           dtpar    *dtp;
           addr     *val;
USAGE | `dtgetin (opd->dtxddtp, *(opd->dtxdival));`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`*(opd->dtxdival)` | Pointer to the value.
RETURNS | None.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in internal format. This value is set by the call to `dtgetin` if successful.
`extern long dtzin;` | The storage length of the value in internal format if successful.
WARNINGS | None.
EXAMPLE | `dtgetin (opd->dtxddtp, *(opd->dtxdival));`

#

dtputex

DESCRIPTION | Convert a value to file format in Empress from external format. This is typically used to convert values to the appropriate format of the function's return data type.
SYNOPSIS |
    char   *dtputex (dtp, *ex);
           dtpar    *dtp;
           char     *ex;
USAGE | `dtputex (opd->dtxddtp, *ex);`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`*ex` | Pointer to the value in external format.
RETURNS | Pointer to an error message string if the conversion fails. CHARNIL if successful.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in file format. This value is set by the call to `dtputex` if successful.
`extern long dtzfile;` | The storage length of the value in file format if successful.
WARNINGS | None.
EXAMPLE | `dtputex(opd->dtxddtp, *(opd->dtxdival));`

#

dtputgex

DESCRIPTION | Convert a value to file format in Empress from generic external format. This function is typically used to convert a value to the appropriate return data type.
SYNOPSIS |
    char   *dtputgex (dtp, *ex);
           dtpar    *dtp;
           char     *ex;
USAGE | `dtputgex (opd->dtxddtp, *ex);`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`*ex` | Pointer to the value in generic external format.
RETURNS | Pointer to an error message string if the conversion fails. CHARNIL if successful.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in file format. This value is set by the call to `dtputgex` if successful.
`extern long dtzfile;` | The storage length of the value in file format if successful.
WARNINGS | None.
EXAMPLE | `dtputgex(opd->dtxddtp, *(opd->dtxdival));`

#

dtputgin

DESCRIPTION | Convert a value to file format in Empress from generic internal format. This routine is used to convert function arguments or return values to the appropriate data type.
SYNOPSIS |
    char   *dtputgin (dtp, in);
           dtpar    *dtp;
           addr     in;
USAGE | `dtputgin (opd->dtxddtp, in);`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`in` | Pointer to the value in generic internal format.
RETURNS | Pointer to an error message string if the conversion fails. CHARNIL if successful.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in file format. This value is set by the call to `dtputgin` if successful.
`extern long dtzfile;` | The storage length of the value in file format if successful.
WARNINGS | None.
EXAMPLE | `dtputgin (opd->dtxddtp, *(opd->dtxdival));`

#

dtputin

DESCRIPTION | Convert a value to file format in Empress from internal format. This routine is used to convert function arguments.
SYNOPSIS |
    char   *dtputin (dtp, in);
           dtpar    *dtp;
           addr     in;
USAGE | `dtputin (opd->dtxddtp, in);`
`opd->dtxddtp` | Pointer to a structure of type `dtpar`. The `dtpar` structure defines the data type of the value.
`in` | Pointer to the value in internal format.
RETURNS | Pointer to an error message string if the conversion fails. `CHARNIL` if successful.
ASSIGNS |
`extern char *dtval;` | A pointer to the value in file format. This value is set by the call to `dtputin` if successful.
`extern long dtzfile;` | The storage length of the value in file format if successful.
WARNINGS | None.
EXAMPLE | `dtputin (opd->dtxddtp, *(opd->dtxdival));`

#

dtudferr

DESCRIPTION | This routine is used to return a user-defined error message to the calling program when an error condition is encountered. For each record or aggregate that generates an error, the format of the error message will be:
       *** User Error *** 'message' - skipping record
SYNOPSIS |
    dtudferr (string)
        char *string;
USAGE | `dtudferr (string);`
`string` | Pointer (`char *`) to a constant in external format (i.e., a string).
RETURNS | None.
ASSIGNS | None.
WARNINGS | The UDF must return `false` for this routine to be invoked. A result value should not be assigned if the function returns `false`.
EXAMPLE |
    {
          .
          .
       dtudferr("error in function argument");
       return(false);
    }

#

dtxnuerr

DESCRIPTION | This routine is used to determine if the value of an argument to a function evaluates to an error condition. `dtxnuerr` is defined by the following statements in `usrfns.h`:
       # define dtxnuerr(n)     ((n) & DTXERR)
       # define DTXERR          0100
The `dtxdnull` field of the `dtxd` structure can be tested with this routine to determine whether an error condition (typically due to an expression failure) exists.
SYNOPSIS |
    dtxnuerr (n)

       # define dtxnuerr (n)    ((n) & DTXERR)
`n` | `dtxd->dtxdnull` argument value type field in 'dtxd' structure - may be real value, null or error.
USAGE |
    if (dtxnuerr (opd->dtxdnull) == DTXERR)
    {
       .
       .
    }
`opd->dtxdnull` | `opd` is a pointer to a structure of type `dtxd`. `dtxdnull` is a field in this structure which indicates whether the argument value for a function is a valid result, a null, or an error.
`DTXERR` | is defined in the file `usefns.h` as:
    # define   DTXERR   0100
RETURNS | 0100 If an argument value evaluates to an error. 0 If an argument value does not evaluate to an error.
ASSIGNS | None.
WARNINGS | The `dtxinput` flag in the DT Function Table (`usrxtab`) for the function must be set to `NNEY` or `NYEY` for this function to detect an error condition.
EXAMPLE |
    if (dtxnuerr (opd->dtxdnull) == DTXERR)
    {
       dtudferr ("function argument cannot be evaluated");
       return (false);
    }

#

dtxnunul

DESCRIPTION | This routine is used to determine if the value of an argument to a function evaluates to a null. `dtxnunul` is defined by the following statements in `usrfns.h`:
       # define dtxnunul(n)     ((n) & DTXNULL)
       # define DTXNULL         020
The `dtxdnull` field of the `dtxd` structure can be tested with this routine to determine whether an null value (as the result of an expression or a null attribute value) exists.
SYNOPSIS |
    dtxnunul (n)

       # define dtxnunul (n)    ((n) & DTXNULL)
`n` | `dtxd->dtxdnull` argument value type field in 'dtxd' structure - may be real value, null or error.
USAGE |
    if (dtxnunul (opd->dtxdnull) == DTXNULL)
    {
       .
       .
    }
`opd->dtxdnull` | `opd` is a pointer to a structure of type `dtxd`. `dtxdnull` is a field in this structure which indicates whether the argument value for a function is a valid result, a null, or an error.
`DTXNULL` | is defined in the file `usefns.h` as:
    # define   DTXNULL   020
RETURNS | 020 If an argument value evaluates to null. 0 If an argument value does not evaluate to null.
ASSIGNS | None.
WARNINGS | The `dtxinput` flag in the DT Function Table (`usrxtab`) for the function must be set to `NYEN` or `NYEY` for this function to detect a null.
EXAMPLE |
    if (dtxnunul (opd->dtxdnull) == DTXNULL)
    {
       opr->dtxrresult->dtxdnull = DTXOPDNUL;     /* return a null value */
       return (true);
    }

#

dtxnuval

DESCRIPTION | This routine is used to determine if the value of an argument to a function evaluates to a valid, not-null result. `dtxnuval` is defined by the following statements in `usrfns.h`:
       # define dtxnuval(n)     ((n) & DTXVALUE)
       # define DTXVALUE        040
The `dtxdnull` field of the `dtxd` structure can be tested with this routine to determine whether a valid not-null argument value has been passed to a function.
SYNOPSIS |
    dtxnuval (n)

       # define dtxnuval (n)    ((n) & DTXVALUE)
`n` | `dtxd->dtxdnull` argument value type field in 'dtxd' structure - may be real value, null or error.
USAGE |
    if (dtxnuval (opd->dtxdnull) == DTXVALUE)
    {
       .
       .
    }
`opd->dtxdnull` | `opd` is a pointer to a structure of type `dtxd`. `dtxdnull` is a field in this structure which indicates whether the argument value for a function is a valid result, a null, or an error.
`DTXVALUE` | is defined in the file `usefns.h` as:
    # define   DTXVALUE   040
RETURNS | 040 If an argument value evaluates to a valid result. 0 If an argument value does not evaluate to a valid result.
ASSIGNS | None.
WARNINGS | None.
EXAMPLE |
    if (dtxnuval (opd->dtxdnull) == DTXVALUE)
    {
       opr->dtxrresult->dtxdnull = DTXVALUE;     /* set the null indicator
                                                    field of the result
                                                    structure to indicate
                                                    that a value is
                                                    expected */

       return (true);
    }

#

spfree

DESCRIPTION | Free the space that had been used for performing internal calculations.
SYNOPSIS |
    spfree (space);
       addr   space;
USAGE |
    spfree (opr->dtxrwksp);
`opr->dtxrwksp` | Pointer (`addr`) to space allocated by `dtalloc()`.
RETURNS | None.
WARNINGS | None.
EXAMPLE |
    {
          .
          .
       spfree (opr->dtxrwksp);
       return (true);
          .
          .
    }

#

strfree

DESCRIPTION | Free space containing a variable length result value. This routine is normally used in conjunction with `strsave()` which stores a variable length result value. `strfree` is defined in the file `usrfns.h` as:
    #define    strfree (x)    spfree ((addr) (x))
SYNOPSIS |
    strfree (space);
       addr   space;
USAGE |
    strfree (*opr->dtxrresult->dtxdival);
`*opr->dtxrresult->dtxdival` | Pointer (`addr`) to result value.
RETURNS | None.
WARNINGS | `strsave()` will normally be called to allocate space to hold a variable length result value after `strfree()` first frees the space occupied by a variable length result value.
EXAMPLE |
    {
       addr *ival;
       char *ex;

          .
          .
       ex = "string_value";
       ival = opr->dtxrresult->dtxdival;
       strfree(*ival);
       *ival = strsave(ex);
          .
          .
    }

#

strsave

DESCRIPTION | Allocate the required space to store a variable length result.
SYNOPSIS |
    char   *strsave(value);
           addr   value;
USAGE |
    *ival = strsave (ex);

       addr   *ival;
       char   *ex;
RETURNS | An indirect pointer to the result.
WARNINGS | `strsave()` will normally be called to allocate the space to store a variable length result after `strfree()` frees the space occupied by another variable length result value.
EXAMPLE |
    {
       addr *ival;
       char *ex;

          .
          .
       ex = "string_value";
       ival = opr->dtxrresult->dtxdival;
       strfree(*ival);
       *ival = strsave(ex);
          .
          .
    }