![]() |
![]() |
|
|
Buffer Update Functions
The functions listed in this section access and update entire fielded buffers, rather than individual fields in the buffers. These functions use, at most, three parameters:
Fconcat
Fconcat adds fields from the source buffer to the fields that already exist in the destination buffer.
int
Fconcat(FBFR *dest, FBFR *src)
Occurrences in the destination buffer are maintained (that is, they are retained and not modified) and new occurrences from the source buffer are added with greater occurrence numbers than any existing occurrences for each field. The fields are maintained in field identifier order.
Consider the following example:
FBFR *src, *dest;
. . .
if(Fconcat(dest,src) < 0)
F_error("pgm_name");
If dest has fields A, B, and two occurrences of C, and src has fields A, C, and D, the resulting dest has two occurrences of field A (destination field A and source field A), field B, three occurrences of field C (two from dest and the third from src), and field D.
This operation fails if there is not enough space for the new fields (FNOSPACE); in this case, the destination buffer remains unchanged.
For more information, refer to Fconcat, Fconcat32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
Fjoin
Fjoin is used to join two fielded buffers based on matching field ID/occurrence.
int
Fjoin(FBFR *dest, FBFR *src)
For fields that match on field ID/occurrence, the field value is updated in the destination buffer with the value from the source buffer. Fields in the destination buffer that have no corresponding field ID/occurrence in the source buffer are deleted. Fields in the source buffer that have no corresponding field ID/occurrence in the destination buffer are not added to the destination buffer. Thus
if(Fjoin(dest,src) < 0)
F_error("pgm_name");
Using the input buffers in the previous example results in a destination buffer that has source field value A and source field value C. This function may fail due to lack of space if the new values are larger than the old (FNOSPACE); in this case, the destination buffer will have been modified. However, if this happens, the destination buffer may be reallocated using Frealloc and the Fjoin function repeated (even if the destination buffer has been partially updated, repeating the function gives the correct results).
If joining buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.
For more information, refer to Fjoin, Fjoin32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
Fojoin
Fojoin is similar to Fjoin, but it does not delete fields from the destination buffer that have no corresponding field ID/occurrence in the source buffer.
int
Fojoin(FBFR *dest, FBFR *src)
Note that fields in the source buffer for which there are no corresponding field ID/occurrence pairs in the destination buffer are not added to the destination buffer. Consider the following example:
if(Fojoin(dest,src) < 0)
F_error("pgm_name");
Using the input buffers from the previous example, dest contains the source field value A, the destination field value B, the source field value C, and the second destination field value C. As with Fjoin, this function can fail for lack of space (FNOSPACE) and can be reissued again after more space has been allocated to complete the operation.
If joining buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.
For more information, refer to Fojoin, Fojoin32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
Fproj
Fproj is used to update a buffer in place so that only the desired fields are kept. (The result, in other words, is a projection on specified fields.) If updating buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.
int
Fproj(FBFR *fbfr, FLDID *fieldid)
These fields are specified in an array of field identifiers passed to the function. The update is performed directly in the fielded buffer. Consider the following example:
#include "fldtbl.h"
FBFR *fbfr;
FLDID fieldid[20];
. . .
fieldid[0] = A; /* field id for field A */
fieldid[1] = D; /* field id for field D */
fieldid[2] = BADFLDID; /* sentinel value */
if(Fproj(fbfr, fieldid) < 0)
F_error("pgm_name");
If the buffer has fields A, B, C, and D, the example results in a buffer that contains only occurrences of fields A and D. Note that the entries in the array of field identifiers do not need to be in any specific order, but the last value in the array of field identifiers must be field identifier 0 (BADFLDID).
For more information, refer to Fproj, Fproj32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
Fprojcpy
Fprojcpy is similar to Fproj but the desired fields are placed in a destination buffer. If updating buffers results in the removal of a pointer field (FLD_PTR), the memory area referenced by the pointer is not modified or freed.
int
Fprojcpy(FBFR *dest, FBFR *src, FLDID *fieldid)
Any fields in the destination buffer are first deleted and the results of the projection on the source buffer are copied into the destination buffer. Using the above example, the following code places the results of the projection in the destination buffer:
if(Fprojcpy(dest, src, fieldid) < 0)
F_error("pgm_name");
The entries in the array of field identifiers may be rearranged; if the entries are not in numeric order, the field identifier array is sorted.
For more information, refer to Fprojcpy, Fprojcpy32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
Fupdate
Fupdate updates the destination buffer with the field values in the source buffer.
int
Fupdate(FBFR *dest, FBFR *src)
For fields that match on field ID/occurrence, the field value is updated in the destination buffer with the value in the source buffer (like Fjoin). Fields on the destination buffer that have no corresponding field on the source buffer are left untouched (like Fojoin). Fields on the source buffer that have no corresponding field on the destination buffer are added to the destination buffer (like Fconcat). Consider the following example:
if(Fupdate(dest,src) < 0)
F_error("pgm_name");
If the src buffer has fields A, C, and D, and the dest buffer has fields A, B, and two occurrences of C, the updated destination buffer contains: the source field value A, the destination field value B, the source field value C, the second destination field value C, and the source field value D.
For pointers, Fupdate32 stores the pointer value. The buffer pointed to by a FLD_PTR field must be allocated using the tpalloc(3c) call. For embedded FML32 buffers, Fupdate32 stores the entire FLD_FML32 field value, except the index. For embedded VIEW32 buffers, Fupdate32 stores a pointer to a structure of type FVIEWFLD, that contains vflags (a flags field, currently unused and set to 0), vname (a character array containing the view name), and data (a pointer to the view data stored as a C structure). The application provides the vname and data to Fupdate32. The FVIEWFLD structure is as follows:
typedef struct {
TM32U vflags; /* flags - currently unused */
char vname[FVIEWNAMESIZE+1]; /* name of view */
char *data; /* pointer to view structure */
} FVIEWFLD;
For more information, refer to Fupdate, Fupdate32(3fml) in the BEA Tuxedo ATMI FML Function Reference.
![]() |
![]() |
![]() |
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|