Frstrindex(), Frstrindex32() - restore index in a buffer
Frstrindex(FBFR *fbfr, FLDOCC numidx)
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:
The buffer does not begin on the proper boundary.
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:
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)
Copyright © 2000 BEA Systems, Inc. All rights reserved.