flcbyt_buffer Class Reference

A C++ stream buffer to use with istream/ostream. More...

#include <FLCBYTBF.hpp>

Inheritance diagram for flcbyt_buffer:

Public Member Functions
	flcbyt_buffer (const char *filstr, const char *fmtstr, char **state=NULL, size_t buff_sz=4096, size_t put_back=1)
	Constructor for a FLUC byte interface streambuf implementation.
	~flcbyt_buffer ()
	Flushes buffers and closes the file.
std::string	close (const int statfmt=FLMOUT_FORMAT_LST)
	Flushes all internal buffers and closes the file.
int	error ()
	Returns an error code for the last byte interface operation.
std::string	errormsg ()
	Returns an error message for the last byte interface operation.

Static Public Member Functions
static std::string	errortrace ()
	Returns a FLAM error trace.
static std::string	version ()
	Retrieves version information.
static std::string	about ()
	Retrieves about information.
static std::string	license ()
	Retrieves license information.
static std::string	help (const int what, const int depth, const char *path)
	Returns help information about the file and format strings.
static std::string	syntax (const int what, const int depth, const char *path)
	Returns syntax information about the file and format strings.

Detailed Description

A C++ stream buffer to use with istream/ostream.

flcbyt_buffer is a streambuf implementation that allows to use the C++ stream facilities to read and write files via FLUC. It is supposed to be passed to an istream or ostream object. The stream buffer is backed by the FLUC byte interface. (fcb*() functions)

Constructor & Destructor Documentation

flcbyt_buffer()

flcbyt_buffer::flcbyt_buffer ( const char * filstr, const char * fmtstr, char ** state = NULL, size_t buff_sz = 4096, size_t put_back = 1 )

explicit

Constructor for a FLUC byte interface streambuf implementation.

Calls fcbopen(filstr, fmtstr) of the FLUC byte interface to open a normal file, a member in a FLAM4FILE, a GZIP file or a member in a concatenated GZIP-, BZIP- or XZ-File or some other supported file format. It supports base encoding, encryption, compression, character conversion and text formatting, among others.

The handle obtained from fcbopen() is stored internally for subsequent operations, alongside with an internal buffer.

The file definition string uses the same syntax as the read or write method of the FLCL CONV command. The complete syntax and help can be determined with the corresponding functions below. The zero-terminated string must start with 'read.' or 'write.' followed by the corresponding method (binary/char/text/flam4/xml/...).

Examples:

"read.text(file='test.txt')"
"write.binary(file='test.gz' comp.gzip(level=BEST))"

For more information, please use:

'fcbhelp/syntax(FLC_READ_FILE,10,NULL)'
'fcbhelp/syntax(FLC_WRITE_FILE,10,NULL)'

The format string uses the syntax of the 'format' union which was specially designed for the byte interface to format a byte stream based on the FLAM elements. The zero-terminated string must start with 'format.' followed by the corresponding method.

Examples:

"format.text(method=CRLF suptws ccsid='UTF-16LE')"
"format.bin()"
"format.char(ccsid=DEFAULT)"
"format.record(ccsid='IBM-1141')"

For more information, please use:

'fcbhelp/syntax(FLC_READ_FORMAT,10,NULL)'
'fcbhelp/syntax(FLC_WRITE_FORMAT,10,NULL)'

The file string defines how the FLAM elements are read from or written to the file. The format string defines how the FLAM elements are converted into a byte stream or records.

The state parameter can be used to (optionally) transfer some internal state from an input stream to an output stream. The internal state can be used to transfer attributes/values/information from a "read.*" to a "write.*" operation. The state string contains mainly file attributes which must be known to fill header information for archives (GZIP, FLAM) correctly. You are responsible to free() the string when you no longer need the state string obtained from a read operation.

The parameter is a pointer to a pointer to a string. On read mode, if you pass a non-null pointer, the pointer points to a string pointer pointing to the state string after the open procedure. On write mode, if you pass a non-null pointer to a pointer to a state string, this state string is used to set the internal state. Otherwise, the state will be initialized with default values.

You can look up the state string syntax and help with the corresponding functions below. The zero-terminated string must start with 'state(' followed by the corresponding value definitions and closed with ')'.

Example:

"state(member='test.txt' recf=FBA recl=120)"

For more information, please use:

'fcbhelp/syntax(FLC_STATE,10,NULL)'

Below you can find two examples:

1. Write only

   char* state="STATE(file='test.txt')";
   flcbyt_buffer writebuf("write.text(comp.gzip())","format.text()",&state);
   std::ostream out(&writebuf);

2. Read and write

   char* state=NULL;
   flcbyt_buffer readbuf("read.text(file='test.txt')","format.text()",&state);
   flcbyt_buffer writebuf("write.text(comp.gzip())","format.text()",&state);
   std::istream in(&readbuf);
   std::ostream out(&writebuf);
   if (state)
      free(state);

In both cases, the member name for the original file in the GZIP header is 'test.txt'.

Parameters

[in]	filstr	File string with READ/WRITE instructions
[in]	fmtstr	Format string with FORMAT instructions
[in,out]	state	Pointer to a pointer to a string with STATE values (optional, must be free()d on "read.*" if you provide a non-null pointer)
[in]	buff_sz	Size of the internal buffer (optional, default: 4096)
[in]	put_back	Number of bytes you are guaranteed to be able to put back (only for istream, optional, default: 1)

Exceptions

flam_exception

Thrown if the file cannot be opened by fcbopen()

~flcbyt_buffer()

flcbyt_buffer::~flcbyt_buffer

(

)

Flushes buffers and closes the file.

Unless close() has been called, calls fcbclose() to flush all buffers and close the file. There will be no indication if an error occurs while flushing buffers (except an incomplete output file). So, it is recommended to call close() which throws an exception on error.

Member Function Documentation

close()

std::string flcbyt_buffer::close

(

const int

statfmt = FLMOUT_FORMAT_LST

)

Flushes all internal buffers and closes the file.

Flushes all internal buffers and closes the file by calling fcbclose(). If an error occurs, a flam_exception is thrown, containing an error message.

It is recommended to call close() after the last operation on the file. Otherwise, there will be no indication if data that still resides in internal buffers fails to write to the file, resulting in an incomplete file.

This function returns statistics information in readable string format. You can define the format of the string. The default is FLMOUT_FORMAT_LST, resulting in a simple list of strings with each line separated by '\n'.

Parameters

statfmt

The returned statistics format (Possible values: FLMOUT_FORMAT_* [see FLAMDEF.h])

Returns

A human-readable string with statistics information

error()

int flcbyt_buffer::error

(

)

Returns an error code for the last byte interface operation.

Returns the error code for the last FLUC byte interface operation. Must not be called after a calling close() (undefined behavior). The error code is the same as returned by fcberror().

Returns

A non-zero value if the last operation resulted in an error, zero otherwise

errormsg()

std::string flcbyt_buffer::errormsg

(

)

Returns an error message for the last byte interface operation.

Returns an error message for the last FLUC byte interface operation on the file. Must not be called after a calling close() (undefined behavior). The error message is the same as returned by fcberrms(fcberror()).

Returns

A non-zero value if the last operation resulted in an error, zero otherwise

errortrace()

static std::string flcbyt_buffer::errortrace ( )

static

Returns a FLAM error trace.

This function can be used to get an error trace for the last byte interface operation. The error trace contains the FLAM error stack. If parsing the file or format string failed, the error trace also contains the complete error stack of the Command Line Parser (FLAMCLP).

Returns

A multi-line string containing the current FLAM error trace

version()

static std::string flcbyt_buffer::version ( )

static

Retrieves version information.

This function returns a string with version information for each used component. This should be used in a support case.

Returns

String with version information

about()

static std::string flcbyt_buffer::about ( )

static

Retrieves about information.

This function returns a string with about information for this library on multiple lines and license information for used external libraries.

Returns

String with about information

license()

static std::string flcbyt_buffer::license ( )

static

Retrieves license information.

This function can be used to get the current license text on multiple lines. The license text defines the permissible use of this library.

Returns

String with license information

help()

static std::string flcbyt_buffer::help ( const int what, const int depth, const char * path )

static

Returns help information about the file and format strings.

This function can be used to get all help messages or man pages for each parameter in the file and format strings. If depth 0 or greater then 9 aliases are provided. In all other cases aliases are suppressed. Please use fcbsyntax() to see possible aliases for the same argument.

Parameters

[in]	what	Integer constant for the corresponding file or format string (one of FLC_READ_* or FLC_WRITE_*)
[in]	depth	Number of levels to display (0-Man page, 1-One Level, 2-Two Level, ..., <9-All)
[in]	path	Path (e.g. read.text.ccsid) to limit help to the (sub)tree of a certain object

Returns

a string containing the help information on several lines, in case of an error the string is empty.

syntax()

static std::string flcbyt_buffer::syntax ( const int what, const int depth, const char * path )

static

Returns syntax information about the file and format strings.

This function can be used to determine the complete syntax of the file and format strings.

Parameters

[in]	what	Integer constant for the corresponding file or format string (one of FLC_READ_* or FLC_WRITE_*)
[in]	depth	Number of levels to display (0-Man page, 1-One Level, 2-Two Level, ..., <9-All)
[in]	path	Path (e.g. read.text.ccsid) to limit syntax to the (sub)tree of a certain object

Returns

a pointer to a static area with a zero-terminated string containing the syntax information in one (level == 1) or several lines (level > 1), in case of an error the string is empty.

---

The documentation for this class was generated from the following file:

• FLCBYTBF.hpp