---

BFO.h File Reference

Balloon Flight Output, Interface. More...

Typedefs
typedef _BFO_ocb	BFO_ocb
	Typedef for struct _BFO_ocb.
typedef int(*	BFO_dskWriteRtn )(int fd, const void *buf, int size)
	Callback signature for writing data files. More...
Functions
BFO_ocb *	BFO_get (void)
	Returns a pointer to the BFO output control block. More...
int	BFO_ocb_sizeof (void)
	Returns the size of the BFO output control block. More...
int	BFO_msg_sizeof (void)
	Returns the size of a BFO message. More...
int	BFO_ocb_init (BFO_ocb *bfo, BFO_dskWriteRtn wrt, void *msgs, int msgs_size, struct _BFA_acb *acb)
	Initializes the Output Control Block. More...
int	BFO_flush (BFO_ocb *bfo)
	Ques a message to flush data from all internal BFO buffers. More...
int	BFO_synch (BFO_ocb *bfo)
	Attempts to ensure that all previous requests have been acted upon. More...
int	BFO_write (BFO_ocb *bfo, struct _BFU_fileDsc *dsc)
	Ques a message to write the specified events to the output streams. More...
void	BFO_dskBlkSizeSet (BFO_ocb *bfo, int blkSize)
	Sets the disk blocking size. More...
int	BFO_dskDisable (BFO_ocb *bfo)
	Disables writing to the disk. More...
int	BFO_dskEnable (BFO_ocb *bfo)
	Enables writing to the disk. More...
void	BFO_dskFileSet (BFO_ocb *bfo, int fd)
	Simply routine to set the current file descriptor. More...
int	BFO_dskFileGet (BFO_ocb *bfo)
	Simply query routine to return the current file descriptor. More...
void	BFO_biuSamplingSet (BFO_ocb *bfo, int sampleRate, int limit)
	Sets the parameters controlling the BIU sampling factors. More...
int	BFO_biuDisable (BFO_ocb *bfo)
	Disables writing to the BIU sampling stream. More...
int	BFO_biuDstSet (BFO_ocb *bfo, unsigned int ip, unsigned short port)
	Sets the destination IP address. More...
int	BFO_biuEnable (BFO_ocb *bfo)
	Enables writing to the BIU sampling stream. More...

---

Detailed Description

Balloon Flight Output, Interface.

Author:

JJRussell - russell@slac.stanford.edu

---

Typedef Documentation

BFO_dskWriteRtn

Callback signature for writing data files. The callback signature exactly matches that of the standard UNIX write routine.

---

Function Documentation

int BFO_biuDisable (  BFO_ocb *    bfo )

Disables writing to the BIU sampling stream. Parameters: bfo  The Output Control Block Return values: 0, if  the BIU was already disabled 1, if  the BIU was previously enabled.

void BFO_biuDstSet (  BFO_ocb *    bfo, unsigned int    ip, unsigned short    port )

Sets the destination IP address. Parameters: bfo  The Output Control Block ip  The destination IP address. port  The destination port number. Returns: Status.

int BFO_biuEnable (  BFO_ocb *    bfo )

Enables writing to the BIU sampling stream. Parameters: bfo  The Output Control Block Return values: 0, if  the BIU was already enabled 1, if  the BIU was previously disabled. As a side effect, this routine restores the credit limit to its maximum. There seemed to be only 2 sensible choices, setting it to 0, and starting the timer, or setting to the maximum.

void BFO_biuSamplingSet (  BFO_ocb *    bfo, int    sampleRate, int    limit )

Sets the parameters controlling the BIU sampling factors. Parameters: bfo  The Output Control Block sampleRate  The sample rate expressed in bytes/sec. This number must be less than 2**22, i.e. around 4Mbytes/sec. limit  An upper limit on the number of bytes that one can accumulate. If this is specified as 0, the it is set to the amount on can accumulate in 1 second. Sets the sampling parameters for the BIU stream. This stream is allowed to output a stream of data at no more than 'sampleRate', expressed in bytes/second. In order to not allow pauses in the flow of data to accumulate a big backlog (imagine that little to no data flows for a long period of time, then deltaT * sampleRate will be a very big number), the amount one can 'save' is limited to some amount. This is essentially the second parameter.

void BFO_dskBlkSizeSet (  BFO_ocb *    bfo, int    blkSize )

Sets the disk blocking size. Parameters: bfo  The Output Control Block blkSize  The block size, in bytes. Sets the blocking size. Output will be written to the disk only when this many bytes are accumulated or an explicit write is forced using a BFO_flush() operation.

int BFO_dskDisable (  BFO_ocb *    bfo )

Disables writing to the disk. Parameters: bfo  The Output Control Block Return values: 0, if  the writing was already disabled 1, if  the writing was previously enabled. Warning: This routine is meant to be used only in a test situation. This routine is dangerous to use unless precautions are taken. Because the output is being buffered up, arbitrary disabling can leave the state of buffer in an inconsistent state. Always make sure that all output is flushed and that no more new output is sent before a call to this routine is issued. For disk writing efficiency, the previous file should be closed out and a new one opened. This is because the writing has been stopped before a new cluster is completely filled, leaving the disk driver always reading the partial record from disk, appending the new stuff, then writing it all back out. Since the disk writing routines always submit their output in clusters, one is permanently out of synch.

int BFO_dskEnable (  BFO_ocb *    bfo )

Enables writing to the disk. Parameters: bfo  The Output Control Block Return values: 0, if  the writing was already disabled 1, if  the writing was previously enabled. Warning: See BFO_dskDisable() for usage warnings.

int BFO_dskFileGet (  BFO_ocb *    bfo )

Simply query routine to return the current file descriptor. Parameters: bfo  The Output Control Block Returns: The file descriptor This is a simply query routine to return the current file descriptor. This saves the user from having to buffer the file descriptor.

int BFO_dskFileSet (  BFO_ocb *    bfo, int    fd )

Simply routine to set the current file descriptor. Parameters: bfo  The Output Control Block fd  The file descriptor. This is a simple routine to set the current file descriptor. Note that it is the user's responsibility to ensure that all previous activity on this stream is complete. This is usually accomplished by performing a BFO_flush() followed by a BFO_synch().

int BFO_flush (  BFO_ocb *    bfo )

Ques a message to flush data from all internal BFO buffers. Parameters: bfo  The output control block to perform the flush on. Returns: Status Flushes the whatever is in the disk buffers. This only posts the last remaining piece for writing. Because this only posts a message requesting a flush, use BFO_synch() to ensure that flush message has been consumed. Warning: It is imperative that no more data be written to the disk until after this operation has been completed. The stream should be disabled and BFO_synch().

int BFO_get (  void    )

Returns a pointer to the BFO output control block. Returns: A pointer to the BFO output control block.

int BFO_msg_sizeof (  void    )

Returns the size of a BFO message. Returns: The BFO message size. This routine allows the user to control the allocation and management of the pool messages used by the BFO routines to post messages across the FORK tasks. The customary usage would be to call BFO_msg_sizeof(), multiple the returned message size by however many messages that the user wished to use, allocate the that amount of memory, and, finally pass the allocated memory and its size to BFO_ocb_init().

int BFO_ocb_init (  BFO_ocb *    bfo, BFO_dskWriteRtn    wrt, void *    msgs, int    msgs_size, struct _BFA_acb *    acb )

Initializes the Output Control Block. Parameters: bfo  The Output Control Block to initialize. wrt  The routine to perform the writing. msgs  A pool of memory to be used for the messages. msgs_size  The size of msgs area acb  The allocation control structure. Returns: Status This routine only initialize properties of the BFO which are very static, ie the are very unlikely to change as long as the BFO control structure is in existence. Other properties, such as the file to write to and the BIU sampling parameters can be changed during the BFO stream's lifetime.

int BFO_ocb_sizeof (  void    )

Returns the size of the BFO output control block. Returns: The size of the BFO output control block. Returns the size of the Output Control Block. This includes the size of the FORK and Free Packet Pool control blocks. This allows the user to control and manage the allocation of this memory.

int BFO_synch (  BFO_ocb *    bfo )

Attempts to ensure that all previous requests have been acted upon. Parameters: bfo  The output control block to synchronize. Returns: Status. Currently the only failure modes are of the irrecoverable variety, ie program error or corruption. This routine can never really ensure that all the data is actually physically on the disk. The UNIX IO routines have no mechanism to enforce such a wish. All this routine can really do is ensure that all previous messages have been acted on. What one can do is perform a BFO_flush() operation, ensuring that all data within the internal BFO buffers are sent to disk with a UNIX 'write' operation. This should then be followed by a BFO_synch(), ensuring the flush message itself has been consumed.

int BFO_write (  BFO_ocb *    bfo, struct _BFU_fileDsc *    fileDsc )

Ques a message to write the specified events to the output streams. Parameters: bfo  The Output Control Block fileDsc  The 'file' descriptor describing the events to write. Returns: Status This routine posts a message to the write the specified events to the output streams. It does not actually perform the IO itself. To ensure that this message has been consumed, call BFO_synch().

---