19.2.6 Example - Manipulate an RDML Working List

This second example is a simple variation on the first example. 

It is called UD_AVERAGE_LIST and it allows an RDML "working list" of numbers to be passed into it.

All the values in the list are accumulated to produce the average value.

This function's unique identifier is 414.

It has one mandatory argument .... a working list of numbers.

It has one mandatory return value .... the average of the list of numbers.

Used in an RDML function like this it could support the averaging of up to 1000 entries:

  define field(#number) type(*dec) length(7)                 
  def_list name(#list) fields(#number) type(*working)        
           entrys(1000)                                      
  define field(#mean) type(*dec) length(7)                   
                                                             
  use  ud_average_list with_arg(#list) to_get(#mean)         

An example of the user defined Built-In Function required to implement UD_AVERAGE_LIST might be coded like this:
/ ================================================================= */
/* ========== USER DEFINED BUILT-IN FUNCTION DEFINITION =========== */
/* ================================================================ */
/*                                                                  */
/* Source File               : U_BIF414.C                           */
/* Entry Point Name          : U_Builtin_414                       */
/* Linked DLL Name           : U_BIF414.DLL                         */
/* Shared Object Name        : u_bif414.O                           */
/* OS/Dependencies           : Yes/No                               */
/*                                                                  */
/* Amendment History   :                                            */
/*                                                                  */
/* Task Id  Date    Description                                     */
/* =======  ====    ===========                                     */
/*                                                                  */
/* ================================================================ */
#define U_BIF_FUNCTION       U_Builtin_414
#define U_BIF_FUNCTION_NAME "U_Builtin_414"
#define U_BIF_DESCRIPTION   "This is a description of this built-in"

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <limits.h>

#include "x_glodef.h"
#include "x_glousr.h"

#ifdef X_OPERATING_SYSTEM_WIN
#include <windows.h>
#endif

#include "x_funstr.h"
#include "x_funpro.h"
#include "x_bif000.h"
/*==================================================================*/
/*                                                                  */
/* Arguments    : pX_Ids       - Standard X_IDS system definition   */
/*                pX_Pro       - Standard X_PRO process definition  */
/*                pX_Fun       - Standard X_FUN function definition */
/*                pX_Bif       - Standard X_BIF built-in definition */
/*                X_Fld[:      - Standard X_FLD field definitions   */
/*                X_List[:     - Standard X_LIST list definitions   */
/*                sInCount     - Number of arguments passed  */
/*                sInVec[:     - Vectors of arguments               */
/*                sRetCount    - Number of return values            */
/*                sRetVec[:    - Vectors of return values           */
/*                                                                  */
/*==================================================================*/
 X_VOID_FUNCTION U_BIF_FUNCTION ( U_BIF_STANDARD_PARAMETERS )
{

   /* ------------------------------------------------------------- */
   /* Handle a shutdown request (usually no activity is required)   */
   /* ------------------------------------------------------------- */
    if (U_BIF_SHUTDOWN_REQUEST)
   {
      U_BIF_SET_GOOD_RETURN
   }
   /* ------------------------------------------------------------- */
   /* Else perform the requested activity                           */
   /* ------------------------------------------------------------- */
    else
   {

      U_BIF_DECLARE_LIST_POINTER (pListArg1)
      X_SHORT  sEntrys  = 0;
      X_LONG   lAverage = 0;

      /* ------------------------------------- */
      /* Set list pointer and get entry count  */
      /* ------------------------------------- */

       U_BIF_SET_ARG_LIST_POINTER (pListArg1, 0)
       U_BIF_GET_LIST_CURRENT_ENTRYS (pListArg1, sEntrys)

      /* ------------------------------------- */
      /* If there is any entries in the list   */
      /* ------------------------------------- */

       if (sEntrys > 0)
      {
         X_SHORT  sCurrentEntry;
         X_CHAR   chFound;
         X_LONG   lValue;
         X_DOUBLE dTotal = 0;

         /* -------------------------------------- */
         /* Process all list entries and calculate */
         /* the average value of all of them       */
         /* -------------------------------------- */

      for (sCurrentEntry = 1; sCurrentEntry <= sEntrys; sCurrentEntry++)
        {
           U_BIF_GET_ENTRY_FROM_LIST (pListArg1, sCurrentEntry, chFound)
           U_BIF_GET_LIST_COLUMN_AS_LONG (pListArg1, 0, lValue)
           dTotal = dTotal + lValue;
         }
          lAverage = dTotal / sEntrys;
       }
      /* ------------------------------------- */
      /* Return the result in return value 1   */
      /* ------------------------------------- */
        U_BIF_SET_RET_FROM_LONG (0, lAverage);
        U_BIF_SET_GOOD_RETURN
    }

   /* ------------------------------------------------------------- */
   /* Return control to caller                                      */
   /* ------------------------------------------------------------- */
    U_BIF_RETURN;
}

Some significant things to note about this example are: