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