#include <uif.h> #include <gp.h> #include <usevars.h> int getusenames(names, nkeep, nomit) char *names[]; int *nkeep; int *nomit; int getusenames2(param, names, nkeep, nomit) char *param; char *names[]; int *nkeep; int *nomit; int getkeepnames(param, min, max, names, nkeep) char *param; int min, max; char *names[]; int *nkeep; int getusevars(set, names, nkeep, nomit, var) SETP set; char **names; int nkeep; int nomit; VARP **var; int getkeepvars(set, names, nkeep, var) SETP set; char **names; int nkeep; VARP **var; int freeusevars(var) VARP var; int getsamevar(var, arrays, n, v) VARP var; VARP arrays[]; int n; VARP v[]; int cmpsamevars(var, n, mask) VARP var[]; int n; int mask; int cmp2vars(var1, var2, mask) VARP var1, var2; int mask; int cmperr(var, diff) VARP var; int diff;
The functions described here are TDF variable utility functions. They are used primarily for getting variable names from the user in terms of function parameters, finding the corresponding variables in datasets, and testing similarity of variables within and across datasets.
getusenames() or getkeepnames() /* Get name list
getusenames2() :
: :
getusevars() getkeepvars() /* Find var list
: :
: :
cmpvars() or cmpvars() or /* Compare vars
cmp2vars() cmp2vars()
: :
freeusevars() freeusevars() /* Free var list
getusenames and getusenames2 query the user for TDF variable names. names points to the list of names. The memory for the names is allocated dynamically by these routines and is never freed. If the user does not specify any variables, nkeep and nomit both equal 0, and it is assumed that the calling program will process all variables. If the user types in a '-' before the names, nomit equals the number of names typed in and nkeep equals 0. In this case, the list of names are those that should be omitted from the processing in the calling program. Otherwise the names that are entered are those that are intended to be processed by the calling program, and nkeep equals the number of names typed in and nomit equals 0. Both these functions are to be used in conjunction with cmdform, getusenames uses the parameter name include vars, while getusenames2 allows a user-defined parameter name, param.
Given a TDF dataset set and an array of names to keep/omit obtained by getusenames, getusevars returns an array of variables in the dataset to use. The array is null terminated. Only one or both of nkeep and nomit can be 0. If both are 0, then all variables in the dataset are returned in the array of variables var. If nomit is non-zero, then the returned list contains all variables in the set omitting the variables with names names. getusevars allocates dynamic memory to hold the array of pointers to variables; applications should call freeusevars when done with the array.
getkeepnames is a useful variant of getusenames2, with the following differences. getkeepnames accepts between min and max names (or wildcard terms), does not have an omit option, and has no default response unless min=0.
getkeepvars is a version of getusevars, intended to be used in conjunction with getkeepnames. getkeepvars guarantees that each name returned by getkeepvars corresponds to one and only one dataset variable. Otherwise, an error occurs.
freeusevars frees the dynamic memory associated with the list of variables, var, obtained by getusevars or getkeepvars.
getsamevar gets the same variable from an array of variable arrays, where each variable array was obtained from getusevars. The same variable is determined by the name of variable var. The output is an array, v, of retrieved variables, one from each array in arrays. The output array is null terminated. If the variable is missing in one of the arrays, its corresponding entry in the output array is NULL. n is the number of input arrays in the array arrays.
cmpsamevars compares the properties of a list of variables in var. The procedure compares the properties of the first variable to all other variables in the list. n gives the number of variables in the list. mask is a mask of properties to be compared; see include/usevars.h for properties and their mask values (see datasets). Mask values can be or\'ed together. The return value is the mask of properties that did not match.
cmp2vars compares the properties of variables var1 and var2 on the basis of a property mask. The list of properties that can be compared is given in include/usevars.h. Mask values can be or\'ed together. The return value is the mask of properties that did not match.
cmperr reports comparison errors involving variables using fmtout. The name of variable var is used in the error message. diff is the mask of properties that did not match. Each nonmatching property is reported in the error message. An example use might be:
diff = cmpvars(...) if (diff) exit( cmperr(var, diff) );
with a possible error message such as:
'satvar1: badvalue/scaling/dimsizes vary across datasets'
If successful, getusenames, getusenames2, and getkeepnames return the number of names (wildcard terms) entered by the user. Otherwise -1 is returned with error code in terrno.
If successful, getusevars and getkeepvars return the number of variables to use (i.e., to keep or not omit) in the given dataset. Otherwise -1 is returned with error code in terrno.
getsamevar returns -1 if a variable is missing from one of the arrays, 0 otherwise.
cmpsamevars and cmp2vars return the mask of properties that did not match.
cmperr always returns -1.
ENOMEM is declared in /usr/include/errno.h. Dataset-related errors are found in gp.h. Parameter-related errors are declared in uif.h.
include/gp.h, include/usevars.h, include/uif.h, lib/libapp.a
gpatt, gpdim, gperr, gplink, gpname, gprel, gpset, gptype, gpvar, datasets, typestuff, coordstuff, prmstr, cmdform, uif
Last Update: $Date: 1999/05/10 20:57:08 $