United States

Compaq C++

# Compaq C++
Class Library Reference Manual

Previous | Contents | Index

In classes derived from `streambuf` , this function is called to let derived classes examine the state of the put, get, and reserve areas, and to synchronize these areas with any external representation. Normally `sync()` should consume any characters stored into the put area and, if possible, give back to the source any characters in the get area that have not been fetched. When `sync()` returns, no unconsumed characters should remain and the get area should be empty. If some kind of failure occurs, `sync()` should return `EOF` .

### int unbuffered()

Returns the current buffering state flag, which is independent of the actual allocation of a reserve area. This function's primary purpose is to find out if a reserve area is being allocated automatically by `allocate()` .

### void unbuffered(int n)

Sets the value of the current buffering state flag. If n equals 0, then the `streambuf` object is buffered; otherwise it is unbuffered. This function's primary purpose is to control whether a reserve area is allocated automatically by `allocate()` .

### virtual int underflow()

In `streambuf` , this function should be treated as if its behavior is undefined; classes derived from `streambuf` must define it.

In classes derived from `streambuf` , it is called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, `underflow()` should return `EOF` and leave an empty get area.

## Example

    static const int bufsize = 1024;
    char buf[bufsize] ;
    int p, g ;
    do {
            in->sgetc() ; (1)
            g = in->in_avail() ;  (2)
            if (g > bufsize) g = bufsize ;  (3)
            g = in->sgetn(buf,g) ;
            p = out->sput(buf,g) ;
            out->sync() ;  (4)
            if (p!=g) error("output error");
            } while (g > 0)

> Provides a way to pass characters into the `in` and `out` arrays as soon as the characters become available (as when someone types them from a terminal) as follows:

> 1. Ensures at least one character is immediately available in the `in` array (unless the get pointer is at the end of the sequence).
> 2. Returns the number of characters immediately available.
> 3. Checks that chunks in which the characters become available are less than `bufsize` , and that they fit into the arrays.
> 4. Sends characters put into the `out` array to the ultimate consumer.

# strstream class

> Specializes the `iostream` class for storing in and fetching from arrays of bytes.

## Header File

> `#include <strstream.hxx>`

> Alternative Header

> `#include <strstream.h>`

## Declaration

>     class strstream: public iostream
>     {
>     public:
>                          strstream();
>                          strstream(char *, int, int);

>         strstreambuf     *rdbuf();
>         char             *str();
>     };

## Description

> This class specializes the `iostream` class for storing in and fetching from arrays of bytes. It handles all predefined data types, and provides an extensive set of options for performing input and output on these data types.

## Constructors and Destructors

> ### strstream()

> Constructs an `strstream` object and dynamically allocates space to hold stored characters.

> ### strstream(char *cp, int n, int mode)

> Constructs an `strstream` object. It stores characters into the array starting at cp and continuing for n bytes. If `ios::ate` or `ios::app` is set in mode, cp is presumed to be a null-terminated string and storing begins at the null character; otherwise, storing begins at cp. Seeks are permitted anywhere in the array.

## Member Functions

> ### strstreambuf *rdbuf()

> Returns a pointer to the `strstreambuf` object associated with a `strstream` object.

> ### char *str()

> Returns a pointer to an explicit array, to be used as the associated `strstreambuf` object, if the `strstream` object was constructed with such an array; otherwise, it returns a pointer to a dynamically allocated area. Until `str()` is called, deleting the dynamically allocated area is the responsibility of the `strstream` object. After `str()` returns, dynamic allocation becomes the responsibility of the user program. After `str()` has been called, the effect of storing more characters into the `strstream` object is undefined.

# strstreambuf class

> Specializes the `streambuf` class for input and output performed on arrays of bytes in memory.

## Header File

> `#include <strstream.hxx>`

> Alternative Header

> `#include <strstream.h>`

## Declaration

>     class strstreambuf: public streambuf
>     {
>     public:
>                             strstreambuf();
>                             strstreambuf(char *, int, char *);
>                             strstreambuf(int);
>                             strstreambuf(unsigned char *, int,
>                             unsigned char *);
>                             strstreambuf(void *(*a)(long),
>                             void (*f)(void *));

>         void                freeze(int n = 1);
>         virtual int         overflow(int);
>         virtual streambuf   *setbuf(char *, int);
>         char                *str();
>         virtual int         underflow();
>     };

## Description

> Objects of this class let you use an array of bytes (a string of characters) in memory as a `streambuf` object for stream input/output operations on various kinds of data. Mapping between abstract get and put pointers and `char *` pointers is direct in the sense that a `char *` is interpreted as logically pointing immediately ahead of the `char` it actually points to. Moving the pointers corresponds to incrementing and decrementing the `char *` values.

> To accommodate the need for strings of arbitrary length, this class supports a dynamic mode. When a `strstreambuf` object is in dynamic mode, space for the character is allocated as needed. When the sequence is extended too far, it is copied to a new array.

> If your program expects a buffer to be allocated when none was allocated, then the iostream package allocates a default buffer, with a length specified by `BUFSIZ` as defined in `stdio.h` . The package then issues the following warning:

>     Warning; a null pointer to streambuf was passed to ios::init()

## Constructors and Destructors

> ### strstreambuf()

> Constructs an empty `strstreambuf` object in dynamic mode. This means that space is automatically allocated to accommodate characters put into the `strstreambuf` object (using the `new` and `delete` operators). Because this may require copying the original characters, programs that have many characters to insert should use `setbuf()` to inform the `strstreambuf` object about the needed allocation of space, or to use one of the constructors that follow.

> ### strstreambuf(int n)

> Constructs an empty `strstreambuf` object in dynamic mode. The initial allocation of space is at least n bytes.

> ### strstreambuf(char *ptr, int n, char *pstart)

> ### strstreambuf(unsigned char *ptr, int n, unsigned char *pstart)

> Constructs a `strstreambuf` object to use the bytes starting at ptr. The `strstreambuf` object is in static mode; it does not grow dynamically. If n is positive, then the n bytes starting at ptr are used as the `strstreambuf` object. If n is 0, ptr is presumed to point to the beginning of a null-terminated string and the bytes of that string (not including the terminating null character) constitute the `strstreambuf` object. If n is negative, then the `strstreambuf` object is presumed to continue indefinitely.

> The get pointer is initialized to ptr. The put pointer is initialized to pstart. If pstart is not null, then the initial sequence for fetching (the get area) consists of the bytes between ptr and pstart. If pstart is null, then storing operations are treated as errors and the initial get area consists of the entire array.

> ### strstreambuf(void *(*a)(long n), void (*f)(void *ptr))

> Constructs an empty `strstreambuf` object in dynamic mode. a is used as the allocator function in dynamic mode. The argument passed to a is a `long` denoting the number of bytes to be allocated. If the a argument is null, the `new` operator is used. f is used to free (or delete) get, put, or reserve areas returned by a. The argument to f becomes a pointer to the array allocated by a. If f is null, the `delete` operator is used.

## Member Functions

> ### void freeze(int n)

> Inhibits (freezes) automatic deletion of the current array if n is nonzero, or permits (unfreezes) automatic deletion if n is 0. Deletion normally occurs when more space is needed, or when the `strstreambuf` object is being destroyed. Only space obtained through dynamic allocation is free. Storing characters into a `strstreambuf` that was dynamically allocated and is now frozen causes an error (the effect is undefined). If you want to resume storing characters in such a `strstreambuf` object you can thaw (unfreeze) it.

> ### virtual int overflow(int c)

> In classes derived from `streambuf` , it is called to consume characters. If c is not `EOF` , `overflow(c)` also must either save c or consume it. Although it can be called at other times, this function is usually called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between `pbase()` and `pptr()` , call `setp()` to establish a new put area, and (if c `!= EOF` ) store c using `sputc()` . `overflow(c)` should return `EOF` to indicate an error; otherwise, it should return something else.

> ### virtual streambuf *setbuf(char *ptr, int n)

> Causes the `strstreambuf` object to remember n (if ptr is 0); this ensures that at least n bytes are allocated during the next dynamic mode allocation.

> ### char *str()

> Returns a pointer to the first character in the current array and freezes the `strstreambuf` object. If the `strstreambuf` object was constructed with an explicit array, the function returns a pointer to that array. If the `strstreambuf` object is in dynamic allocation mode but nothing has been restored yet, the returned pointer is null.

> ### virtual int underflow()

> In classes derived from `streambuf` , it is called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, `underflow()` should return `EOF` and leave an empty get area.

# Chapter 5
Messages Package

The Messages package provides a way to retrieve messages stored in a catalog or file that is separate from your program. It consists of a single class, `Messages` , that retrieves the text of a message.

Processing a message file on an OpenVMS system requires a message set number and a message number. A message set number is an OpenVMS message identification code, including a facility code (bits 16 through 27) and a facility-specific bit (bit 15); all other bits should be 0. A message number is an integer from 1 to 8191. To process the message file, use the OpenVMS Message Utility (see the OpenVMS Message Utility Manual for details) and link the resulting object code into one of the following:

- Your program
- A shareable image that your program is linked against
- A shareable image that is then specified with the `set message` command

# Messages class

> Retrieves message text for a message number.

## Header File

> `#include <messages.hxx>`

> Alternative Header

> None.

## Declaration

>     class Messages
>     {
>     public:
>        Messages(const char *filename_arg, int set_arg = 0,
>             const char *default_file_location_arg = (const char *)(NULL));
>        ~Messages();

>        const char *text(int msg_arg, const char *fallback_text_arg,
>              int set_arg = 0);
>     };

## Constructors and Destructors

> ### Messages(const char *filename_arg, int set_arg, const char *default_file_location_arg)

> Constructs a `Messages` object. set_arg specifies the message number to set; a value of 0 specifies that the default set be used. filename_arg and default_file_location_arg are ignored.

> ### ~Messages()

> Deletes a `Messages` object.

## Member Function

> ### const char *text(int msg_arg, const char *fallback_text_arg, int set_arg)

> Returns the text of the message specified by the msg_arg argument. The fallback_text_arg argument indicates the text to return if the message cannot be found. The set_arg argument specifies the message set number; a value of 0 causes the system to use the set number provided to the constructor.

> Depending on the process defaults, the facility, error severity, and message identification code may be appended to the beginning of the message (for example, `%CXXL-W-E_ONEXT` , prefixed to `Can't delete an object that is on a list.` ).

## Example

> The following is a sample message source file:

    .TITLE      MESSAGES_EXAMPLE_MSG    Example messages -- VMS message catalog
    .IDENT      '1.0'
    .FACILITY   EXAMPLE, 1 /PREFIX=EXAMPLE_

    .BASE 0
    .SEVERITY WARNING    ! we just want a 0 in the severity field
    SET <>               ! message set number

    .SEVERITY ERROR
    EXAMPLE_ERROR <This is an example error message>

    .END

> Entering the following OpenVMS Message Utility commands set the appropriate options and compile this file:

    $ set message/nofac/nosev/noid
    $ message/lis MESSAGES_EXAMPLE_MSG

> The following program retrieves the sample error message:

    #include <iostream.hxx>
    #include <messages.hxx>

    const char *message_file_name = (const char *)(NULL);
    const char *message_file_location = (const char *)(NULL);
    #pragma __extern_model __save
    #pragma __extern_model __globalvalue
    extern int EXAMPLE_SET;
    #pragma __extern_model __restore
    int message_set_example = EXAMPLE_SET;

    Messages m_example (message_file_name, message_set_example,
        message_file_location);

    int main()
    {
        cout <<
            "text of example message 1: " <<
            m_example.text(1, "fallback message 1") <<
            "\n";

        cout <<
            "text of example message 2: " <<
            m_example.text(2, "fallback message 2") <<
            "\n";

        return 0;
    }

> The following compiler command compiles the program:

    $ cxx/lis MESSAGES_EXAMPLE

> Entering the following link and run sequence retrieves the text of the error message and displays the second fallback message:

    $ link MESSAGES_EXAMPLE,MESSAGES_EXAMPLE_MSG

    $ run/nodeb messages_example
    text of example message 1: This is an example error message
    text of example message 2: fallback message 2

Previous | Next | Contents | Index

privacy and legal statement