Data Exchange and Synchronization

When communicating with the Universal Streaming Service (USS), a protocol handshake must occur before data transmission can begin. The reader and writer exchange platform-specific information using a USS format label. USS format labels describe the architecture of both platforms, including the size of each native data type. This information is critical when communicating between two dissimilar architectures, such as SPARC and Intel.

Although USS format labels are automatically managed by the os_bstream class, the presence of the labels must be synchronized between both parties. Consequently, binary streams are subject to the following rules.

When you construct an os_bstream and write to it for the first time, a format label is automatically sent first. After the first write, no additional format labels are sent unless you reset the os_bstream using reset() .
When you construct an os_bstream and read from it for the first time, a format label is expected first. After the first read, the os_bstream saves the format of the writer, and will not expect another format label unless you first reset the os_bstream using reset() .

In most cases, automatic format label management is not a problem. However, because this mechanism is tied to the construction of an os_bstream object, you must follow a simple rule to ensure that your stream ends are synchronized.

RULE-The scope of the reader os_bstream and writer os_bstream must be consistent.

For example, if you construct a single os_bstream and write three objects to it, construct a single os_bstream and read three objects from it. Do not construct three os_bstream objects and read one object from each.

The following diagram illustrates the effect of inconsistent scope when using os_bstream objects. The writer constructs a single os_bstream and writes three X objects to it. If the reader constructs an os_bstream in a loop and reads one X object per loop iteration, as shown in the incorrect reader example below, the reader expects a format label three times. Instead, construct the reader to use a single os_bstream for all iterations of the loop, as shown in the correct reader example below.

Often, a protocol adapter must maintain its own state information to correctly translate between the encoded data representation and the native machine format. For instance, most protocols share the concept of memory alignment, which can force extra padding between data values. To ensure the correct amount of padding is written, the protocol adapter must remember the last data type written to the stream.

To accommodate the need for state information in protocol adapters, follow these simple rules to ensure this state is managed correctly.

RULE-Never have multiple os_bstream objects connected to the same device at the same time. This technique circumvents the state information maintained in the protocol adapter, thus corrupting the final data stream.

RULE-If you seek on a device, the os_bstream object connected to the device is no longer valid. Construct a new os_bstream on the device, or reset the os_bstream objects using reset() , before reading or writing. This causes a new format synchronization.

The next sections of this manual describe the streaming of primitives, objects, and chunks of raw data using os_bstream .