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:
- The manipulation of a working list. Working lists passed into Built-In Functions can be read, updated, added to or cleared by using a few simple U_BIF macros.
- Note that unlike arguments and return values, working list entries are numbered from 1 to N, rather than from 0 to (N-1).