evio  6.0
 All Data Structures Files Functions Variables Typedefs Macros Groups
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
handleevio handle
lengthpointer 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
handleevio handle
dictionarypointer 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.
lenpointer 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
handleevio handle
namecaller's char array which gets filled with file name or NULL if there is no name.
maxLengthlength 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
handleevio handle
tablepointer to array of uint32_t pointers which gets filled with an array of event pointers. If this arg = NULL, error is returned.
lenpointer 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
typenumerical 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
handleevio handle
requestcase independent string value of:
  1. "B" for setting target block size for writing in words
  2. "W" for setting writing (to file) internal buffer size in words
  3. "N" for setting max # of events/block
  4. "R" for setting run number (used in file splitting)
  5. "T" for setting run type (used in file splitting)
  6. "S" for setting file split size in bytes
  7. "M" for setting stream id (used in auto file naming)
  8. "V" for getting evio version #
  9. "H" for getting 14 ints of block header info (only 8 valid for version < 6)
  10. "E" for getting # of events in file/buffer
argp
  1. pointer to uin32_t containing new block size in 32-bit words if request = B, or
  2. pointer to uin32_t containing new buffer size in 32-bit words if request = W, or
  3. pointer to uin32_t containing new max # of events/block if request = N, or
  4. pointer to uin32_t containing run number if request = R, or
  5. pointer to character containing run type if request = T, or
  6. pointer to uint64_t containing max size in bytes of split file if request = S, or
  7. pointer to uin32_t containing stream id if request = M, or
  8. pointer to int32_t returning version # if request = V, or
  9. 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.
  10. 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
typenumerical 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
errorerror 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.