[Next] [Previous] [Index]
Next: References Previous: Afterword Index: Contents

Functions in the PIPS library


List of functions


pipsAddPnm()

Synopsis

int pipsAddPnm (int ncId, char *varName, char *imgName, nc_type dataType)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate()
char *varName
Name of variable to create, default is imgName
char *imgName
Name of file to open, NULL means read from stdin
nc_type dataType
Type of variable to create

Description

pipsAddPnm() reads the image file header to determine the type and size of the image, then creates a variable varName or imgName, if varName is empty and the variable doesn't exist. The image data is read and converted to NC_BYTE or NC_LONG (only ppm) and written to the end of the variable.

pipsAwaitChildData()

Synopsis

void pipsAwaitChildData (tid, jobId, perform, done, ntask, finishedJob, index)

Parameters

int tid []
An array with task Id's of the tasks
int jobId []
An array with currently processed data fragments
int perform []
An array with number of completed jobs per task
int *done
Total number of accomplished jobs so far
int ntask
Number of spawned tasks
int *finishedJob
Number of recently finished job.
int *index
Index for tid[], jobId[] and perform[]

Description

pipsAwaitChildData() waits for the next task to send an idle signal. It then looks up its task id and prepares the reception of data, if the task was busy with a job.

pipsChangeAtts()

Synopsis

int pipsChangeAtts (ncId, defName)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate()
char *defName
Name of file containing attribute definitions

Description

pipsChangeAtts() opens the file defName and changes/adds/deletes attributes in the file of ncId. If defName is NULL, then stdin is read. The definitions have to be in CDL-Syntax

pipsDataPerJob()

Synopsis

long pipsDataPerJob (ntask, granularity, lower, upper, items, njobs)

Parameters

int ntask
Number of tasks available for parallel data processing (spawned by pipsTaskManager)
int granularity
A number to influence the number of data fragments (jobs) generated.
int lower
A lower bound for the number of jobs
int upper
An upper bound for the number of jobs
int *njobs
The number of jobs to generate

Description

pipsDataPerJob() calculates the optimal number of jobs to distribute among the tasks. It will be at least lower and at most upper. The function returns the number of items per job.

pipsExtPnm()

Synopsis

int pipsExtPnm (ncId, varName, number, imgName, imgType)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate()
char *varName
Name of variable to query, NULL means all variables
long number
Number of image to extract from variable, default is all images.
char *imgName
Name of image file to create, default is varName
int imgType
Type of image to create, possible values: PipsUnknown, PipsPbmAscii, PipsPgmAscii, PpmAscii, PgmRaw, PpmRaw . PipsUnknown causes to determine the type from the variable attribute or data type

Description

pipsExtPnm() creates an image file named imgName of type imgType and copies the data from the variable varName to it. If number > -1, then that image from the image sequence is extracted, otherwise all images are extracted and stored in numbered files (foo.pgm.0, foo.pgm.1, ...). If varName is empty, then all variables are processed.

pipsHistory()

Synopsis

void pipsHistory (ncID, value)

Parameters

int ncID
ID of netCDF file
char *value
String designating value associated with attribute

Description

pipsHistory() append data manipulation histories to the netcdf file. The value is appended as character string to the attribute name constructed from the history prefix and the current time. It is assumed that NetCDF is already in define mode for this routine to work.

pipsJobAvailable()

Synopsis

int pipsJobAvailable (int jobId[], int *job, int ntask, int newJobs)

Parameters

int jobId[]
Array of currently processed jobs (on all hosts)
int *job
Returned number of next job to process
int ntask
Number of tasks spawned by pipsTaskManager
int task
Index of task that has most recently submitted a finished job and gets another one now
int newJobs
Indicates wheter or not new jobs are available or if the competition has allready started.

Description

pipsJobAvailable() returns the number of a new job. If all new jobs are distributed, then a job currently processed is returned, so a competition among the tasks will be started.

pipsMinMax()

Synopsis

int pipsMinMax (ncId, varId, number, imgName, imgType, min, max)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate()
int *varId
Id of variable to query
long number
Number of image to examine
long height
Height of image
long width
Width of image
unsigned long *min
Minimum value in the image
unsigned long *max
Maximum value in the image

Description

pipsMinMax() expects long data in varId and returns the minimal and maximal value.

pipsNewFlagArray()

Synopsis

int *pipsNewFlagArray (size, initValue)

Parameters

int size
The number of flags, the array will contain
int initValue
The value that should be put into the array

Description

pipsNewFlagArray() allocates size elements of memory, stores initvalue in them and returns a pointer to the location.

pipsPrintError()

Synopsis

void pipsPrintError (ncId, result, cause, action)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate() or -1
int result
Pips error code
char *cause
String containing cause of error, e.g. filename
int action
If action = PipsExit then the description is printed and program ended; if action = PipsDontExit then only the error message is printed and the program continues.

Description

pipsPrintError() prints the errortext associated with the error code result and the string cause if not NULL. If action is PipsExit, then the program description in description is printed as well, ncabort (ncId) and ncclose (ncId) is called and the program is left with value (-result),

pipsPrintPerformance()

Synopsis

void pipsPrintPerformance (tid, perform, ntask, njobs)

Parameters

int tid []
An array with task Id's of the tasks
int perform[]
An array holding the number of jobs accomplished per task (so its size is ntask)
int ntask
Number of tasks spawned by pipsTaskManager
int njobs
Total number of accomplished jobs.

Description

pipsPrintPerformance() prints out a table on stderr stating how many jobs have been completed by which task (task Id's printed).

pipsReadAttDef()

Synopsis

int pipsReadAttDef (file, varName, attName, attType, attNum, attValueArray)

Parameters

FILE *file
File containing attribute definitions
char *varName
Returned variable name
char *attName
Returned attribute name
nc_type *attType
Returned nc_type of attribute
int *attNum
Number of values in attValueArray
char *attValueArray
Returned attribute values

Description

pipsReadAttDef() parses the contents of an open text file and returns names and values for one attribute definition. varName is the affected variable or NC_GLOBAL, attValueArray contains the new values for the attribute attName of variable varName. If the : in an attribute definition is followed by a ;, then attNum = 0, meaning, that this attribute has to be deleted.

pipsReadPnmHeader()

Synopsis

int pipsReadPnmHeader (file, width, height)

Parameters

FILE* file
Stream containing the image data
long *width
The width of a recognized image
long *height
The height of a recognized image

Description

pipsReadPnmHeader() identifies the type of image in the stream file, which has to be open, and reads the header up to the data body. The width and height are returned in width and height respectively. The function returns a symbol for the image type (see pips.h) If the image is not recognized or the stream is empty, then width and height are unchanged and PipsUnknown or EOF is returned.

pipsReadPnmValue()

Synopsis

int pipsReadPnmValue (file, imgType, data)

Parameters

FILE* file
Stream containing the image data
int imgType
One of the image types, recognized by pips
void* data
Pointer to sufficient memory for holding the data

Description

pipsReadPnmValue() reads one data value from the stream file and puts it in *data. The numbers of bytes read depend on the image type imgType. It returns the number of successfully read values (0 or 1).

pipsSelectNewJob()

Synopsis

void pipsSelectNewJob (int *newJobs, int *job)

Parameters

int *newJobs
Flag that indicates wheter or not new jobs are available
int njobs
The total number of jobs to process
int *job
Number of next new job to send

Description

pipsSelectNewJob() selects the next unprocessed job, if one is available; leaves *job unchanged, if not.

pipsStrApp()

Synopsis

int pipsStrApp (char **s1, char *s2)

Parameters

char **s1
A pointer to a string
char *s2
A string to append

Description

pipsStrApp() appends s2 to *s1, allocating memory before. s1 must not be a constant string as it is freed after construction of the concatenated string. The function returns the total length of the strings or 0 on an error.

pipsTaskManager()

Synopsis

void pipsTaskManager (prgName, ntask, tid)

Parameters

char* prgname
Name of program to spawn (usually argv[0])
int *ntask
Number of spawned tasks
int **tid
Array with task id's

Description

pipsTaskManager() spawns one program prgName on all available hosts and returns the number and ids of all spawned tasks.

pipsVarDef()

Synopsis

int pipsVarDef (ncId, varName, dataType, fileType, image, height, width)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate()
char *varName
Name of variable to create, default is imgName
nc_type *dataType
The datatype that is used in the variable
int *fileType
The type of image (to be) saved in the variable
long *image
The current number of images in varName (if exist)
long *height
Height of images, the variable should hold
long *width
Width of images, the variable should hold

Description

pipsVarDef() returns the properties of varName in dataType, fileType, image, height and width if the variable exists, otherwise it creates the unlimited dimension and then limited dimensions of size width and height, if they don't exist. It then creates a variable with name varName and dimensions unlimited, height, width, unless it exists. Image is set to the current value of the unlimited dimension, so the number of images per variable. The function leaves the define mode and returns the variable Id.

pipsVarInq()

Synopsis

int pipsVarInq (ncId, dataId, varName, dataType, images, height, width)

Parameters

int ncId
Identifier of a NetCDF file, returned by ncopen() or nccreate()
int dataId
The identifier of the current variable
char *varName
Name of variable to query
nc_type dataType
The nc type of the variable
long images
Returned number of images in dataId
long height
Returned height of images in dataId
long width
Returned width of images in dataId

Description

pipsVarInq() returns information about the variables of a netcdf file. If varName is NULL or its stringlength is 0, then subseqent calls with the same variables will return images from all variables starting with the first. If varName is not NULL then it must have space for at least MAX_NC_NAME characters, and the variable name will be returned. ncId and dataId should never have random values. Initialize them or set them to -1; Calls for different netcdf files or variables cannot be mixed. All internal variables are reset, if a new ncId or dataId is encountered. It returns true, as long as there are variables not returned yet.

pipsWritePnmHeader()

Synopsis

int pipsWritePnmHeader (file, imgType, width, height)

Parameters

FILE *file
Stream for the image data (must be open)
int imgType
Type of image
*width
The width of the image
*height
The height of the image

Description

pipsWritePnmHeader() writes a pnm header to the named stream, which must be open, leaving the file pointer at the proper position for the data.

pipsWritePnmValue()

Synopsis

int pipsWritePnmValue (file, imgType, data)

Parameters

FILE* file
Stream for the image data
int imgType
One of the image types, recognized by pips
void* data
Pointer to one data value to store

Description

pipsWritePnmValue() writes one data value from data to the named stream. The used format depends on imgType It returns 0 on success and EOF on failure.
Frank Heimes (Dr-Frank.Heimes@epost.de), 31 Jan 1995
Phone: +49 (721) 6091 - 424, FAX: +49 (721) 6091 - 233
http://members.tripod.de/DrFrankHeimes/pips/functions.html