I/O Class Descriptions

class ostream

Provide for Stream Insertion

SYNOPSIS

#include <iostream.h>

class ostream : virtual public ios
{
public:
   ostream(streambuf *buf);
   virtual ~ostream();

   int opfx();

   void osfx();

   ostream& operator <<(char c);
   ostream& operator <<(signed char c);
   ostream& operator <<(unsigned char c);

   ostream& operator <<(const char *str);
   ostream& operator <<(const unsigned
                        char *str);
   ostream& operator <<(const signed
                        char *str);

   ostream& operator <<(short sh);
   ostream& operator <<(unsigned short sh);

   ostream& operator <<(int i);
   ostream& operator <<(unsigned int i);

   ostream& operator <<(long l);
   ostream& operator <<(unsigned long l);

   ostream& operator <<(float f);
   ostream& operator <<(double d);

   ostream& operator <<(void *vp);

   ostream& operator <<(streambuf *buf);

   ostream& operator <<(ostream&(*f)
                       (ostream&));
   ostream& operator <<(ios&(*f)(ios&));

   ostream& put(char c);

   ostream& write(const char *str, int n);
   ostream& write(const signed char *str,
                  int n);
   ostream& write(const unsigned char *str,
                  int n);
   ostream& flush();

   streampos tellp();

   ostream& seekp(streampos pos);
   ostream& seekp(streamoff offset,
                  seek_dir place);
};
ostream& endl(ostream&);
ostream& ends(ostream&);
ostream& flush(ostream&);

DESCRIPTION

class ostream is declared in the iostream.h header file and is the base class for those classes that support only output. It includes all the basic insertion operators (formatted output) on fundamental C++ types, as well as a number of unformatted output functions and functions designed to change the stream position. In addition, some output manipulators are defined for use with this class.

PARENT CLASSES

class ostream inherits characteristics from class ios . See the description of this parent class for the details on functions and operators that are inherited.

CONSTRUCTORS

class ostream defines one constructor:

ostream::ostream(streambuf *buf)

initializes an ostream and associates a streambuf with it.

DESTRUCTORS

Here is the class ostream destructor:

virtual ostream::~ostream()

closes the ostream.

PREFIX AND SUFFIX OUTPUT FUNCTIONS

Certain operations are defined to happen either before or after formatted output through a ostream . The prefix operations are done by ostream::opfx() and the suffix operations are done by ostream::osfx() .

int ostream::opfx()

performs prefix operations for an ostream . This function returns 0 and does nothing else if any bits in the stream's I/O state are set; it returns 1 otherwise. If the ostream is tied (see tie() ) to another, the other stream is flushed (see flush() ).

By convention, opfx() is called before any formatted output operation on a stream. If it returns 0 (meaning one or more bits are set in the stream's I/O state), the output operation is not performed. Each of the built-in inserters follows this convention. User-defined formatted output functions should also follow this convention by calling this function and checking the return code before doing any output.

void ostream::osfx()

performs suffix operations on the stream. If ios::unitbuf is set, this ostream is flushed. If ios::stdio is set, cout and cerr are flushed. This function should be called at the end of any formatted output function that does unformatted output on the ostream . It need not be called if the last output operation on the ostream was formatted.

FORMATTED OUTPUT FUNCTIONS

The functions named operator << are called inserters (because they insert values into the output stream). All inserters are formatted output operations and as such follow the formatted output conventions mentioned previously.

All of the inserters do the following: First, they call opfx() , and if it returns 0, they do nothing else. If there is no error, they then convert the input argument to a converted value (a sequence of characters), based on the argument's type and value and on the formatting flags set for the stream. The rules for construction of the converted value are given here for each inserter.

Once a converted value has been determined, it is copied, possibly with the addition of fill characters, to an output field. The characters of the output field are then inserted into the stream's buffer. The ios::width() function for the stream determines the minimum number of characters in the output field. If the converted value had fewer characters, fill characters (defined by the value of ios::fill() for the stream) are added to pad out the field. The placement of fill characters is as follows::

ios::right

places the converted value in the rightmost portion of the field (leading padding).

ios::left

places the converted value in the leftmost portion of the field (trailing padding).

ios::internal

places the sign and base indicators of the converted value in the leftmost portion of the field and the remainder in the rightmost portion (internal padding).

Note that truncation cannot occur when copying the converted value to an output field, regardless of the value of width() .

Once the converted value is constructed and the field is padded to be at least ios::width() characters wide, ios::width() is reset to 0 and osfx() is called. All inserters indicate errors by setting I/O state flags in the ostream , as necessary. Inserters always return a reference to their ostream argument.

Here are the formatted output functions.

ostream& ostream::operator <<(char c)

ostream& ostream::operator <<(signed
char c)

ostream& ostream::operator <<(unsigned
char c)

convert the argument to the char c .

ostream& ostream::operator <<(const
char *str)

ostream& ostream::operator <<(const
unsigned char *str)

ostream& ostream::operator <<(const
signed char *str)

convert the argument to a sequence of chars , up to but not including a ' \0 ' character, pointed to by str .

ostream& ostream::operator <<(short sh)

ostream& ostream::operator <<(unsigned
short sh)

ostream& ostream::operator <<(int i)

ostream& ostream::operator <<(unsigned
int i)

ostream& ostream::operator <<(long l)

ostream& ostream::operator <<(unsigned
long l)

convert the value of the argument to a sequence of digits, preceded by a leading ' - ' if the argument is negative.

If the following format flags within the ostream are set, they affect the converted value as follows:

ios::showpos

causes a leading ' + ' to be included in the converted value if the value is positive.

ios::dec, ios::oct, and ios::hex

determine the base used for the converted value.

ios::showbase

causes the converted value to indicate the appropriate base as follows:

decimal	makes no change to the converted value.
octal	prefixes the converted value with a single ' 0 ' digit. If the value is 0, there is only one zero digit.
hexadecimal	prefixes the converted value with ' 0x '. If ios::uppercase is set, a leading ' 0X ' is used instead.

If both a sign representation (+ or -) and a base representation appear in the converted value, the sign appears first.

ostream& ostream::operator <<(float f)

ostream& ostream::operator <<
(double d)

convert the argument to a character representation of its value in one of two formats:

• fixed notation (' ± ddd.ddd ')
• scientific notation (' ± d.ddde± dd ').

These formats are described in detail in enum format_state . The format of the converted value is affected by the settings of the following format flags:

ios::fixed or ios::scientific

determines the overall representation format. If neither is set, then the overall format is scientific if the exponent is less then -4 or greater than the precision. Fixed notation is chosen otherwise.

ios::showpoint

causes the decimal point to be shown, followed by at least one digit. If showpoint is not set and all digits after the decimal point are zero, these digits and the decimal point are dropped.

ios::uppercase

causes the ' e ' in scientific notation to be ' E ' instead.

ios::showpos

causes a leading '+' to be output for positive values.

ostream& ostream::operator <<
(void *vp)

converts the value of the pointer vp to an unsigned long and represents it as if ios::hex and ios::showbase were set.

ostream& ostream::operator <<
(streambuf *buf)

fetches all the characters in buf and inserts them into the output stream, provided no bits are set in buf 's I/O state. No padding is done. If any bits are set in buf 's I/O state, this function returns immediately.

ostream& ostream::operator <<
(ostream&(*f) (ostream&))

ostream& ostream::operator <<
(ios&(*f)(ios&))

are for support of simple manipulators. Although these operators resemble an insertion in appearance, they are used to manipulate the stream rather than to insert characters into it. The argument to either of these operators is a manipulator function that modifies its ios or ostream argument in some manner.

UNFORMATTED OUTPUT FUNCTIONS

The following functions are for support of unformatted output to a stream. Because they are unformatted operations they do not call opfx() and osfx() ; however, these functions do check to see whether any I/O state flags are set for the ostream and take no further action if any are found. All inserters indicate errors by setting I/O state flags in the ostream . Each of these functions returns a reference to its argument ostream .

ostream& ostream::put(char c)

inserts its argument into the stream.

ostream& ostream::write(const char *str,
int n)

ostream& ostream::write(const signed
char *str, int n)

ostream& ostream::write(const unsigned
char *str, int n)

insert n characters starting at str into the stream. The characters are treated as plain chars independent of their actual type. The null character is treated the same as any other character.

OTHER MEMBER FUNCTIONS

The following functions are also members of class ostream .

ostream& ostream::flush()

calls rdbuf()->sync() . For more information, refer to the description of streambuf::sync() .

streampos ostream::tellp()

returns the stream's current put pointer position. For more information, refer to the descriptions of streambuf::seekoff() and streambuf::seekpos() .

ostream& ostream::seekp(streampos pos)

ostream& ostream::seekp(streamoff offset,
seek_dir place)

reposition the stream's put pointer. For more information, refer to the descriptions of streambuf::seekoff() and streambuf::seekpos() .

MANIPULATORS

The following functions are called manipulators. They are intended to be used with the inserters to manipulate the stream in specified ways. These manipulators do nothing if any of the stream's I/O state flags are set. They signal errors by setting flags in the stream's I/O state. They each return their argument.

ostream& endl(ostream&)

inserts a ' \n ' character into the stream. Here is an example:

#include <iostream.h>

float mynum=3.2;
   // Writes "mynum is:" and the value
      of mynum on one line.
cout << "mynum is: " << mynum << endl;

ostream& ends(ostream&)

inserts a ' \0 ' character into the stream. Here is an example, using a strstream :

#include <iostream.h>
strstream mystream;
float mynum=3.2;

   // Writes mynum to mystream.
mystream << "mynum is: " << mynum <<
   ends;

ostream& flush(ostream&)

calls ostream.flush() .

SEE ALSO

class ios, class iostream, class istream

class stdiostream

Provide Formatted I/O in a Mixed C and C++ Environment

SYNOPSIS

#include <stdiostream.h>

class stdiostream : public iostream
{
public:
   stdiostream(FILE *file);

   FILE* stdiofile();

   stdiobuf* rdbuf();
};

DESCRIPTION

class stdiostream is declared in the stdiostream.h header file. It provides iostream access to an external file accessed by C functions using the ANSI standard I/O interfaces declared in stdio.h . Use of class stdiostream enables a program to use stdio output and C++ iostream output in the same output file. Similarly, class stdiostream enables your program to use stdio input and C++ iostream input to process the same input file.

PARENT CLASSES

class stdiostream inherits characteristics from class iostream , which in turn inherits characteristics from class istream , class ostream , and class ios . See the descriptions of these parent classes for the details on functions and operators that are inherited.

CONSTRUCTORS

class stdiostream has one constructor:

stdiostream::stdiostream(FILE *file)

creates a stream from the open FILE* file . The constructor assumes that the file is open.

MEMBER FUNCTIONS

The following descriptions give the purpose and return type of the member functions, as well as any other appropriate information.

stdiostream::FILE* stdiofile()

returns the FILE* associated with this stream.

stdiobuf* stdiostream::rdbuf()

returns a pointer to the stdiobuf associated with the stream.

SEE ALSO

class stdiobuf

class streampos

Mark a Stream Location

SYNOPSIS

#include <iostream.h>

class streampos
{
public:
   streampos();
   streampos(long n);
   operator long();
   fpos_t* fpos();
};

DESCRIPTION

class streampos is declared in the iostream.h header file and is used to record or specify a position in a stream. This class is for use only with streams that support seeking.

Most streampos values are similar to C fpos_t values; that is, they record file position values in a way private to the implementation. Because these values are probably not useful for user-defined stream classes, it is also possible to create integral-valued streampos objects. Note that integral-valued streampos objects probably are not useful for positioning fstream or stdiostream objects.

CONSTRUCTORS

This class defines two constructors:

streampos::streampos()

creates a streampos object with an unknown value.

streampos::streampos(long n)

creates a streampos object from the value n . All kinds of stream buffers support the following values of n :

streampos(0)

indicates the beginning of the stream.

streampos(EOF)

indicates the end of the stream.

strstream objects created from other values of n are not useful for positioning fstream or stdiostream objects.

MEMBER FUNCTIONS

This class defines two member functions:

streampos::operator long()

reduces the value of the streampos to a long integer. The value of long(streampos(long_val)) is defined to be equal to long_val . The result of converting a streampos not constructed from a long is undefined.

fpos_t* streampos::fpos()

returns a pointer to an fpos_t contained in the streampos . This fpos_t contains a valid value only if this streampos was returned from a call to seekoff() or seekpos() on a filebuf or stdiobuf object.

class strstream, istrstream, and ostrstream

Provide Formatted String I/O

SYNOPSIS

#include <strstream.h>

class istrstream : public strstreambuf,
                   public istream
{
public:
   istrstream(char *str);
   istrstream(char *str, int size);
   ~istrstream( );
   strstreambuf* rdbuf ( );
};

class ostrstream : public strstreambuf,
                   public ostream
{
public:
   ostrstream(char *str, int size,
              int mode = ios::out);
   ostrstream( );
   ~ostrstream( );

   char* str( );
   int pcount ( );
   strstreambuf* rdbuf( );
};

class strstream : public strstreambuf,
                  public iostream
{
public:
   ostrstream(char *str, int size,
              int mode = ios::out);
   ostrstream( );
   ~ostrstream( );

   char* str( );
   int pcount( );
   strstreambuf* rdbuf( );
};

class strstream : public strstreambuf,
                  public iostream
{
public:
   strstream(char *str, int size,
             int mode = ios::out);
   strstream( );
   ~strstream( );

   char* str( );
   int pcount( );
   strstreambuf* rdbuf( );
};

DESCRIPTION

class strstream and its associated classes class istrstream and class ostrstream are declared in the strstream.h header file. These classes support string (array) I/O. They do this by customizing the I/O operations defined in the base classes istream , ostream , and iostream .

PARENT CLASSES

class istrstream inherits characteristics from class istream . class ostrstream inherits characteristics from class ostream , and class strstream inherits characteristics from class iostream . All three of class istrstream , ostrstream , and strstream inherit characteristics from class ios . See the descriptions of these parent classes for the details on functions and operators that are inherited.

CONSTRUCTORS

class strstream , class istrstream , and class ostrstream each have two constructors. For a discussion of dynamic mode versus static mode streams, see class strstreambuf .

istrstream::istrstream(char *str)

creates a static mode istrstream such that extraction operations on the stream will fetch the characters of str , up to the terminating ' \0 '. str must be null-terminated. The ' \0 ' character is not fetched. Seeks are allowed within the array.

istrstream::istrstream(char *str,
int size)

creates a static mode istrstream such that extraction operations on the stream will fetch characters from the array starting at str and extending for size bytes. Seeks are allowed within the array.

ostrstream::ostrstream(char *str,
int size, int mode = ios::out)

creates a static mode ostrstream referencing an area of size bytes starting at the character pointed to by str . The get pointer is positioned at the beginning of the array. The put pointer is also positioned at the beginning of the array unless either the ios::ate or ios::app bit is set in mode ; if either of these bits is set, the put pointer is positioned at the space that contains the first null character. Seeks are allowed anywhere within the array.

ostrstream::ostrstream()

creates a dynamic mode ostrstream . This involves dynamically allocating space to hold stored characters. Seeks are not allowed.

strstream::strstream(char *str,
int size, int mode = ios::out)

creates a static mode strstream referencing an area of size bytes starting at the character pointed to by str . The get pointer is positioned at the beginning of the array. The put pointer is also positioned at the beginning of the array unless either the ios::ate or ios::app bit is set in mode ; if either of these bits is set, the put pointer is positioned at the space that contains the first null character.

strstream::strstream()

creates a dynamic mode strstream . This involves allocating space to hold stored characters. Seeks are not allowed. The get pointer is positioned at the beginning of the array.

DESTRUCTORS

class istrstream , class ostrstream , and class strstream each have one destructor:

istrstream::~istrstream() ostrstream::~ostrstream() strstream::~strstream()

closes the stream. For dynamic stream objects, closing means delete the array, unless it has been frozen. For static stream objects, closing is meaningless.

MEMBER FUNCTIONS

The following functions are members of class istrstream , class ostrstream , and class strstream .

char* ostrstream::str()
char* strstream::str()

call str() on the associated streambuf . These functions return whatever the streambuf::str() call returned.

int ostrstream::pcount()
int strstream::pcount()

return the number of stored bytes.

strstreambuf* istrstream::rdbuf() strstreambuf* ostrstream::rdbuf() strstreambuf* strstream::rdbuf()

return a pointer to the strstreambuf associated with the stream.

EXAMPLE

This example creates a strstream , inserts a string and a number, then extracts them again, writing the contents of mystream to cout .

strstream mystream;
float mynum=3.2;
float num2;

   // Write mynum to mystream.
mystream << mynum << ends;

   // Extract the contents of mystream
   // and store them in num2.
mystream >> num2;

   // Get the string from mystream and
   // write it to cout.
cout << mystream.str();

SEE ALSO

class strstreambuf

Buffer Class Descriptions

This section provides the descriptions of the buffer classes, such as filebuf and strstreambuf .

Using these classes is an advanced programming technique and is not required for simple C++ programs that use I/O. As with the stream class descriptions, the protected interface to the buffer classes is not included in the class descriptions that follow, although it is implemented.

Each class (or occasionally, a set of related classes) is listed alphabetically. All class descriptions include the following information:

• a synopsis of the class
• a brief description of the purpose and structure of the class
• a discussion of parent classes
• a detailed description of the members of the class
• examples of using some of the members, if appropriate
• a SEE ALSO section that points you to related classes.

In addition, some class descriptions contain other sections, as appropriate for the class.

The following classes are described in this section:

class filebuf class stdiobuf class streambuf class strstreambuf class bsambuf class bsam_exit_list

The bsambuf class is a specialized version of class streambuf and was added with Release 6.00. It implements I/O via the record-oriented Basic Sequential Access Method (BSAM) interface of the SAS/C OS Low-Level I/O functions. In addition to providing all the functionality of the streambuf class, class bsambuf permits functions to be called as BSAM exits via objects of class bsam_exit_list .

The bsambuf class is defined in the header file <bsamstr.h> . This header file also defines a set of classes for performing formatted file I/O using a bsambuf object. These include:

• class bsamstream
• class ibsamstream
• class obsamstream .

These classes are specialized versions of class iostream , istream , and ostream , respectively.

For details about the streams library and the parent class of class bsambuf , refer to class streambuf in the "I/O Class Descriptions" section. For details about the OS Low-Level I/O functions, refer to SAS/C Library Reference, Third Edition, Volume 2. For more information about BSAM, refer to the IBM publication MVS/XA Data Administration Guide (GC26-4140).

Note: The classes defined in <bsamstr.h> can be used in a C++ program that uses the Systems Programming Environment (SPE) library.

Note: The term character in the following class and function descriptions refers to either a char , a signed char , or an unsigned char .

class bsambuf

Provide File I/O via BSAM

SYNOPSIS

class bsambuf : public streambuf
{
public:
   enum error_id { Enone,
                   Estorage,
                   Eabend,
                   Eopen,
                   Eclose,
                   Eget,
                   Eput,
                   Efind,
                   Estow,
                   Eflush,
                   Eseek,
                   Etell
                  };
   bsambuf();
   virtual ~bsambuf();
   int is_open();
   bsambuf *open(const char *filename, 
      int mode, const char *keywords = 0, 
      int willseek = 0,
      bsam_exit_list *user_exits = 0);
   bsambuf *attach(DCB_t *dcb, int mode, 
      int willseek = 0);
   int init_directory();
   int delete_member(const char *name);
   int rename_member(const char *old_name,
      const char *new_name);
   int stow(const char *name, 
      char action = 'R',
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0, 
      int R = 0, int TTRN = 0);
   int add_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int replace_member(const char *name,
      int user_data_length = 0,
      const void *user_data = 0,
      int alias = 0, int TT = 0,
      int R = 0, int TTRN = 0);
   int find(const char *name);
   bsambuf *close();
   char dcbrecfm();
   short dcblrecl();
   short dcbblksize();
   DCB_t *getdcb();
   int error_info(error_id& id);
   void clear_error_info();
   void set_user_data(void *user_data);
   void *get_user_data();
   const char *get_ddname();
   const char *get_member();
   virtual streambuf *setbuf(char *buffer, 
      int length);
   virtual streampos seekoff(streamoff 
      offset,ios::seek_dir dir, int mode);
   virtual streampos seekpos(streampos 
      pos, int mode);
   virtual int sync();
 };

DESCRIPTION

The <bsamstr.h> header file defines class bsambuf . The bsambuf class is a specialization of class streambuf that implements I/O via the record-oriented BSAM interface of the OS Low-Level I/O functions. bsambuf objects are intended for use in C++ programs that use the SPE version of the library, but they may also be useful in other contexts.

In addition to the expected streambuf functionality, class bsambuf permits functions to be called as BSAM exits via objects of class bsam_exit_list .

For more information about the OS Low-Level I/O functions, refer to SAS/C Library Reference, Third Edition, Volume 2, Release 6.00. For more information about BSAM, refer to the IBM publication MVS/XA Data Administration Guide (GC26-4140).

RESTRICTIONS

• A file having the DCB characteristic LRECL=X cannot be connected to a bsambuf .
• "Short records," that is, records in a fixed-length record data set that are shorter than the record length, are padded on the right. If the file was opened in ios::binary mode, the record is padded with null (all bits 0) characters, otherwise the record is padded with blank characters. Padding characters are not removed from records on input.
• The number of pushback characters is limited to the size of the buffer, which is either the logical record length of the file or the size specified by setbuf , whichever is smaller. In no case can characters be pushed back beyond a record boundary.

PARENT CLASSES

class bsambuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

CONSTRUCTORS

class bsambuf defines one constructor:

bsambuf::bsambuf()

constructs a bsambuf object for an unopened file.

DESTRUCTORS

Here is the class bsambuf destructor:

virtual bsambuf::~bsambuf()

closes the file, if opened.

TYPES

class bsambuf defines one type, enum error_id . This type enumerates the values that may be retrieved by the error_info function, described later in this section.

NONVIRTUAL MEMBER FUNCTIONS

The following nonvirtual functions are defined in class bsambuf . The virtual functions are described later in this section.

int bsambuf::is_open()

returns a value other than 0 if the bsambuf is connected to an open file; returns 0 otherwise.

bsambuf *bsambuf::open
(const char *filename, int mode,
const char *keywords = 0,
int willseek = 0,
bsam_exit_list *user_exits = 0)

opens a file named filename and connects the bsambuf to it. If the open is successful, open returns a pointer to the bsambuf . If an error occurs during the open, open returns 0. filename is a DDname optionally followed by a parenthesized member name. filename may be in upper- or lowercase. For example, ' sysin ' is a valid filename, as is ' obj(subrtn) '. mode is a combination of one or more enum open_mode flags. One or more of ios::in, ios::out , or ios::app must be set. keywords is a string of 0 or more DCB macro keywords. The supported keywords are DSORG, RECFM, LRECL, BLKSIZE, OPTCD, NCP, and BUFNO. The keywords and their values can be in either upper- or lowercase. If several keywords are specified, they can be separated by blanks or commas. For example, the keyword string ' recfm=fb,blksize=6400,lrecl=80 ' corresponds to the DCB specification DCB=(RECFM=FB,BLKSIZE=6400,LRECL=80). By default, no keywords are used.

DCB attributes may be specified via the keywords string or by the DD statement or TSO ALLOCATE for the DDname. If any attributes are unspecified for a new file, the following default values are used:

• If the record format is not specified, it defaults to variable-length, blocked records (RECFM=VB).
• If the record length is not specified, the default is 259 for a variable-length file or 80 for a fixed-length file.
• If the block size (footnote 1) is not specified, the default is shown in the following table:

Format	Default Blocksize
RECFM=F	either the logical record length or the largest multiple of the logical record length less than 6144, whichever is larger
RECFM=V	either the logical record length + 4 or 6144, whichever is larger
RECFM=U	255

If the value of willseek is 0, seeking is disabled for this file. Any attempt to use either the seekoff and seekpos function will result in an error. Specify a value other than 0 for this parameter if you intend to use either seekoff or seekpos on this file. The default value is 0. user_exits is a pointer to a bsam_exit_list object describing a number of functions to be called as BSAM exit routines. See class bsam_exit_list for information about this parameter. By default, no user exits are enabled.

Restrictions

• The ios::app mode flag is treated as ios::ate .
• The ios::nocreate and ios::noreplace mode flags are ignored.

bsambuf *bsambuf::attach(DCB_t *dcb,
int mode, int willseek = 0)

associates a DCB that has already been created by either the osdcb or osbdcb function to a bsambuf and opens the file. If the open is successful, attach returns a pointer to the bsambuf . If an error occurs during the open, attach returns 0. mode and willseek have the same meaning as they have in the open function.

Restrictions

• The DCB cannot already be open.
• The bsambuf implementation reserves the DCBUSER field for its own use.
• The ios::app mode flag is treated as ios::ate .
• The ios::nocreate and ios::noreplace mode flags are ignored.

int bsambuf::init_directory()

invokes the "initialize directory" function of the STOW macro on the file (which must be a PDS) connected to the bsambuf . The value returned is 0 if the function succeeds or is a value other than 0 otherwise.

int bsambuf::delete_member
(const char *name)

deletes the PDS member identified by name from the file connected to the bsambuf . name may be specified in either upper- or lowercase. If name is shorter than eight characters it will be padded on the right with blanks. The value returned is 0 if the member is successfully deleted or is a value other than 0 otherwise.

int bsambuf::rename_member (const char *old_name, const char *new_name)

renames the PDS member identified by old_name to new_name . old_name and new_name may be specified in either upper- or lowercase. If either name is shorter than eight characters it will be padded on the right with blanks. The value returned is 0 if the member is successfully renamed or is a value other than 0 otherwise.

int bsambuf::stow(const char *name,
char action = 'R',
int user_data_length = 0,
const void *user_data = 0,
int alias = 0, int TT = 0,
int R = 0, int TTRN = 0)

adds or replaces a member or alias in the file connected to the bsambuf . The file must be a PDS. name is the name of the member or alias. name may be specified in either upper- or lowercase. If name is shorter than eight characters, it will be padded on the right with blanks. action may be either 'R', indicating that name replaces an existing member or alias in the PDS, or 'A', which indicates that name is to be added to the PDS. The default value is 'R'. user_data_length is the length, in bytes, of the user data to be associated with name in the PDS directory. This value must be nonnegative and no greater than 62. user_data is a pointer to the user data. The default value of both user_data_length and user_data is 0.

If alias is a value other than 0, then name is treated as an alias to be added or replaced. The default value of alias is 0. TT and R are the relative track and record number, respectively, of name . These values are ignored when alias is 0. By default both are 0. (footnote 2) TTRN is the number of TTRN fields in user_data . This must be a nonnegative number no greater than 3. By default it is 0. stow returns a value other than 0 if any of the arguments are out of bounds. If stow invokes the STOW macro, with one exception, stow( ) returns the return code from the STOW macro. (This code can also be retrieved via the error_info function.) In general, the STOW macro returns 0 if the requested action succeeded, or a value other than 0 otherwise. The exception occurs when action is 'R' and the STOW macro returns 8. This return code from the STOW macro indicates that the member or alias did not previously exist and so was added. In this case, stow returns 0.

int bsambuf::add_member(const char *name,
int user_data_length = 0,
const void *user_data = 0,
int alias = 0, int TT = 0,
int R = 0, int TTRN = 0)

is equivalent to the stow function when action is 'A'. The arguments and return value are identical to stow .

int bsambuf::replace_member
(const char *name,
int user_data_length = 0,
const void *user_data = 0,
int alias = 0, int TT = 0,
int R = 0, int TTRN = 0)

is equivalent to the stow function when action is 'R'. The arguments and return value are identical to stow .

int bsambuf::find(const char *name)

positions the file, which must be a PDS, to the start of the member identified by name . name may be specified in either upper- or lowercase. If name is shorter than eight characters it will be padded on the right with blanks. find returns 0 if the file is successfully positioned, or a value other than 0 otherwise.

bsambuf *bsambuf::close()

causes any outstanding output to be flushed, then closes the file and disconnects the bsambuf from it (even if errors occur). The bsambuf 's I/O state is cleared. If the close is successful, close returns a pointer to the bsambuf . If an error occurs, close returns 0.

char bsambuf::dcbrecfm()

returns the value of the DCBRECFM field in the DCB. The bits in this field describe the record format of the file connected to the bsambuf . The <osio.h> header file contains preprocessor symbol definitions for the bits that may be set in this field. The most commonly used flags are shown in the following table:

Symbol	Format
DCBRECF	fixed
DCBRECV	variable
DCBRECU	undefined (see Note)
DCBRECBR	blocked

Note: DCBRECU is equivalent to ORing DCBRECF with DCBRECV. When examining the value returned by dcbrecfm , you must always check for DCBRECU before testing the DCBRECF or DCBRECV flags.

short bsambuf::dcblrecl()
short bsambuf::dcbblksize()

return the logical record length (LRECL) and block size (BLKSIZE) of the file connected to the bsambuf .

DCB_t *bsambuf::getdcb()

returns a pointer to the DCB associated with the file connected to the bsambuf .

int bsambuf::error_info(error_id& id)

returns the return code from the first failed low-level routine. If a function receives a value other than 0 as a return code from a low-level routine, it saves the return code and a value of type error_id indicating which routine failed. error_info retrieves this information, which may be used for a detailed error analysis.

The value returned in the id argument may have one of the values shown in the following table. Unless otherwise noted, the failing routine is a BSAM routine in the OS Low-Level I/O group of functions.

error_id	Routine
Enone	(no error)
Estorage	GETMAIN (table note 1) error_info
Eabend	BSAM (table note 2) bsambuf
Eopen	osopen
Eclose	osclose
Eget	osget (table note 3) osget
Eput	osput
Efind	osfind
Estow	osstow
Eflush	osflush
Eseek	osseek
Etell	ostell

TABLE NOTE 1:

This value is set when storage cannot be allocated for a buffer. The code returned by

is always 4.

TABLE NOTE 2:

This value is returned when an "ignorable" ABEND has occurred. An ignorable ABEND does not terminate the program but does prevent any further I/O from being performed on the file connected to the

. The value of the return code is that of the completion code field in the ABEND exit parameter list.

TABLE NOTE 3:

Although end-of-file causes

to return a value other than zero as a return code, this value is not stored as an error code.

If, after a low-level routine has failed and its error information stored, a subsequent low-level routine fails, the error information for that failure is not stored unless clear_error_info has been called.

void bsambuf::clear_error_info()

sets the stored error information to the initial state. In this state, the value of error_id is Enone and the return code is 0.

void bsambuf::set_user_data
(void *user_data)

stores the value in user_data for later retrieval by get_user_data . The value may be any value required by the program. It is ignored by the stream.

void *bsambuf::get_user_data()

retrieves the value stored by set_user_data .

void *bsambuf::get_ddname()

returns a pointer to the DDname part of the filename argument to open . The DDname is uppercased and terminated by a ' \0 '. If the DCB was associated to the bsambuf by the attach function, the pointer points to a 0-length string.

void *bsambuf::get_member()

returns a pointer to the member part of the filename argument to open . The member name is uppercased and terminated by a ' \0 '. If the DCB was associated to the bsambuf by the attach function, or the filename did not specify a member name, the pointer points to a 0-length string.

VIRTUAL MEMBER FUNCTIONS

virtual streambuf *bsambuf::setbuf
(char *buffer, int length)

offers the character array starting at buffer and containing length bytes as a buffer for use by the bsambuf . If buffer is 0 or length is less than or equal to 0, the bsambuf is unbuffered. (However, buffering by BSAM will still take place.) This function must be called before any I/O is requested for this bsambuf and can be called only once for the bsambuf . If the buffer will be used by the bsambuf , setbuf returns a pointer to the bsambuf .

If this function is called after I/O has been requested for the bsambuf , it does nothing and returns 0. If this function is called more than once, subsequent calls for the bsambuf do nothing except return 0. This function does not affect the I/O state of the bsambuf .

By default, the buffer size is equal to the number of data characters in a record. In most cases, use of the setbuf function will have little, if any, effect on I/O performance. However, changing the bsambuf to be unbuffered will severely degrade the performance. Also note that the underlying BSAM routines will always buffer the data, whether the bsambuf is unbuffered or buffered.

virtual streampos bsambuf::seekoff
(streamoff offset, ios::seek_dir dir, int mode)

sets the get and put pointers to a new position, as indicated by offset and dir . For a bsambuf , seekoff will only accept 0 as the value of offset . The only acceptable values for dir are ios::beg and ios::cur . (Refer to the description of streambuf::seekoff for an explanation of these two values.) If dir is ios::beg , the file is positioned to the beginning. If dir is ios::cur , the position of the file is not changed. The new location of the file is returned in the streampos .

For bsambuf objects, the get and put pointers are the same, so the mode argument is ignored. seekoff returns (streampos) EOF if offset is a value other than 0, if dir is neither ios::beg or ios::cur , or if the file position cannot be moved. seekoff will also always return (streampos) EOF if willseek was 0 when the file was connected to the bsambuf by either open or attach .

virtual streampos bsambuf::seekpos
(streampos pos, int mode)

sets the get and/or put pointers to a new position, as indicated by streampos . This function returns the new position, or seekpos(EOF) if an error occurs. For bsambuf objects, the get and put pointers are the same, so the mode argument is ignored.

virtual int sync()

tries to force the state of the get and put pointers of the bsambuf to be synchronized with the state of the file it is associated with. If some characters have been buffered for output they will be written to the file. (footnote 3) Characters that have been buffered for input will be discarded. Note that synchronization is not possible unless the file is positioned at a record boundary.

This function returns 0 if synchronization succeeds, otherwise it returns EOF.

SEE ALSO

class bsam_exit_list, class bsamstream, class ibsamstream, class obsamstream

class bsam_exit_list

Define BSAM Exit Routines

SYNOPSIS

#include <bsamstr.h>

class bsam_exit_list {
   bsam_exit_list();
   bsam_exit_list(exit_t *list);
   int use(_e_exit code, _e_exit_fp exit);
   int use(_e_exit code, void *exit);
   int remove(_e_exit code,_e_exit_fp exit);
   int remove(_e_exit code, void *exit);
   };

DESCRIPTION

The <bsamstr.h> header file defines class bsam_exit_list . A pointer to a bsam_exit_list object can be passed to the bsambuf::open , bsamstream::open , ibsamstream::open , or obsamstream:open function to define one or more functions that are to be used as DCB exit routines.

RESTRICTIONS

• Functions that serve as DCB exit routines cannot be member functions.
• Only one function can be called for each type of DCB exit.
• No more than 18 exits can be specified in each bsam_exit_list object. OS Low-Level I/O defines only 18 distinct exits.

CONSTRUCTORS

class bsam_exit_list defines two constructors:

bsam_exit_list::bsam_exit_list()

constructs an object that defines no exits.

bsam_exit_list::bsam_exit_list
(exit_t list[])

constructs an object that defines the exits specified by list . list is an array of type exit_t . This type is defined as shown here:

typedef struct {
         unsigned exit_code;
         union {
           _e_exit_fp exit_addr;
           void *area_addr;
          };
     } exit_t;

exit_code may be any one of the values defined for the enumeration type _e_exit , which is also defined as shown here:

enum _e_exit {INACTIVE = 0, INHDR = 1,
    OUTHDR = 2, INTLR = 3, OUTTLR = 4,
    OPEN = 5, EOV = 6, JFCB = 7,
    USER_TOTAL = 10, BLK_COUNT = 11,
    DEFER_INTLR = 12,
    DEFER_NONSTD_INTLR = 13, FCB = 16,
    ABEND = 17, JFCBE = 21,
    TAPE_MOUNT = 23, SECURITY = 24,
    LAST = 128, SYNAD = 256};

The last entry in the list must set area_addr to 0 and have an exit_code value of LAST or, if either exit_addr or area_addr is a value other than 0, you must OR the exit_code value with LAST.

Here is an example using this constructor:

static int open_exit(void *r1, void *r0)
   { 
   // DCB open exit processing...
   return 0;
   }
static int abend_exit(void *r1, void *r0)
   { 
   // DCB abend exit processing... 
   return 0; 
   }
int main()
 {    
 exit_t exit_array[] = {{OPEN, open_exit},
                      {ABEND, abend_exit},
                      {LAST, 0}
                       } ;    
   // Construct "list" with
   // two DCB exits.
     bsam_exit_list list(exit_array);

   // Open DDname "OUT"     
   // defining two DCB exits.     
     obsamstream o("out", ios::out, 0, 0,
                   &list);

   /* remainder of program */
     . 
     . 
     .     

DESTRUCTORS

Here is the class bsam_exit_list destructor:

virtual bsam_exit_list::~bsam_exit_list()

NONVIRTUAL MEMBER FUNCTIONS

The following nonvirtual functions are defined in class bsam_exit_list . This class defines no virtual functions.

Note: BSAM exits may be either functions or data areas. Therefore, class bsam_exit_list defines functions for both types.

int use(_e_exit code, _e_exit_fp exit)

adds a pointer to a function to be used as a DCB exit to the bsam_exit_list . The pointer must have type _e_exit_fp , which is defined as:

typedef _ _remote int (*_e_exit_fp)
       (void *, void *)

The exit must be a static member function or a nonmember function. The BSAM exit type is specified by code . If the exit is added, use returns 0. Otherwise it returns a value other than 0.

On entry to a BSAM exit, the first argument is the value of general register 1 as established by BSAM. Likewise, the second argument is the value of general register 0.

ABEND exit considerations

A default DCB ABEND exit is always defined for a bsambuf . If you define an DCB ABEND exit for the bsambuf , your exit will be run first, followed by the default exit. Your exit must set the option mask byte in the ABEND exit parameter list before returning. If the option mask byte is set to 4, indicating that the ABEND should be "ignored," the default exit causes the DCB to be closed and freed.

For your convenience, the <bsamstr.h> header file contains a partial definition of the parameter list BSAM creates for the DCB ABEND exit. On entry to the exit function, general register 1 (the first argument) contains a pointer to this parameter list:

struct Abend_exit_parms {
        char completion_code :12;
        char                 :4;
        char return_code;
        union {
           struct {
              char         :4;
              char recover :1;
              char ignore  :1;
              char delay   :1;
              char         :1;
              } can;
           char option_mask;
           };
        DCB_t *dcb;
       };
     // Set "option_mask" to this value
     // to ignore the ABEND.
     const int IGNORE_ABEND = 4;

int remove(_e_exit code, _e_exit_fp exit)

removes an exit function from the bsam_exit_list . If an exit having the matching exit code and function pointer is not in the bsam_exit_list , remove returns a value other than 0. Otherwise, remove removes the exit and returns 0.

int use(_e_exit code, void *exit)

adds a data pointer to be used as a DCB exit to the bsam_exit_list . The BSAM exit type is specified by code .

If the exit is added, use returns 0. Otherwise it returns a value other than 0.

int remove(_e_exit code, void *exit)

removes a data exit from the bsam_exit_list . If an exit having the matching exit code and address is not in the bsam_exit_list , remove returns a value other than 0. Otherwise, remove removes the exit and returns 0.

SEE ALSO

class bsambuf, class bsamstream, class ibsamstream, class obsamstream

class filebuf

Provide File I/O

SYNOPSIS

#include <fstream.h>
class filebuf : public streambuf
{
public:
   filebuf();
   virtual ~filebuf();
   int is_open();
   filebuf* open(const char *name,
                 int mode,
                 const char *amparms = "",
                 const char *am = "");
   filebuf* close();
   virtual streampos seekoff(streamoff
         offset, seek_dir place,
         int mode = ios::in|ios::out);
   virtual streampos seekpos(streampos pos,
         int mode = ios::in|ios::out);
   virtual streambuf* setbuf(char *p,
                             size_t len);
   virtual int sync();
};

DESCRIPTION

The fstream.h header file defines class filebuf . filebuf objects represent the lowest level of file I/O that is standard C++. They provide a specialized form of streambufs that uses a file as the source or destination (sink) for characters. Input corresponds to file reads and output corresponds to file writes. For filebuf objects, the get and put pointers are tied together. That is, if you move one, you move the other. If the file has a format that allows seeks, a filebuf allows seeks. filebuf I/O guarantees at least four characters of putback. You do not need to perform any special action between reads and writes (in contrast to standard C I/O, where such seeks are required).

When a filebuf is connected to a file, the filebuf is said to be open. There is no default open mode, so you must always specify the open mode when you create a filebuf .

PARENT CLASSES

class filebuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

CONSTRUCTORS

class filebuf defines one constructor:

filebuf::filebuf()

creates an unopened file.

DESTRUCTORS

Here is the class filebuf destructor:

virtual filebuf::~filebuf()

closes the file, if opened.

NONVIRTUAL MEMBER FUNCTIONS

The following nonvirtual functions are defined in class filebuf . The virtual functions are described later in this section.

int filebuf::is_open()

returns a nonzero value if the filebuf is connected to an open file; returns 0 otherwise.

filebuf* filebuf::open(const char *name,
int mode, const char *amparms = "",
const char *am = "")

opens a file named name and connects the filebuf to it. If the open is successful, open() returns a pointer to the filebuf . If an error occurs during the open (for example, if the file is already open), open() returns 0. See enum open_mode for a description of the mode argument.

An explanation of filename specification and the arguments amparms and am can be found in the SAS/C Library Reference, Volume 1. (Note that the order of the amparms and am arguments in this function is the opposite of the order in which they appear in calls to the C afopen function.) You may also want to refer to the SAS/C Compiler and Library User's Guide.

filebuf* filebuf::close()

causes any outstanding output to be flushed, then closes the file and disconnects the filebuf from it (even if errors occur). Also, the filebuf 's I/O state is cleared. If the close is successful, close() returns a pointer to the filebuf . If an error occurs during the close, close() returns 0.

VIRTUAL MEMBER FUNCTIONS

The following functions override their base class definitions (in class streambuf ).

virtual streampos filebuf::seekoff
(streamoff offset, seek_dir place,
int mode = ios::in|ios::out)

sets the get and put pointers to a new position, as indicated by place and offset . (Descriptions of offset and place are contained in the streambuf::seekoff() description.) This function returns the new position, or it returns streampos(EOF) if an error occurs (for example, the file may not support seeking, or you may have requested a seek to a position preceding the beginning of the file). The position of the file after an error is undefined. Some files support seeking in full, and some impose lesser or greater restrictions on seeking. seekoff() corresponds to the C fseek function, and seekpos() corresponds to the C fsetpos function. Rules for these similar C functions are given in the SAS/C Library Reference, Volume 1, Third Edition, Release 6.00.

For filebuf objects, the get and put pointers are the same (moving either one moves the other). Because of this, you do not have to use the last argument, mode .

virtual streampos filebuf::seekpos
(streampos pos,
int mode = ios::in|ios::out)

sets the get and/or put pointers to a new position, as indicated by streampos . This function returns the new position, or it returns seekpos(EOF) if an error occurs. For filebuf objects, the get and put pointers are the same (moving either one moves the other). Because of this, you do not have to use the last argument, mode .

virtual streambuf* filebuf::setbuf
(char *p, size_t len)

offers the character array starting at p and containing len bytes as a buffer for use by the filebuf . If p is null or len is less than or equal to 0, the filebuf is unbuffered. (However, buffering by the SAS/C Library and the operating system may still take place.) This function must be called before any I/O is requested for this filebuf and can be called only once for the filebuf . Under normal conditions, setbuf() returns a pointer to the filebuf .

If this function is called after I/O has been requested for the filebuf , this function does nothing and returns NULL . If this function is called more than once, subsequent calls for the filebuf do nothing except return NULL . This function does not affect the I/O state of the filebuf .

virtual int filebuf::sync()

tries to force the state of the get or put pointer of the filebuf to be synchronized with the state of the file it is associated with. This attempt at synchronization may result in the following:

• characters being written to the file, if some have been buffered for output. Note that all characters may not be written immediately due to additional buffering performed by the operating system.
• an attempt to seek the file, if characters have been read and buffered for input.

This function usually returns 0; if synchronization is not possible, it returns EOF.

IMPLEMENTATION

Usually, filebuf objects directly access the native I/O facilities of the system on which they are implemented. For this release of the SAS/C C++ Development System, filebuf objects are implemented in terms of C FILE* s. This may be changed in later versions of this library, and no assumptions should be made of this particular implementation.

SEE ALSO

class fstream, class ifstream,
class ofstream

class stdiobuf

Provide I/O in a Mixed C and C++ Environment

SYNOPSIS

#include <stdiostream.h>

class stdiobuf : public streambuf
{
public:
  stdiobuf(FILE *file);

  virtual ~stdiobuf( );

  int is_open( );

  FILE* stdiofile( );

  streampos seekoff(streamoff offset,
                    seek_dir place,
                    int mode =
                    ios::in|ios::out);
  streampos seekpos(streampos pos,
                    int mode =
                    ios::in|ios::out);
  virtual int sync();
};

DESCRIPTION

The stdiostream.h header file declares class stdiobuf . stdiobufs are intended to be an interface to ANSI C style FILE *s on those systems that provide FILE *s. Calls to stdiobuf member functions are mapped directly to calls to ANSI C stdio functions.

Because stdiobuf objects provide no buffering other than that provided by the C stdio functions, any changes to file attributes or contents made via a stdiobuf are reflected immediately in the stdio data structures. This includes file positioning using seekoff() or seekpos() . For stdiobuf objects, the get and put pointers are tied together. That is, if you move one, you move the other.

Unless you are mixing streambuf and stdio access to the same file, you should use class filebuf instead of class stdiobuf . Use of filebuf objects may improve performance.

PARENT CLASSES

class stdiobuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

CONSTRUCTORS

class stdiobuf defines one constructor:

stdiobuf::stdiobuf(FILE *file)

creates a stdiobuf object associated with an open FILE *.

DESTRUCTORS

Here is the class stdiobuf destructor:

virtual stdiobuf::~stdiobuf()

closes the associated FILE *, if opened.

NONVIRTUAL MEMBER FUNCTIONS

The following descriptions detail the nonvirtual member functions for class stdiobuf . The redefined virtual functions are described later in this section.

int stdiobuf::is_open()

returns a nonzero value if the stdiobuf is connected to an open file; returns 0 otherwise.

FILE* stdiofile()

returns the associated FILE *.

VIRTUAL MEMBER FUNCTIONS

The following functions override their base class definitions (in class streambuf ).

streampos stdiobuf::seekoff
(streamoff offset, seek_dir place,
int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . place can be one of the following:

ios::beg

indicates the start of file.

ios::cur

indicates the current get and put position.

ios::end

indicates the end of file.

offset is a positive or negative integer position relative to place. mode can be one of the following:

ios::in

moves the get pointer.

ios::out

moves the put pointer.

ios::in|ios::out

moves both pointers.

Whether seekoff() and seekpos() work for an stdiobuf depends on the characteristics of the associated FILE* . See the SAS/C Library Reference, Volume 1, Third Edition, Release 6.00 for more information on FILE* characteristics.

streampos stdiobuf::seekpos
(streampos pos,
int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . pos must be a value returned by a previous call to seekoff() . mode can be one of the following:

ios::in

moves the get pointer.

ios::out

moves the put pointer.

ios::in|ios::out

moves both pointers.

Some stream buffers do not support seeking. For those stream buffers, seekpos() returns streampos(EOF) to indicate an error occurred. See the documentation for particular stream buffer classes (such as filebuf ) for more information on what kinds of seeking are allowed.

virtual int stdiobuf::sync()

tries to force the state of the get or put pointer of the stdiobuf to be synchronized with the state of the associated file. This attempt at synchronization may result in the following:

• buffered for output. Note that all characters may not be written immediately due to additional buffering performed by the operating system.
• an attempt to seek the file, if characters have been read and buffered for input.

This function usually returns 0; if synchronization is not possible it returns EOF.

SEE ALSO

class stdiostream

class streambuf

Provide Base Class for All Stream Buffers

SYNOPSIS

#include <iostream.h>

class streambuf
{
public:
   int in_avail();
   int out_waiting();

   int sbumpc();
   int sgetc();
   int sgetn(char *s, int n);
   int snextc();
   void stossc();

   int sputbackc(char c);
   int sputc(int c);
   int sputn(const char *s, int n);

   virtual int sync();
   virtual streampos seekoff(streamoff
            offset, seek_dir place,
            int mode = ios::in|ios::out);
   virtual streampos seekpos(streampos pos,
            int mode = ios::in|ios::out);
   virtual streambuf* setbuf(char *p,
                             int len);
};

DESCRIPTION

class streambuf is declared in the iostream.h header file and is the base class for all stream buffers. Stream buffers manage the flow of characters between the program and the ultimate sources or consumers of characters, such as external files. The streambuf class defines behavior common to all stream buffers. More specialized classes can be derived from class streambuf to implement appropriate buffering strategies for particular stream types. For instance, filebufs implement buffering suitable for file input or output and strstreambufs implement buffering suitable for transfer of data from strings in memory. A streambuf is almost never used directly (classes derived from it are used instead) but more often acts as an interface specification for derived classes.

The functions defined by the streambuf interface are divided into two groups: nonvirtual functions and virtual functions. These sets of functions are described separately.

CONSTRUCTORS AND DESTRUCTORS

class streambuf defines two constructors and one destructor. All these functions are protected. This ensures that class streambuf is used only as a base class for derived classes.

NONVIRTUAL MEMBER FUNCTIONS

The following list describes the nonvirtual streambuf interface.

int streambuf::in_avail()

returns the number of characters that have been buffered for input, that is, the number of characters that have been read from the ultimate source of the input but have not been extracted from the streambuf . Generally, this information is useful only for classes derived from class streambuf .

int streambuf::out_waiting()

returns the number of characters that have been buffered for output, that is, the number of characters that have been inserted into the streambuf but have not been delivered to its ultimate destination. Generally, this information is useful only for classes derived from class streambuf .

int streambuf::sbumpc()

advances the get pointer one character and returns the character preceding the advanced pointer. If the get pointer is at the end of the stream, the get pointer is not moved and EOF is returned.

int streambuf::sgetc()

returns the character following the get pointer. This function does not move the get pointer. If the get pointer is at the end of the stream, this function returns EOF.

int streambuf::sgetn(char *s, int n)

extracts the next n characters from the stream into s and positions the get pointer after the last extracted character. If there are less than n characters between the get pointer and the end of the stream, those characters are extracted into s and the get pointer is moved to the end of the stream. This function returns the number of characters extracted into s .

int streambuf::snextc()

advances the get pointer one character and returns the character after the advanced pointer. If the get pointer is at the end of the stream, the get pointer is not moved and EOF is returned.

void streambuf::stossc()

advances the get pointer one character.

int streambuf::sputbackc(char c)

backs the get pointer up one character, returning c . c must be the character that the get pointer is moved over; if it is not, the effects of this function are undefined. For example, if the get pointer is at the start of the stream and you call this function, the effect is undefined.

Also, each class derived from streambuf may impose a limit on the number of characters that can be moved over by sputbackc() . If you exceed this limit, this function returns EOF. For some classes, you cannot back up over any characters.

int streambuf::sputc(int c)

stores c in the position following the put pointer, replacing any pre-existing character, and then advances the put pointer one position. This function returns c if the operation is successful, or EOF if an error occurs.

int streambuf::sputn(const char *s, int n)

stores after the put pointer the first n characters addressed by s , replacing any pre-existing characters in those positions, and then advances the put pointer past the last character stored. This function returns the number of characters successfully stored.

VIRTUAL MEMBER FUNCTIONS

The following virtual functions are members of class streambuf . These functions can be redefined in derived classes (both those supplied by the library and those you define yourself) to customize the behavior of streambuf objects.

virtual int streambuf::sync()

tries to force the state of the get or put pointer of the streambuf to be synchronized with the state of the sink or source it is associated with. This function returns 0 if successful, or EOF if an error occurs.

virtual streampos streambuf::seekoff
(streamoff offset, seek_dir place,
int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . place can be one of the following:

ios::beg

indicates the start of file.

ios::cur

indicates the current get or put position.

ios::end

indicates the end of file.

offset is a positive or negative integer position relative to place. mode can be one of the following:

ios::in

moves the get pointer.

ios::out

moves the put pointer.

ios::in|ios::out

moves both pointers. This is the default value.

Some kinds of seeking are not supported for certain stream buffers. If a particular stream buffer does not support the seeking specified, this function returns streampos(EOF) to indicate an error occurred. See the documentation for particular stream buffer classes (such as filebuf ) for more information on what kinds of seeking are allowed.

virtual streampos streambuf::seekpos
(streampos pos,
int mode = ios::in|ios::out)

moves the get and/or put pointers of the streambuf . pos must be a value returned by a previous call to seekoff() . mode can be one of the following:

ios::in

moves the get pointer.

ios::out

moves the put pointer.

ios::in|ios::out

moves both pointers. This is the default value.

Some stream buffers do not support seeking. For those stream buffers, seekpos() returns streampos(EOF) to indicate an error occurred. See the documentation for particular stream buffer classes (such as filebuf ) for more information on what kinds of seeking are allowed.

virtual streambuf* streambuf::setbuf
(char *p, int len)

allocates a buffer area to be used for buffering within the streambuf .

class strstreambuf

Provide String I/O

SYNOPSIS

#include <strstream.h>

class strstreambuf : public streambuf
{
public:
   strstreambuf( );
   strstreambuf(int len);
   strstreambuf(void* (*a) (long),
                void (*f) (void*));
   strstreambuf(char *b, int size,
                char *pstart = 0);

   ~strstreambuf( );

   void freeze(int n = 1);
   char* str( );

   virtual streambuf* setbuf(char *p,
                             int len);
   inc sync( );
   virtual streampos seekoff
           (streamoff offset,
            seek_dir place,
            int mode = ios::in|ios::out);

   virtual streampos seekpos 
            (streampos pos,
            int mode = ios::in|ios::out);
};

DESCRIPTION

The header file strstream.h declares class strstreambuf , which specializes class streambuf to provide for I/O using arrays of char (strings).

For strstreambuf objects, the get and put pointers are separate. That is, if you move one of these pointers you do not necessarily move the other. strstreambuf objects are created in one of two different modes, dynamic mode or static (fixed) mode. Once a strstreambuf is created, it does not change modes. The following list explains the difference between fixed and dynamic mode:

dynamic mode

means the strstreambuf does not have a fixed size and grows as needed. When the array associated with a dynamic mode strstreambuf is filled, the strstreambuf automatically allocates a larger array, copies the old smaller array to the larger, and frees the smaller array. The functions used to handle allocating and freeing the arrays are determined by the constructor used to create the strstreambuf (see the description of constructors for class strstreambuf .

static mode

means the strstreambuf has a fixed size that does not change. If the array associated with a static mode strstreambuf is filled, further writes to the strstreambuf may corrupt memory. Be cautious when inserting into static mode strstreambuf s.

Note: Do not confuse static mode with the static storage class modifier.

class strstreambuf defines some member functions of its own and also redefines several virtual functions from the base class.

PARENT CLASSES

class strstreambuf inherits characteristics from class streambuf . See the description of this parent class for the details on functions and operators that are inherited.

CONSTRUCTORS

class strstreambuf defines four constructors:

strstreambuf::strstreambuf()

creates an empty strstreambuf object in dynamic mode.

strstreambuf::strstreambuf(int len)

creates an empty strstreambuf object in dynamic mode. The initial allocation uses at least len bytes.

strstreambuf::strstreambuf
(void*(*a)(long), void (*f)(void*))

creates an empty strstreambuf object in dynamic mode. a is the allocation function to be used to do the dynamic allocation and takes as its argument a long , which specifies the number of bytes to allocate. If a is NULL , the operator new is used instead of a . f is the deallocation function, which frees the space allocated by a . f takes as its argument a pointer to an array allocated by a . If f is NULL , the operator delete is used instead of f .

strstreambuf::strstreambuf(char *b,
int size, char *pstart = 0)

constructs a strstreambuf object in static mode; it does not grow dynamically. b specifies where to start the array and size specifies the size of the array, as explained in the following list.

• If size is positive, the array is size bytes long.
• If size is 0, the function assumes b points to the start of a null-terminated string. In this case, the string, not including the ' \0 ' character, is considered to be the strstreambuf .
• If size is negative, the strstreambuf is assumed to be indefinitely long.

The get pointer receives the value of b and the put pointer receives the value of pstart . If pstart is NULL , then storing characters in the strstreambuf is not allowed and causes the function to return an error.

DESTRUCTORS

Here is the class strstreambuf destructor:

strstreambuf::~strstreambuf()

closes the strstreambuf object. The destructor causes any memory allocated for the strstreambuf to be freed.

NONVIRTUAL MEMBER FUNCTIONS

class strstreambuf defines two nonvirtual member functions.

void strstreambuf::freeze(int n = 1)

controls the automatic deletion of the array. If n is nonzero, which is the default, the array is not deleted automatically. If n is 0, the array is unfrozen and is deleted automatically. The array is deleted whenever a dynamically created strstreambuf needs more space or when the destructor is called. This function only applies to dynamically created strstreambuf s; it has no effect on statically created strstreambuf s.

If you try to store characters in a frozen array, the effect is undefined.

char* strstreambuf::str()

returns a pointer to the first character in the current array and freezes the array. After str() has been called, the effect of storing characters in the array is undefined until the strstreambuf is unfrozen by calling freeze(0) .

VIRTUAL MEMBER FUNCTIONS

class strstreambuf redefines several virtual functions from its base class ( class streambuf ).

virtual strstreambuf::streambuf* setbuf
(char *p, int len)

tells the strstreambuf that the next time an array is dynamically allocated it should be at least len bytes long. p is ignored.

int strstreambuf::sync()

returns EOF.

virtual streampos strstreambuf::seekoff
(streamoff offset, seek_dir place,
int mode = ios::in|ios::out)

moves the get and/or put pointers of the strstreambuf . See the description of streambuf::seekoff for explanations of offset , place and mode .

If the strstreambuf is in dynamic mode, this function returns streampos(EOF) to indicate an error occurred.

If either the get or put pointer is moved to a position outside the strstreambuf , or if the put pointer is moved for a strstreambuf that does not allow output, then streampos(EOF) is returned and the pointers are not moved.

If place is ios::end , it refers to the end of the array.

virtual streampos strstreambuf::seekpos
(streampos pos,
int mode = *ios::in|ios::out)

moves the get and/or put pointers of the strstreambuf .

If the strstreambuf is in dynamic mode, this function returns streampos(EOF) to indicate an error occurred. pos must be a value returned by a previous call to seekoff() .

See the description of streambuf::seekpos() for an explanation of mode . If ios::out is specified for mode and output is not allowed for this strstreambuf , then streampos(EOF) is returned to indicate an error occurred and the put pointer is not moved.

SEE ALSO

class strstream

Manipulator Descriptions

This section describes contents of the iomanip.h header file, which provides predefined manipulators, as well as support functions and classes that enable you to create your own manipulators.

class IOMANIP

Provide Manipulators

SYNOPSIS

#include <IOMANIP.h>

/* Macros for creating class names */
#define SMANIP(T)  ...
#define SAPP(T)    ...
#define IMANIP(T)  ...
#define IAPP(T)    ...
#define OMANIP(T)  ...
#define OAPP(T)    ...
#define IOMANIP(T) ...
#define IOAPP(T)   ...

// Start of IOMANIPdeclare macro

#define IOMANIPdeclare(T)

class SMANIP(T)
{
   public:
   SMANIP(T)(ios&(*f)(ios&, T), T d);
   friend istream& operator >>(istream& i,
         SMANIP(T)& m);
   friend ostream& operator <<(ostream& o,
         SMANIP(T)& m);
};

class SAPP(T)
{
public:
   SAPP(T)(ios&(*f)(ios&, T));
   SMANIP(T)operator()(T d);
};

class IMANIP(T)
{
public:
   IMANIP(T)(ios&(*f)(ios&, T), T d);
   friend istream& operator >>(istream& i,
         IMANIP(T)& m);
};

class IAPP(T)
{
public:
   IAPP(T)(ios&(*f)(ios&, T));
   IMANIP(T)operator()(T d);
};
class OMANIP(T)
{
public:
   OMANIP(T)(ios&(*f)(ios&, T), T d);
   friend ostream& operator <<(ostream& o,
         OMANIP(T)& m);
};
class OAPP(T)
{
public:
   OAPP(T)(ios&(*f)(ios&, T));
   OMANIP(T)operator()(T d);
};

class IOMANIP(T)
{
public:
   IOMANIP(T)(ios&(*f)(ios&, T), T d);
   friend istream& operator >>(istream& i,
         IOMANIP(T)&m);
   friend ostream& operator <<(ostream& o,
         IOMANIP(T)&m);
};

class IOAPP(T)
{
public:
   IOAPP(T)(ios&(*f)(ios&, T));
   IOMANIP(T)operator()(T d);
};
// End of IOMANIPdeclare macro

IOMANIPdeclare(int);
IOMANIPdeclare(long);

SMANIP(int) setw(int width);
SMANIP(int) setbase(int base);
SMANIP(int) setfill(int fill_char);
SMANIP(int) setprecision(int precision);
SMANIP(long) setiosflags(long flags);
SMANIP(long) resetiosflags(long flags);

DESCRIPTION

The IOMANIP.h header file declares some predefined manipulators, as well as support functions and classes that enable you to create your own manipulators. A manipulator is a value that can be used to effect some change to a stream by inserting it into or extracting it from the stream. For example, the flush function is a manipulator of ostream objects:

cout << flush; // Causes cout to be flushed.

In fact, any function of one the following types is a manipulator:

ostream& (ostream&)

is a manipulator for ostream objects.

istream& (istream&)

is a manipulator for istream objects.

ios& (ios&)

is a manipulator for istream or ostream objects.

You can also create manipulators that have arguments. The IOMANIP.h header file defines two manipulator-creation classes for each type of stream ( ios , istream , ostream , and iostream ). One class has a name in the form xMANIP(T) , and the other class has a name in the form xAPP(T) , where T is an identifier that names a type (such as a typedef name for a class name) and x is a letter such as S.

For ios objects, these two classes are named SMANIP(T) and SAPP(T) .

PREDEFINED MANIPULATORS

The predefined manipulators defined by iomanip.h allow you to control various pieces of the format state of a stream. These manipulators are described in the following list.

SMANIP(int) setw(int w)

returns a manipulator (an SMANIP(int) ) that can be used to set the width() value of an ios object.

SMANIP(int) setbase(int base)

returns a manipulator that can be used to set the default numeric conversion base of an ios object. The argument must be one of the values 8, 10, or 16.

SMANIP(int) setfill(int f)

returns a manipulator that can be used to set the fill() value of an ios object.

SMANIP(int) setprecision(int p)

returns a manipulator that can be used to set the precision() value of an ios object.

SMANIP(long) setiosflags(long flags)

returns a manipulator that can be used to set the flags() value of an ios object.

SMANIP(long) resetiosflags(long flags)

returns a manipulator that can be used to reset the flags() value of an ios object.

EXAMPLES USING PREDEFINED MANIPULATORS

The following example transmits ********27,00048 :

cout << setw(10) << setfill('*')
     << 27 << ',' << setw(5)
     << setfill('0') << 48;

The following example transmits 32,5 :

cout << setprecision(2) << 32.1 << ','
     << setprecision(0) << 5.3;

The following example sets the skipws bit in cout 's format state:

cout << setiosflags(ios::skipws);

The following example clears the skipws bit in cout 's format state:

cout << resetiosflags(ios::skipws);

USER-DEFINED MANIPULATORS

As well as the predefined manipulators described in the previous section, the IOMANIP.h header file also provides the means for you to create your own manipulators. It does this by defining a macro, IOMANIPdeclare(T) , that when invoked with a typedef name for T declares the following classes:

SMANIP(T) and SAPP(T)

use with ios objects.

IMANIP(T) and IAPP(T)

use with istream objects.

OMANIP(T) and OAPP(T)

use with ostream objects.

IOMANIP(T) and IOAPP(T)

use with iostream objects.

class SMANIP(T) and SAPP(T) are explained in detail in this section; the other classes are very similar to SAPP(T) and only the differences between them and class SMANIP and SAPP(T) are noted.

If you are going to create new manipulators using the various xMANIP(T) and xAPP(T) classes, the classes must first be defined for a particular type name. This is done by putting the following definition in any module that uses the xMANIP(T) or xAPP(T) classes for a particular type name:

IOMANIPdeclare(type-name);

where type-name can be any valid type identifier. Because int and long are the most commonly used type names in manipulators, the IOMANIPdeclares for these type names are included in the IOMANIP.h header file, and your program should not declare them again. If you need to create manipulators using the xMANIP(T) and xAPP(T) classes for type names other than int or long , you must include a use of IOMANIPdeclare() in your module.

For example, before using xMANIP(T) and xAPP(T) classes to create manipulators that accept char arguments, the xMANIP(T) and xAPP(T) classes for the type name char must be declared as follows:

#include <IOMANIP.h>
IOMANIPdeclare(char);

If you need to create manipulators that accept arguments of more complicated types, like char* arguments, you must first declare a typedef for the type because IOMANIPdeclare requires a single-word type name. Here is an example:

#include <IOMANIP.h>
typedef char* STRING;
IOMANIPdeclare(STRING);

class SMANIP(T)

provides a constructor and two operators, as detailed next.

SMANIP(T)(ios&(*f)(ios&, T), T d)

constructs an SMANIP(T) and returns a single argument manipulator by collecting the function f and argument d into a single manipulator value. It is assumed that f is a function that changes ios in some way using the value of d .

friend istream& operator >> (istream& i,
SMANIP(T)& m)

friend ostream& operator << (ostream& o,
SMANIP(T)& m)

enable SMANIP(T) objects to be "inserted-into" istream objects and "extracted-from" ostream objects, respectively. They each use the values f and d from the SMANIP(T) value. They then call f(myios,d) where myios is the ios part of i or o , respectively. It is assumed that f is a function that changes ios in some way using the value of d .

It is often easier to create manipulators using the applicator classes, in this case SAPP(T) , than to use the xMANIP(T) classes. class SAPP(T) is described next.

class SAPP(T)

provides a constructor and an operator, as detailed next. SAPP(T) objects make it easier to use SMANIP(T) objects. The EXAMPLES section gives an example of using an SAPP(T) object. Here are the members of class SAPP(T) :

SAPP(T) (ios&(*f)(ios&, T))

initializes an SAPP(T) object to contain f .

SMANIP(T) operator() (T d)

creates and returns an SMANIP(T) object using the f from the SAPP(T) and the d argument.

Other manipulator classes

The rest of the classes defined by IOMANIPdeclare(T) are similar to class SAPP(T) , with the following differences:

• for IMANIP(T) and IAPP(T) , f has type

  istream&(*f)(istream&, T)

• for OMANIP(T) and OAPP(T) , f has type

  ostream&(*f)(ostream&, T)

• for IOMANIP(T) and IOAPP(T) , f has type

  iostream&(*f)(iostream&, T)

• IMANIP(T) does not contain operator <<
• OMANIP(T) does not contain operator >>

EXAMPLES OF USER-DEFINED MANIPULATORS

The following code creates a manipulator setwidth , which works like the library's setw .

ios& setw_func(ios& i, int w)
{
   i.width(w);
   return i;
}
SAPP(int) setwidth(setw_func);

FOOTNOTE 2: class bsambuf defines no function that can retrieve this information. Use the osnote function in the OS Low-Level I/O group of functions to get the TTRz value for the current position in the file.

FOOTNOTE 3:The sync function invokes the low-level osflush routine to flush all buffered characters to the operating system. Note, however, that all characters may not be written immediately, due to additional buffering performed by the operating system.

Chapter Contents

Previous

Next

Top of Page

Copyright © Tue Feb 10 12:11:23 EST 1998 by SAS Institute Inc., Cary, NC, USA. All rights reserved.