Convert a string to FLOAT.

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;

cvaf (&f, string);

1

If successful.

0

If unsuccessful.

None.

#include <../include/usrfns.h>

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

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

Convert a string to INTEGER.

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;

cvai (&i, string);

1

If successful.

0

If unsuccessful.

None.

#include <../include/usrfns.h>

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

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

Convert a string to LONGINTEGER.

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;

cval (&l, string);

1

If successful.

0

If unsuccessful.

None.

#include <../include/usrfns.h>

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

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

Convert a floating point value to a string.

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;

cvfx (string, f);

None.

None.

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

Convert a INTEGER value to a string.

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;

cvix (string, i);

None.

None.

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

Convert a LONGINTEGER value to a string.

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;

cvlx (string, l);

None.

None.

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

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)

space = dtalloc(n);

   addr    space;
   int     n;

opr->dtxrwksp = dtalloc(n);

Pointer (addr) to the space allocated for performing internal calculations.

The space allocated by dtalloc() must be freed by calling spfree().

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

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.

char   *dtgetex (dtp, *val);
       dtpar    *dtp;
       addr     *val;

dtgetex(opd->dtxddtp, *(opd->dtxdival));

None.

None.

dtgetex(opd->dtxddtp, *(opd->dtxdival));

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.

char   *dtgetgex (dtp, *val);
       dtpar    *dtp;
       addr     *val;

dtgetgex(opd->dtxddtp, *(opd->dtxdival));

None.

None.

dtgetgex(opd->dtxddtp, *(opd->dtxdival));

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.

char   *dtgetgin (dtp, *val);
       dtpar    *dtp;
       addr     *val;

dtgetgin (opd->dtxddtp, *(opd->dtxdival));

None.

None.

dtgetgin(opd->dtxddtp, *(opd->dtxdival));

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.

char   *dtgetin (dtp, *val);
       dtpar    *dtp;
       addr     *val;

dtgetin (opd->dtxddtp, *(opd->dtxdival));

None.

None.

dtgetin (opd->dtxddtp, *(opd->dtxdival));

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.

char   *dtputex (dtp, *ex);
       dtpar    *dtp;
       char     *ex;

dtputex (opd->dtxddtp, *ex);

Pointer to an error message string if the conversion fails. CHARNIL if successful.

None.

dtputex(opd->dtxddtp, *(opd->dtxdival));

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.

char   *dtputgex (dtp, *ex);
       dtpar    *dtp;
       char     *ex;

dtputgex (opd->dtxddtp, *ex);

Pointer to an error message string if the conversion fails. CHARNIL if successful.

None.

dtputgex(opd->dtxddtp, *(opd->dtxdival));

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.

char   *dtputgin (dtp, in);
       dtpar    *dtp;
       addr     in;

dtputgin (opd->dtxddtp, in);

Pointer to an error message string if the conversion fails. CHARNIL if successful.

None.

dtputgin (opd->dtxddtp, *(opd->dtxdival));

Convert a value to file format in Empress from internal format. This routine is used to convert function arguments.

char   *dtputin (dtp, in);
       dtpar    *dtp;
       addr     in;

dtputin (opd->dtxddtp, in);

Pointer to an error message string if the conversion fails. CHARNIL if successful.

None.

dtputin (opd->dtxddtp, *(opd->dtxdival));

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

dtudferr (string)
    char *string;

dtudferr (string);

None.

None.

The UDF must return false for this routine to be invoked. A result value should not be assigned if the function returns false.

{
      .
      .
   dtudferr("error in function argument");
   return(false);
}

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.

dtxnuerr (n)

   # define dtxnuerr (n)    ((n) & DTXERR)

if (dtxnuerr (opd->dtxdnull) == DTXERR)
{
   .
   .
}

# define   DTXERR   0100

0100

If an argument value evaluates to an error.

0

If an argument value does not evaluate to an error.

None.

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.

if (dtxnuerr (opd->dtxdnull) == DTXERR)
{
   dtudferr ("function argument cannot be evaluated");
   return (false);
}

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.

dtxnunul (n)

   # define dtxnunul (n)    ((n) & DTXNULL)

if (dtxnunul (opd->dtxdnull) == DTXNULL)
{
   .
   .
}

# define   DTXNULL   020

020

If an argument value evaluates to null.

0

If an argument value does not evaluate to null.

None.

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.

if (dtxnunul (opd->dtxdnull) == DTXNULL)
{
   opr->dtxrresult->dtxdnull = DTXOPDNUL;     /* return a null value */
   return (true);
}

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.

dtxnuval (n)

   # define dtxnuval (n)    ((n) & DTXVALUE)

if (dtxnuval (opd->dtxdnull) == DTXVALUE)
{
   .
   .
}

# define   DTXVALUE   040

040

If an argument value evaluates to a valid result.

0

If an argument value does not evaluate to a valid result.

None.

None.

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

Free the space that had been used for performing internal calculations.

spfree (space);
   addr   space;

spfree (opr->dtxrwksp);

None.

None.

{
      .
      .
   spfree (opr->dtxrwksp);
   return (true);
      .
      .
}

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

strfree (space);
   addr   space;

strfree (*opr->dtxrresult->dtxdival);

None.

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.

{
   addr *ival;
   char *ex;

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

Allocate the required space to store a variable length result.

char   *strsave(value);
       addr   value;

*ival = strsave (ex);

   addr   *ival;
   char   *ex;

An indirect pointer to the result.

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.

{
   addr *ival;
   char *ex;

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