write routines

These routines handle opening the ev lib for writing to a file, buffer, or socket. More...

Functions
int	evWrite (int handle, const uint32_t *buffer)
	This routine writes an evio event to an internal buffer containing evio data. More...
int	evFlush (int handle)
	This function flushes any remaining internally buffered data to file/socket. More...
int	evWriteDictionary (int handle, char *xmlDictionary)
	This routine writes an optional dictionary as the first event of an evio file/socket/buffer. More...
int	evWriteFirstEvent (int handle, const uint32_t *firstEvent)
	This routine writes an optional "first event" after any dictionary in an evio file/socket/buffer. More...
int	evCreateFirstEventBlock (const uint32_t *firstEvent, int localEndian, void **block, uint32_t *words)
	This routine takes the given "first event" (evio bank) and places it into a properly formatted evio block (evio file format) with the proper bit set in the block header labeling content as a first event. More...
int	evStringsToBuf (uint32_t *buffer, int bufLen, char **strings, int stringCount, int *dataLen)
	This routine writes an array of strings, in evio format, into the given buffer. More...

Detailed Description

These routines handle opening the ev lib for writing to a file, buffer, or socket.

Function Documentation

int evCreateFirstEventBlock	(	const uint32_t *	firstEvent,
		int	localEndian,
		void **	block,
		uint32_t *	words
	)

This routine takes the given "first event" (evio bank) and places it into a properly formatted evio block (evio file format) with the proper bit set in the block header labeling content as a first event.

The returned buffer has been malloced and needs to be freed by the caller.

The localEndian arg tells this routine the endianness of the data in the firstEvent buffer. No swapping is done in this routine.

Parameters

firstEvent	pointer to evio bank defining the first event
localEndian	true (not 0) if first event and containing block are same as local endian, else false (0)
block	pointer which gets set to malloced block
words	int pointer which gets filled with length of returned data in 32-bit words

Returns

S_SUCCESS if successful

S_EVFILE_BADARG if firstEvent, block, or words args are NULL

S_EVFILE_ALLOCFAIL if cannot allocate memory

References EV_FIRSTEVENT_MASK, EV_LASTBLOCK_MASK, EV_VERSION, EVIO_SWAP32, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, and S_SUCCESS.

int evFlush

(

int

handle

)

This function flushes any remaining internally buffered data to file/socket.

Calling evClose automatically does this so it isn't necessary to call before closing. This method should only be used when writing events at such a low rate that it takes an inordinate amount of time for internally buffered data to be written to the file.

Calling this can kill performance if writing to a hard disk!

Parameters

handle

evio handle

Returns

S_SUCCESS if successful

S_EVFILE_BADHANDLE if bad handle arg

S_FAILURE error occurred during writing

References EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, evfilestruct::lastEmptyBlockHeaderExists, evfilestruct::rw, S_EVFILE_BADHANDLE, and S_SUCCESS.

int evStringsToBuf	(	uint32_t *	buffer,
		int	bufLen,
		char **	strings,
		int	stringCount,
		int *	dataLen
	)

This routine writes an array of strings, in evio format, into the given buffer.

This does NOT include any bank, segment, or tagsegment header. The length of the written data in bytes is returned in the "dataLen" arg. The written data is endian independent.

Parameters

buffer	buffer in which to place the evio format string data
bufLen	length of available room in which to write data in buffer in bytes
strings	array of strings to write as data
stringCount	number of strings in string array
dataLen	pointer to int which gets filled the length of the written data in bytes

Returns

S_SUCCESS if successful

S_EVFILE_BADARG if buffer or dataLen arg is NULL, bufLen < 4, stringCount < 0, or a string is NULL

S_EVFILE_TRUNC if not enough room in buffer

References S_EVFILE_BADARG, S_EVFILE_TRUNC, and S_SUCCESS.

int evWrite	(	int	handle,
		const uint32_t *	buffer
	)

This routine writes an evio event to an internal buffer containing evio data.

If that internal buffer is full, it is flushed to the final destination file/socket/buffer/pipe opened with routines evOpen, evOpenBuffer, or evOpenSocket. It writes data in evio version 4 format and returns a status.

Parameters

handle	evio handle
buffer	pointer to buffer containing event to write

Returns

S_SUCCESS if successful

S_EVFILE_BADMODE if opened for reading or appending to opposite endian file/buffer.

S_EVFILE_TRUNC if not enough room writing to a user-supplied buffer

S_EVFILE_BADARG if buffer is NULL

S_EVFILE_BADHANDLE if bad handle arg

S_EVFILE_ALLOCFAIL if cannot allocate memory

errno if file/socket write error

stream error if file stream error

Referenced by evwrite_().

int evWriteDictionary	(	int	handle,
		char *	xmlDictionary
	)

This routine writes an optional dictionary as the first event of an evio file/socket/buffer.

The dictionary is not included in any event count.

Parameters

handle	evio handle
xmlDictionary	string containing xml format dictionary or NULL to remove previously specified dictionary

Returns

S_SUCCESS if successful

S_FAILURE if already written events/dictionary

S_EVFILE_BADMODE if reading or appending

S_EVFILE_BADARG if dictionary in wrong format

S_EVFILE_ALLOCFAIL if cannot allocate memory

S_EVFILE_BADHANDLE if bad handle arg

errno if file/socket write error

stream error if file stream error

References evfilestruct::append, evfilestruct::blknum, evfilestruct::dictBuf, evfilestruct::dictionary, evfilestruct::dictLength, EV_WRITEBUF, EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, evfilestruct::eventCount, evfilestruct::rw, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_FAILURE, and evfilestruct::wroteDictionary.

int evWriteFirstEvent	(	int	handle,
		const uint32_t *	firstEvent
	)

This routine writes an optional "first event" after any dictionary in an evio file/socket/buffer.

This is only useful when writing files however. In that case all split files also have the first event written immediately after any dictionary. If writing to a buffer or socket, one could just as easily write the first event in the normal way.

Parameters

handle	evio handle
firstEvent	buffer containing first event, or NULL to remove previously specified first event

Returns

S_SUCCESS if successful

S_EVFILE_BADMODE if reading or appending

S_EVFILE_ALLOCFAIL if cannot allocate memory

S_EVFILE_BADHANDLE if bad handle arg

errno if file/socket write error

stream error if file stream error

References evfilestruct::commonBlkCount, evfilestruct::dictionary, EV_WRITEBUF, EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, evfilestruct::firstEventBuf, evfilestruct::firstEventLength, evfilestruct::rw, S_EVFILE_ALLOCFAIL, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, and S_SUCCESS.