C Utility Functions for User Functions

This page documents the various C functions which can be used when writing your own user function.

Writing User Functions is documented in the Gsharp User Guide.

  • GsharpBatchMode  - Returns true if Gsharp is running in batch mode, otherwise false.
  • GsharpTopLevel  - Returns the top level widget ID of Gsharp.
  • UpgMsgHandler - Writes a message to the Gsharp Message Area.
  • VarGetType  - Returns the type of a stack object.
  • VarGetUndefined  - Returns the current undefined value.
  • VarIndexIn  - Stores data starting at a particular row, column, and plane.
  • VarIndexOut  - Extracts data from a particular row, column, and plane.
  • VarIsDateData  - Returns true if the datum object is date data.
  • VarIsRealData  - Returns true if the datum object is real (float) data.
  • VarIsTextData  - Returns true if the datum object is text (string) data.
  • VarIsTimeData  - Returns true if the datum object is time data.
  • VarIsNoData  - Returns true if the datum object is an omitted function parameter.
  • VarIsScalar  - Returns true if the datum object is a scalar. 
  • VarIsString  - Returns true if the datum object is a string.
  • VarIsTrue  - Returns true if all data elements in the tack object are true (non-zero).
  • VarName  - Returns a pointer to the Datum name.
  • VarNiceExtremes  - Calculates the nice extremes of a stack object.
  • VarNumColumns  - Returns the number of columns in a stack object.
  • VarNumElements  - Returns the number of data elements in a stack object.
  • VarNumPlanes  - Returns the number of planes in a stack object.
  • VarNumRows  - Returns the number of rows in a stack object.
  • VarReference  - Adds one to the object reference count.
  • VarRelease  - Releases a stack object.
  • VarSelectFolder  - Selects the specified folder and makes it the current folder.
  • VarSetRealData  - Stores real data in a named dataset.
  • VarSetStringData  - Stores text data in a named dataset.
  • VarStoreDataset  - Stores the stack object in a named dataset.
  • VarTempCreate  - Creates a stack object.

CLBreak - stop execution of code that called user function

Syntax:

void CLBreak (void);

Description:

Executes the GSL code in s.

  • If log is true then the code is added to the command log

  • name should contain the name of the calling function. It will be included in any error messages.

Examples:

 
CLRuntimeMessage(CL_ERROR, "No such command");
CLBreak();

See also:

CLRuntimeMessage

CLErrorMessages - enable or suppress error messages

Syntax:

void CLErrorMessages (CLBoolean show_messages);

Description:

Turn error messages off or on.

  • show_messages is either True or False

Examples:

 
CLErrorMessages(False);
if(CLExecuteString(True, command, USER_EXEC))
{
   CLRuntimeMessage(CL_ERROR, CLGetLastErrorMessage());
}
CLErrorMessages(True);

See also:

CLExecuteString, CLGetLastErrorMessage, CLRuntimeMessage

CLExecuteFile - execute a GSL script

Syntax:

int CLExecuteFile (CLString filename);

Description:

Executes the GSL code in the file filename.

Examples:

 
CLExecuteString("myscript.gsl");

See also:

CLExecuteString, CLExecuteStringQuiet

CLExecuteString - execute GSL code

Syntax:

int CLExecuteString (CLBoolean log, CLString s, CLString name);

Description:

Executes the GSL code in the string s.

  • If log is true then the code is added to the command log

  • name should contain the name of the calling function. It will be included in any error messages.

  • returns 0 on success

Examples:

 
sprintf(cmd,"gsharp_1.Polar.B.progress.XuNguiWidth=%d;", n);
CLExecuteString(False, cmd, "UserFunc.c: READDATAPOINTS");

See also:

CLExecuteStringQuiet

CLExecuteStringQuiet - execute GSL code without processing XEvents

Syntax:

int CLExecuteStringQuiet (CLBoolean log, CLString s, CLString name);

Description:

Suspends the processing of XEvents and then calls CLExecuteString.

See also:

CLExecuteString

CLGetLastErrorMessage - get last error message

Syntax:

char *CLGetLastErrorMessage (void);

Description:

Returns the last error message of the parser.

  • The function returns a string pointer to an internal string buffer and so the pointer must not be freed.

Examples:

 
CLErrorMessages(False);
if(CLExecuteString(True, command, USER_EXEC))
{
   CLRuntimeMessage(CL_ERROR, CLGetLastErrorMessage());
}
CLErrorMessages(True);

See also:

CLExecuteString, CLRuntimeMessage

CLMemoryError - Report lack of memory

Syntax:

void CLMemoryError (void);

Description:

Call to report lack of memory

Examples:

 
if(!(dt = VarCreate(RealData, Scalar)))
{  CLMemoryError();
   CLBreak();
   return NULL;
}

See also:

CLBreak

CLRuntimeMessage - output message

Syntax:

void CLRuntimeMessage(CLMessageType msg_type, VarString message)

Description:

Writes a message to the Gsharp Message Area. The message is always output regardless of the message status set with the function set_messages.

  • msg_type should be set to one of the following enumerated values: CL_ERROR, CL_WARNING, CL_INFO, CL_USER.

Examples:

 
CLRuntimeMessage(CL_INFO, "Data is read into T1");

See also:

UpgMsgHandler

CLSyntaxCheckString - parse GSL code

Syntax:

int CLSyntaxCheckString (CLString s, CLString name);

Description:

Parse the GSL code in the string s.

  • name should contain the name of the calling function. It will be included in any error messages.

  • returns 0 if no errors found or line number of first error

Examples:

 
if(CLSyntaxCheckString(command, "MyFunc"))
{  CLRuntimeMessage(CL_INFO, "Internal error in MyFunc");
   return NULL;
}
CLExecuteString(False, command, "MyFunc");

See also:

CLExecuteString

GsharpBatchMode - return mode

Syntax:

VarBoolean GsharpBatchMode(void)

Description:

Returns true if Gsharp is running in batch mode, otherwise false.

Examples:

 
if GsharpBatchMode()
{   return dt;
}

GsharpTopLevel  - return top level widget

Syntax:

Widget GsharpTopLevel(void)

Description:

Returns the widget ID of the Gsharp top level shell. Not necessary or available under Windows.

Examples:

 
if GsharpBatchMode()
{   return dt;
}

UpgMsgHandler - output message

Syntax:

void UpgMsgHandler(VarInt msg_type, VarString message)

Description:

Writes a message to the Gsharp Message Area. The message is filtered according to the status set with the function set_messages. It is recommended that user's function should use CL_USER.

  • msg_type should be set to one of the following enumerated values: CL_ERROR, CL_WARNING, CL_INFO, CL_USER.

Examples:

 
UpgMsgHandler(CL_INFO, "Data is read into T1");

See also:

CLRuntimeMessage

VarCalculateExtremes - calculate extremes of dataset

Syntax:

VarInt VarCalculateExtremes(Datum d1, VarFloat *min, VarFloat *max)

Description:

VarCalculateExtremes returns the minimum and maximum values of the datum d1. The minimum and maximum values are stored in min and max.

  • Note: VarCalculateExtremes will only work on datums of type RealData. 

Examples:

 
VarFloat dmin, dmax;
int x;
Datum d1;       
x = VarCalculateExtremes(d1, &dmin, &dmax);
See also: VarNiceExtremes

VarContainsUndef - check for undefined values

Syntax:

VarBoolean VarContainsUndef(Datum v) 

Description:

VarContainsUndef returns true if v contains at least one element with the undefined value.

Examples:

 
if VarContainsUndef()
{   return dt;
}

VarCopy - copy dataset

Syntax:

Datum VarCopy(Datum v) 

Description:

VarCopy creates a copy of the datum v. The copy must be released with VarRelease if it is not passed back to a caller. 

Examples:

 
Datum d1, dt;       
d1 = *argv++;
dt = VarCopy(d1);
return dt;

See also:

VarReference, VarRelease

VarCopyData - copy data from dataset

Syntax:

VarPointer VarCopyData(Datum v) 

Description:

VarCopyData returns a pointer to a copy of the data stored in the datum v.

Data is formatted in the following way: 

  • If the data is of type RealData, VarCopyData returns a pointer to an array of VarFloat elements. You are responsible for freeing the pointer.

  • For all other types, VarCopyData returns a pointer to an array of VarString elements. Again, you are responsible for freeing all individual VarString datums as well as the returned pointer.

Examples:

 
Datum d1;
int nlines;
VarFloat *vals;

d1 = *argv;
nlines = VarNumRows(d1);
vals = (VarFloat *) VarCopyData(d1);

VarCreate - create dataset

Syntax:

Datum VarCreate(VarDataCode type, DatumDimension dimension) 

Description:

Creates a variable. To create a datum to hold data call VarCreate with the data type and size of the datum. The data type must be either RealData, TextData, DateData, or TimeData. Storage will be set aside to hold as many elements as specified by dimension. 

  • dimension should be set as follows: 

Datum my_data;

DatumDimension dim;
dim[0] = 100;
dim[1] = 1;
dim[2] = 1;
my_data = VarCreate(RealData, dim);

  • In the example above, my_data will be able to hold 100 real elements in the first dimension. The individual elements will be initialized to zero (if the data type were something other than RealData, the elements would be initialized to the undefined value). 

  • The datum returned by VarCreate is marked to be referenced by one user. If the datum is returned to a caller, it should not be dereferenced but rather passed on. If it is only used locally, then it must be dereferenced by calling the VarRelease routine.

  • To store the datum in a dataset in the Data Manager, use VarCreateDataset. You must call VarRelease if you don't need the datum after having stored it in the Data Manager. 

Example 1:

 
Datum dt;       
dt = VarCreate(RealData, Scalar);

Example 2:

 
#The following lines of code show how an array is filled with data
#and passed as the return value from a user function:
DataDimension num_record;
Datum record;
int n = 100;

/* size of returned array: 100, i.e. float array [100] */
num_record[0] = n;
num_record[1] = 1; 
num_record[2] = 1;

/* register the variable pointer with Gsharp (no name is
* registered, just the pointer
*/
record = VarCreate(RealData, num_record);

/* initialize the array with 1...10 */
for(i=1; i<=n; i++) VarSetRealData(record, i, 1, 1, (VarFloat) i);

See also:

VarCreateDataset, VarReference, VarRelease and VarTempCreate

VarCreateDataset - create dataset

Syntax:

VarBoolean VarCreateDataset(VarString name, Datum v)

Description:

Create a dataset with the name specified in name with the data specified in v. v could be the result of a call to VarCreate.

  • VarCreateDataset will return True if the operation was successful and False otherwise.

Examples:

 
VarCreateDataset("DPN2Polar", dd2p);
VarRelease(dd2p);

VarCreateFolder - create folder

Syntax:

VarBoolean VarCreateFolder(VarString name) 

Description:

VarCreateFolder creates a folder in the Data Manager. The folder can then be used to hold datasets. 

Examples:

 
VarCreate("NEWFOLDER");

See also:

VarCurrentFolder, VarDeleteFolder, VarSelectFolder 

VarCurrentFolder - get current folder

Syntax:

VarString VarCurrentFolder(void) 

Description:

VarCurrentFolder returns the name of the current folder. The returned string must not be freed or manipulated. 

Examples:

 
char *folder;
folder = VarCurrentFolder();

See also:

VarCreateFolder, VarDeleteFolder, VarSelectFolder 

VarDeleteDataset - delete dataset

Syntax:

VarBoolean VarDeleteDataset(VarString name) 

Description:

Deletes the specified dataset from the Data Manager. Return False if error, otherwise True.

Examples:

 
VarDeleteDataset("WORK.argv");

See also:

VarDeleteFolder

VarDeleteFolder - delete folder

Syntax:

VarBoolean VarDeleteFolder(VarString name) 

Description:

VarDeleteFolder deletes the specified folder from the Data Manager. Any dataset stored in the folder is also deleted.

  • References to any dataset retrieved with VarGetDataset will still exist until all references have been released with VarRelease, at which point the memory will be deallocated.

  • Return False if error, otherwise True.

Examples:

 
VarDeleteFolder("WORK2");

See also:

VarCreateFolder, VarCurrentFolder, VarSelectFolder 

VarFreeData - free data

Syntax:

void VarFreeData(Datum v) 

Description:

VarFreeData frees all data associated with v datum and sets the datum to contain no data.

Examples:

 
VarFreeData(d2);

VarGetDataset  - get dataset

Syntax:

Datum VarGetDataset(VarString name)

Description:

Get the data associated with name. If no dataset exists with the name name, VarGetDataset will return NULL. Otherwise a Datum is returned which may be used in a function like VarGetRealData. 

Examples:

 
Datum v1;
VarFloat f;

v1 = VarGetDataset("WORK.mydata");
f = VarGetRealData(v1, 1, 1, 1);

VarGetRealData  - get real data

Syntax:

VarFloat VarGetRealData(Datum v, VarInt row, VarInt column, VarInt plane) 

Description:

VarGetRealData returns the data in the element addressed by row, column, plane in a RealData datum v. 

Examples:

 
VarFloat f;
f = VarGetRealData(d1, 1, 1, 1);

See also:

VarGetStringData, VarGetUndefined

VarGetStringData  - get string data

Syntax:

const VarString VarGetStringData(Datum v, VarInt row, VarInt column, VarInt plane) 

Description:

VarGetStringData returns a pointer to the element addressed by row, column, plane in a TextData, DateData or TimeData datum. 

  • VarGetStringData returns a pointer to a string.

  • The string must not be manipulated and the pointer must not be freed. Use strdup if you need a local copy. 

  • If the element is undefined, then a NULL pointer is returned. 

Examples:

 
VarFloat f;
f = VarGetRealData(d1, 1, 1, 1);

See also:

VarGetRealData, VarGetUndefined

VarGetType  - get type

Syntax:

DataCode VarGetType(Datum v)

Description:

Returns the type of the data stored in v.

Examples:

 
Datum v, result;
DataCode type;

v = VarGetDataset("WORK.mydata");
type = VarGetType(v);
result = VarCreate(type, Scalar);

VarGetUndefined  - get undefined value

Syntax:

VarFloat VarGetUndefined(void)

Description:

VarGetUndefined returns the current value which is used to denote undefined data. 

  • Note: There is currently no way to set the systems notion of an undefined value.

Examples:

 
VarFloat f;       
f = VarGetUndefined();

VarIndexIn - index in

Syntax:

VarInt VarIndexIn(Datum source, Datum dest, VarInt row, VarInt column, VarInt plane) 

Description:

VarIndexIn stores the data in source into dest starting at the specified row, column, and plane. 

  • If row, column, and plane are all zero, the entire contents of source is stored in dest. 

See also:

VarIndexOut

VarIndexOut - index out

Syntax:

Datum VarIndexOut(Datum source, VarInt row, VarInt column, VarInt plane) 

Description:

VarIndexOut extracts data from source starting at the specified row, column, and plane. 

See also:

VarIndexIn

VarIsDateData - check for date data

Syntax:

VarBoolean VarIsDateData(Datum v)

Description:

Returns true if the data type is date, otherwise it returns false.

VarIsNoData  - check for no data

Syntax:

VarBoolean VarIsNoData(Datum v)

Description:

Returns true if the Datum variable is an optional function parameter which has been left out by the caller.

  • It is necessary to check each optional parameter to a function with this routine before accessing the data associated with the parameter.

Examples:

 
Datum mode;
int mode_flag;

mode = *argv++;

if(!VarIsNoData(mode))
mode_flag = (int)VarGetRealData(mode, 1, 1, 1);
else
mode_flag = 0;

VarIsRealData - check for real data

Syntax:

VarBoolean VarIsRealData(Datum v)

Description:

Returns true if the data type is real (float), otherwise it returns false. 

VarIsTextData  - check for text data

Syntax:

VarBoolean VarIsTextData(Datum v)

Description:

Returns true if the data type is text (string), otherwise it returns false. 

VarIsTimeData  - check for time data

Syntax:

VarBoolean VarIsTimeData(Datum v)

Description:

Returns true if the data type is time, otherwise it returns false. 

VarIsScalar  - check for scalar

Syntax:

VarBoolean VarIsScalar(Datum v)

Description:

Returns true if the variable is a scalar, otherwise it returns false. 

VarIsString  - check for string

Syntax:

VarBoolean VarIsString(Datum v)

Description:

Return true if the data in v is an array of null terminated strings.

  • The following data types are represented by null terminated strings: date, string, time.

VarIsTrue - check for string

Syntax:

VarBoolean VarIsTrue(Datum v) 

Description:

VarIsTrue returns true if all elements in v are true, in other words, non-zero or not equal to the current undefined value. 

See also:

VarContainsUndef, VarGetUndefined

VarName  - find datum in DataManage

Syntax:

VarString VarName(Datum v) 

Description:

VarName returns a pointer to the name of a datum if the datum has been stored in a dataset in the Data Manager.

  • If the datum has not been stored in a dataset in the Data Manager, VarName returns NULL.

  • The pointer returned by VarName must not be freed or in any way manipulated. 

See also:

VarCreateDataset, VarGetDataset, VarStoreDataset 

VarNiceExtremes  - find nice extremes

Syntax:

VarInt VarNiceExtremes(VarFloat *min, VarFloat *max) 

Description:

VarNiceExtremes rounds the values of the given min and max and replaces the original values with the rounded values. The returned values are suitable for axis end points. 

See also:

VarCalculateExtremes

VarNumColumns  - return number of columns

Syntax:

VarInt VarNumColumns(Datum v)

Description:

Returns number of columns. 

VarNumElements  - return number of elements

Syntax:

VarInt VarNumElements(Datum v)

Description:

Returns number of elements in the Datum v.

  • VarNumElements(v) gives the same result as:

    VarNumRows(v) * VarNumColumns(v) * VarNumPlanes(v)

VarNumPlanes  - return number of planes

Syntax:

VarInt VarNumPlanes(Datum v)

Description:

Returns number of planes. 

VarNumRows  - return number of rows

Syntax:

VarInt VarNumrows(Datum v)

Description:

Returns number of rows. 

VarReference  - increment reference count

Syntax:

Datum VarReference(Datum v)

Description:

VarReference increments the reference count on the datum v and returns v itself. This must be used whenever a datum is referenced by a routine for permanent use, in other words, when the reference to the datum in a static variable:

Example:

static Datum save_me = NULL;

if(save_me) VarRelease(save_me);
save_me = VarReference(new_datum);

See also:

VarRelease

VarRelease  - release Datum

Syntax:

void VarRelease(Datum v) 

Description:

VarRelease tells the Data Manager that you are no longer using the datum v. This allows you to keep track of how many routines are referring to a datum. 

See also:

VarCreate, VarReference, VarTempCreate

VarSelectFolder  - release Datum

Syntax:

VarBoolean VarSelectFolder(VarString name) 

Description:

VarSelectFolder selects the specified folder and makes it the current folder for GSL data operations. 

See also:

VarCreateFolder, VarCurrentFolder, VarDeleteFolder 

VarSetRealData  - set element of Datum

Syntax:

void VarSetRealData(Datum v, VarInt row, VarInt column, VarInt plane, VarFloat d)

Description:

Store the real value d at [row, column, plane] in v. It is the responsibility of the caller to make sure that v is of the right datatype (RealData) and that row, column and plane are within bounds.

See also:

VarSetStringData 

VarSetStringData  - set element of Datum

Syntax:

void VarSetStringData(Datum v, VarInt row, VarInt column, VarInt plane, VarString s)

Description:

Store the text value s at [row, column, plane] in v. I t is the responsibility of the caller to make sure that v is of the right datatype (TextData) and that row, column and plane are within bounds.

See also:

VarSetRealData 

VarStoreDataset  - store dataset

Syntax:

VarBoolean VarStoreDataset(VarString name, Datum v, VarInt row, VarInt column, VarInt plane)

Description:

Store the Datum v in a dataset with the name name.

  • If name does not exist, it is created.

  • If row, column, and plane are specified, then v is stored at that position in the dataset referenced by name. The dataset must then have the appropriate size to avoid an out of bounds condition. 

VarTempCreate- store dataset

Syntax:

Datum VarTempCreate(Datum d1, Datum d2, VarDataCode type) 

Description:

VarTempCreate creates a new datum based on the sizes of d1 and d2. A new type may be specified, or you can specify NoData as the data type to create a datum with the same type as d1. d2 may be given as NULL which will create a datum of the same size as d1. 

The size of the new datum is determined from the following algorithm:

  • If d1 is scalar then the returned datum has the same size as d2.

  • If d2 is a scalar or is not specified then the returned datum will have the same size as d1.

  • If neither of the above are true, the returned datum will, for each dimension, have the smallest size which is not 1. 

For example, if you pair a [10, 10, 10] datum with a [10, 8, 8] datum, the result will be [10, 8, 8]. 
If you pair a [10, 1, 1] datum with a [10, 8, 8] datum, the result will be [10, 8, 8]. 

See also:

VarCreate