Indexing Functions


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Programming BEA Tuxedo ATMI Applications Using FML \| Local Topics \| Previous Topic \| Next Topic \| Contents

Indexing Functions

When a fielded buffer is initialized by Finit or Falloc, an index is automatically set up. This index is used to expedite fielded buffer accesses and is transparent to you. As fields are added to or deleted from the fielded buffer, the index is automatically updated.

However, when storing a fielded buffer on a long-term storage device, or when transferring it between cooperating processes, it may be desirable to save space by eliminating its index and regenerating it upon receipt. The functions described in this section may be used to perform such index manipulations.

Fidxused

This function returns the amount of space used by the index of a buffer.

long
Fidxused(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer.

You can use this function to determine the size of the index of a buffer, and whether significant time or space can be saved by deleting the index.

For more information, refer to Fidxused, Fidxused32(3fml) in the BEA Tuxedo ATMI FML Function Reference.

Findex

The function Findex may be used at any time to index an unindexed fielded buffer.

int
Findex(FBFR *fbfr. FLDOCC intvl)

Here:

fbfr is a pointer to a fielded buffer.
intvl is the indexing interval.

The second argument to Findex specifies the indexing interval for the buffer. If 0 is specified, the value FSTDXINT (defined in fml.h) is used. The user may ensure that all fields are indexed by specifying an interval of 1.

Note that more space may be made available in an existing buffer for user data by increasing the indexing interval, and reindexing the buffer. This represents a space/time trade-off, however, since reducing the number of index elements (by increasing the index interval), means, in general, that searches for fields will take longer. Most operations attempt to drop the entire index if they run out of space before returning a "no space" error.

For more information, refer to Findex, Findex32(3fml) in the BEA Tuxedo ATMI FML Function Reference.

Frstrindex

This function can be used instead of Findex for cases in which the fielded buffer has not been altered since its index was removed.

int
Frstrindex(FBFR *fbfr, FLDOCC numidx)

Here:

fbfr is a pointer to a fielded buffer.
numidx is the value returned by the Funindex function.

For more information, refer to Frstrindex, Frstrindex32(3fml) in the BEA Tuxedo ATMI FML Function Reference.

Funindex

Funindex discards the index of a fielded buffer and returns the number of index entries the buffer had before the index was stripped.

FLDOCC
Funindex(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer.

For more information, refer to Funindex, Funindex32(3fml) in the BEA Tuxedo ATMI FML Function Reference.

Example of Sending a Fielded Buffer Without an Index

To transmit a fielded buffer without its index, complete a procedure such as the following:

Remove the index:
```
save = Funindex(fbfr);
```
Get the number of bytes to send (that is, the number of significant bytes from the beginning of the buffer):
```
num_to_send = Fused(fbfr);
```
Send the buffer without the index:
```
transmit(fbfr,num_to_send);
```
Restore the index to the buffer:
```
Frstrindex(fbfr,save);
```

The index may be regenerated on the receiving side by the following statement:

Findex(fbfr);

Note that the receiving process cannot call Frstrindex because it did not remove the index itself, and the index was not sent with the file.

Note: The space used in memory by the index is not freed by calling Funindex. The Funindex function only saves space on disk or when sending a buffer to another process. Of course, you are always free to send a fielded buffer and its index to another process and avoid using these functions.