Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo FML Function Reference

Frstrindex(), Frstrindex32() - restore index in a buffer

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

A fielded buffer that has been unindexed may be reindexed by either calling Findex() 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() function.

Frstrindex32() is used with 32-bit FML.

A thread in a multithreaded application may issue a call to Frstrindex() or Frstrindex32() while running in any context state, including TPINVALIDCONTEXT.

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

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().

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:

1. - /* unindex, saving for Frstrindx */ 
2. - /* determine number of bytes to send */ 
3. - /* send fbfr, without index */ 
4. - /* 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(), as in:

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

The receiving process cannot call Frstrindx() because:

1. it did not call Funindex() and so has no idea of what the value of the numidx argument to Frstrindex() should be

2. the index itself is not available because it was not sent.

The solution is to call Findex() explicitly. Of course, the user is always free to transmit the indexed versions of a fielded buffer (that is, send Fsizeof(*fbfr) bytes) and avoid the cost of Findex() on the receiving side.

Introduction to FML Functions, Findex, Findex32(3fml), Fsizeof, Fsizeof32(3fml), Funindex, Funindex32(3fml)