get and set routines

These routines handle getting and setting evio parameters. More...

Functions
int	evGetFileName (int handle, char *name, size_t maxLength)
	This routine gets the name of the file currently being written to and opened with evOpen, Returned string may NOT be written into. More...
int	evGetBufferLength (int handle, uint32_t *length)
	This routine returns the number of bytes written into a buffer so far when given a handle provided by calling evOpenBuffer. More...
int	evIoctl (int handle, char *request, void *argp)
	This routine changes various evio parameters used in reading and writing. More...
int	evGetRandomAccessTable (int handle, uint32_t ***const table, uint32_t *len)
	This routine gets an array of event pointers if the handle was opened in random access mode. More...
int	evGetDictionary (int handle, char **dictionary, uint32_t *len)
	This routine gets the dictionary associated with this handle if there is any. More...
const char *	evGetTypename (int type)
	This routine returns a string representation of an evio type. More...
int	evIsContainer (int type)
	This routine return true (1) if given type is a container, else returns false (0). More...
char *	evPerror (int error)
	This routine returns a string describing the given error value. More...

Detailed Description

These routines handle getting and setting evio parameters.

Function Documentation

int evGetBufferLength	(	int	handle,
		uint32_t *	length
	)

This routine returns the number of bytes written into a buffer so far when given a handle provided by calling evOpenBuffer.

After the handle is closed, this no longer returns anything valid. In this evio version, this routine doesn't tell you much since all data isn't written out to buffer until evClose.

Parameters

handle	evio handle
length	pointer to int which gets filled with number of bytes written to buffer so far

Returns

S_SUCCESS if successful

S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::rwBytesOut, S_EVFILE_BADHANDLE, and S_SUCCESS.

int evGetDictionary	(	int	handle,
		char **	dictionary,
		uint32_t *	len
	)

This routine gets the dictionary associated with this handle if there is any.

Memory must be freed by caller if a dictionary was successfully returned.

Parameters

handle	evio handle
dictionary	pointer to string which gets filled with dictionary string (xml) if it exists, else gets filled with NULL. Memory for dictionary allocated here, must be freed by caller.
len	pointer to int which gets filled with dictionary string length (# chars) if there is one, else filled with 0. If this arg = NULL, no len is returned.

Returns

S_SUCCESS if successful

S_EVFILE_BADARG if dictionary arg is NULL

S_EVFILE_ALLOCFAIL if cannot allocate memory

S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::dictionary, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, and S_SUCCESS.

int evGetFileName	(	int	handle,
		char *	name,
		size_t	maxLength
	)

This routine gets the name of the file currently being written to and opened with evOpen, Returned string may NOT be written into.

Parameters

handle	evio handle
name	caller's char array which gets filled with file name or NULL if there is no name.
maxLength	length of array being passed in.

Returns

S_SUCCESS if successful.

S_FAILURE if file name is NULL.

S_EVFILE_TRUNC if char array too small to file filename and ending NULL.

S_EVFILE_BADMODE if not opened for writing to file.

S_EVFILE_BADHANDLE if bad handle arg, NULL name arg, or maxLength arg < 1.

References EV_WRITEFILE, evfilestruct::fileName, evfilestruct::rw, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_EVFILE_TRUNC, S_FAILURE, and S_SUCCESS.

int evGetRandomAccessTable	(	int	handle,
		uint32_t ***const	table,
		uint32_t *	len
	)

This routine gets an array of event pointers if the handle was opened in random access mode.

User must not change the pointers in the array or the data being pointed to (hence the consts in the second parameter).

Parameters

handle	evio handle
table	pointer to array of uint32_t pointers which gets filled with an array of event pointers. If this arg = NULL, error is returned.
len	pointer to int which gets filled with the number of pointers in the array. If this arg = NULL, error is returned.

Returns

S_SUCCESS if successful

S_EVFILE_BADMODE if handle not opened in random access mode

S_EVFILE_BADARG if table or len arg(s) is NULL

S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::eventCount, evfilestruct::pTable, evfilestruct::randomAccess, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, and S_SUCCESS.

const char* evGetTypename

(

int

type

)

This routine returns a string representation of an evio type.

Parameters

type	numerical value of an evio type

Returns

string representation of the given type

int evIoctl	(	int	handle,
		char *	request,
		void *	argp
	)

This routine changes various evio parameters used in reading and writing.

It changes the target block size (in 32-bit words) for writes if request = "B". If setting block size fails, writes can still continue with original block size. Minimum size = EV_BLOCKSIZE_MIN (1024) words. Max size = EV_BLOCKSIZE_MAX (33554432) words.

It changes size of buffer (in 32-bit words) for writing to file/socket/pipe if request = "W". Must be >= target block size (see above) + header (EV_HDSIZ). Max size = EV_BLOCKSIZE_MAX + EV_HDSIZ (33554444) words.

It changes the maximum number of events/block if request = "N". It only goes up to EV_EVENTS_MAX (100,000). Used only in version 4.

It sets the run number used when auto naming while splitting files being written to if request = "R". Used only in version 4.

It sets the run type used when auto naming while splitting files being written to if request = "T". Used only in version 4.

It changes the number of bytes at which to split a file being written to if request = "S". If unset with this function, it defaults to EV_SPLIT_SIZE (2GB). NOTE: argp must point to 64 bit integer (not 32 bit)! Used only in version 4.

It sets the stream id used when auto naming files being written to if request = "M". Used only in version 4.

It returns the version number if request = "V".

It returns a pointer to the EV_HDSIZ_V6 block header ints if request = "H". This pointer must be freed by the caller to avoid a memory leak.

It returns the total number of events in a file/buffer opened for reading or writing if request = "E". Includes any event added with evWrite call. Used only in version 4.

NOTE: all request strings are case insensitive. All version 4 commands to version 3 files are ignored.

Parameters

handle	evio handle
request	case independent string value of: "B" for setting target block size for writing in words "W" for setting writing (to file) internal buffer size in words "N" for setting max # of events/block "R" for setting run number (used in file splitting) "T" for setting run type (used in file splitting) "S" for setting file split size in bytes "M" for setting stream id (used in auto file naming) "V" for getting evio version # "H" for getting 14 ints of block header info (only 8 valid for version < 6) "E" for getting # of events in file/buffer
argp	pointer to uin32_t containing new block size in 32-bit words if request = B, or pointer to uin32_t containing new buffer size in 32-bit words if request = W, or pointer to uin32_t containing new max # of events/block if request = N, or pointer to uin32_t containing run number if request = R, or pointer to character containing run type if request = T, or pointer to uint64_t containing max size in bytes of split file if request = S, or pointer to uin32_t containing stream id if request = M, or pointer to int32_t returning version # if request = V, or address of pointer to uint32_t returning pointer to 14 uint32_t's of block header if request = H (only 8 valid for version < 6). This pointer must be freed by caller since it points to allocated memory. pointer to uin32_t returning total # of original events in existing file/buffer when reading or appending if request = E

Returns

S_SUCCESS if successful

S_FAILURE if using sockets when request = E

S_EVFILE_BADARG if request is NULL or argp is NULL

S_EVFILE_BADFILE if file too small or problem reading file when request = E

S_EVFILE_BADHANDLE if bad handle arg

S_EVFILE_ALLOCFAIL if cannot allocate memory

S_EVFILE_UNXPTDEOF if buffer too small when request = E

S_EVFILE_UNKOPTION if unknown option specified in request arg

S_EVFILE_BADSIZEREQ when setting block/buffer size - if currently reading, have already written events with different block size, or is smaller than min allowed size (header size + 1K), or is larger than the max allowed size (5120000 words); when setting max # events/blk - if val < 1

errno if error in fseek, ftell when request = E

References evfilestruct::append, evfilestruct::blkEvCount, evfilestruct::blkEvMax, evfilestruct::blknum, evfilestruct::blkSizeTarget, evfilestruct::buf, evfilestruct::bufRealSize, evfilestruct::bufSize, evfilestruct::currentHeader, evfilestruct::dataBuf, evfilestruct::dataLeft, evfilestruct::dataNext, EV_BLOCKSIZE_MAX, EV_BLOCKSIZE_MIN, EV_EVENTS_MAX, EV_HD_VER, EV_HDSIZ_V6, EV_READBUF, EV_READFILE, EV_READPIPE, EV_READSOCK, EV_VERSION_MASK, EV_WRITEBUF, EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, evfilestruct::eventLengths, initBlockHeader2, evfilestruct::left, evfilestruct::next, evfilestruct::runNumber, evfilestruct::runType, evfilestruct::rw, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADSIZEREQ, S_EVFILE_UNKOPTION, S_SUCCESS, evfilestruct::split, evfilestruct::streamId, UINT64_MAX, and evfilestruct::version.

Referenced by evioctl_().

int evIsContainer

(

int

type

)

This routine return true (1) if given type is a container, else returns false (0).

Parameters

type	numerical value of an evio type (eg. type = 0x10 = bank, returns 1)

Returns

1 if given type is a container, else 0.

char* evPerror

(

int

error

)

This routine returns a string describing the given error value.

The returned string is a static char array. This means it is not thread-safe and will be overwritten on subsequent calls.

Parameters

error

error condition

Returns

error string

References S_EVFILE, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADBLOCK, S_EVFILE_BADFILE, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_EVFILE_BADSIZEREQ, S_EVFILE_TRUNC, S_EVFILE_UNKOPTION, S_EVFILE_UNXPTDEOF, S_FAILURE, and S_SUCCESS.