PURPOSE

Frstrindex, Frstrindex32 - restore index in a buffer

SYNOPSIS


#include <stdio.h>
#include "fml.h"
int
Frstrindex(FBFR *fbfr, FLDOCC numidx)
#include "fml32.h"
int
Frstrindex32(FBFR32 *fbfr, FLDOCC32 numidx)

DESCRIPTION

A fielded buffer that has been unindexed may be reindexed by either calling Findex(3fml) or Frstrindx(). fbfr is a pointer to a fielded buffer. The former performs a total index calculation on the buffer, and is fairly expensive (requiring a full scan of the buffer). It should be used when an unindexed buffer has been altered, or the previous state of the buffer is unknown (for example, when it has been sent from one process to another without an index). Frstrindex() is much faster, but may only be used if the buffer has not been altered since its previous unindexing operation. The second argument to Frstrindx(), numidx, is the return from the Funindex(3fml) function.

Frstrindex32 is used with 32-bit FML.

RETURN VALUES

This function returns -1 on error and sets Ferror to indicate the error condition.

ERRORS

Under the following conditions, Frstrindex() fails and sets Ferror to:

[FALIGNERR]
"fielded buffer not aligned" The buffer does not begin on the proper boundary.
[FNOTFLD]
"buffer not fielded" The buffer is not a fielded buffer or has not been initialized by Finit().

EXAMPLE

In order to transmit a buffer without its index, something like the following should be performed:


save = Funindex(fbfr);
num_to_send = Fused(fbfr);
transmit(fbfr,num_to_send);	/* A hypothetical function */
Frstrindx(fbfr,save);

These four statements do the following:

```
- /* unindex, saving for Frstrindx */
```

- /* determine number of bytes to send */

```
- /* send fbfr, without index */
```
```
- /* restore index */
```

In this case, transmit() is passed a memory pointer and a length. The data to be transmitted begins at the memory pointer and has num_to_send number of significant bytes. Once the buffer has been sent, its index may be restored (assuming transmit() does not alter it in any way) using Frstrindex(). On the receiving end of the transmission, the process accepting the fielded buffer would index it with Findex(3fml), as in:


receive(fbfr); /* get fbfr from wherever .. into fbfr */
Findex(fbfr);  /* index it */

The receiving process cannot call Frstrindx() because:

It did not call Funindex(3fml) and so has no idea of what the value of the numidx argument to Frstrindex() should be
The index itself is not available because it was not sent.