FDL Functions

This chapter lists and describes the usage of FDL functions.

1. Overview

The following lists each FDL function and gives a short description.

Function Description

fballoc

Calculates the size of a field buffer and allocates memory.

fbbufop

Copies, moves, and compares field data within a field buffer by inputting the 'mode' parameter.

fbbufop_proj

Copies field data in a certain field buffer to a specified field buffer.

fbcalcsize

Calculates the size of a field buffer to allocate a proper amount of memory using the fballoc() or tpalloc() functions.

fbchg_tu

Modifies field serial data of a field key specified in a field buffer.

fbchg_tut

Replaces the value of a field key whose type is specified by the type of another field key at a specified start position in a field buffer allocated by the fballoc() or tpalloc() functions. Also changes the values of previously stored data to another value by specifying a field value type.

fbdelall

Deletes all field key data specified in a field buffer.

fbdelall_tu

Deletes all data in a field that is specified in a field key array.

fbdelete

Deletes data in a field at a specified position in a field buffer allocated by the fballoc() or tpalloc() function.

fbextread

Reads a field key and its value from a file specified in iop and saves it in a field buffer which is allocated to the memory by the fballoc() or tpalloc() functions.

fbfldcount

Returns the number of all fields within a field buffer allocated by the fballoc() or tpalloc() functions.

fbfprint

Prints field data that is saved in a field buffer to a file stream.

fbfree

Frees memory in a field buffer allocated by the fballoc() or tpalloc() functions.

fbftos

Transfers data saved in a field buffer to a matched struct buffer.

fbget

Reads the field data that corresponds to the field key of a field buffer.

fbgetalloc_tu

Reads the field data that corresponds to the sequential number of a field key.

fbgetalloc_tut

Stores the field data that corresponds to the sequential number of a field key. It is specified in a field buffer, in a defined data type in the buffer that is re-allocated to a defined length, and returned.

fbget_fbsize

Obtains the size of a field buffer allocated by the fballoc() or tpalloc() functions.

fbget_fldkey

Returns the identifier of a field matched with a specified field name by referencing the table (FDL file set in FDLFILE) that was created by compiling in fdlc.

fbget_fldname

Returns a field name for a specified field key by referencing the table (FDL file set in FDLFILE) that was created by compiling in fdlc.

fbget_fldno

Returns a field number that matches with a specified field key.

fbget_fldtype

Returns and converts the field type of a specified field key into an integer.

fbgetlast_tu

Returns the last data entry of fields defined in a field buffer.

fbget_strfldtype

Returns the field type for each field in a string.

fbget_tu

Returns the field data that corresponds to the field sequential number in a field key.

fbget_tut

Converts the field data that corresponds to a field sequential number of a specified field key into a specified type and then returns it.

fbget_unused

Calculates the size of unused fields in a field buffer allocated by the fballoc() or tpalloc() functions, and returns it in bytes.

fbget_used

Calculates the size of used fields in a field buffer allocated by the fballoc() or tpalloc() functions, and then returns it in bytes.

fbgetf

Sequentially returns the field data stored in a field buffer allocated by the fballoc() or tpalloc() functions.

fbgetlen

Returns the length of the data that corresponds to the field sequential number of a specified field key.

fbgetnth

Returns the number of fields that contains specified field data that is stored in a specified field key.

fbgetntht

Returns the sequential number of fields in which specified data is stored out of field data that is stored in a specified field key.

fbgetval

Returns the field data that corresponds to a specified field sequential number from field data that is stored in a specified field key in a field buffer.

fbgetvali

Converts field data that corresponds to a specified field sequential number into an integer, and then returns the value.

fbgetval_last_tu

Returns the last sequentially number data from the field data stored in a field key specified in a field buffer.

fbgetvall_tu

Converts the field data of a field sequential number of a field key specified in a field buffer into long type and returns it.

fbgetvals

Converts the field data of a field sequential number of a field key specified in a field buffer into string type and returns it.

fbgetvals_tu

Returns the field data that is stored in a field key in a field buffer.

fbgetvalt

Converts the field data corresponding to a field sequential number in a field key specified in a field buffer into a specified type (totype), and then returns it.

fbinit

Initializes a field buffer allocated by the tpalloc() or fballoc() function.

fbinsert

Returns data corresponding to the sequential number of a field key specified in a field buffer allocated by fballoc() or tpalloc().

fbisfbuf

Checks whether or not a specified field buffer is valid.

fbispres

Checks whether or not the field data in a sequential number of a field specified in a field buffer exists.

fbkeyoccur

Returns the number of fields in a field key specified in a field buffer.

fbmake_fldkey

Dynamically creates a new field key.

fbnext_tu

Returns the next field key and field data in a field buffer.

fbprint

Prints out the data in a field buffer with a standard output.

fbput

Adds a new field to a field buffer.

fbputt

Adds a new field to a field buffer allocated by fballoc() or tpalloc().

fbrealloc

Re-allocates a field buffer by increasing the memory capacity when the size of the buffer is not enough.

fbread

Reads data from a specified file stream and loads it in a field buffer.

fbsnull

Checks whether or not the member variable in a structure mapped to the field sequential number of a specified field key is NULL.

fbstelinit

Initializes the member variables of a structure to NULL.

fbstinit

Initializes a specified struct variable.

fbstof

Unlike fbftos(), fbstof sends data stored in a C struct buffer (stname) to a matching field buffer.

fbstrerror

In the event of a field buffer operation, returns error details to a string.

fbtypecvt

Converts the type of field data specified in fromval from fromtype into totype, and returns the data.

fbupdate

Updates the field value for a field key in a field buffer allocated by the fballoc() or tpalloc() function at a specified position. Generally the function is used to replace the data that was passed from other process in a field buffer.

fbwrite

Stores contents of a field buffer allocated by fballoc() or tpalloc() into a file stream specified in iop.

getfberrno

Returns an error code when an error occurs while performing an API function related to a field buffer.

getfberror

Returns an error code when an error occurs while performing an API function related to a field buffer.

2. fballoc

The fballoc function calculates a field buffer size and allocates its memory.

The number of fields and their lengths are passed into a function and used to calculate their size and allocate memory for the field buffer.

Allocated memory size = count * sizeof(int) + datalen + field key header size

A minimum of 1024 bytes is allocated even if the calculated size of fields is less than 1024 bytes. fballoc() only allocates the minimum required amount of memory to improve efficiency. Use the fbfree function to release the allocated memory when it is no longer used. Memory must be released after use. Dynamic memory allocation is limited to 1 GB.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
FBUF *fballoc(int count, FLDLEN datalen)

  • Parameter

    Parameter Description

    count

    The number of fields used to store data.

    datalen

    The total size of the data stored in field buffers, in bytes.

  • Return Value

    Value Description

    Memory pointer

    The function call succeeded.

    NULL

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEMALLOC

    A system error occurred because memory allocation for field buffers failed.

  • Example

    #include <fbuf.h>
#include <atmi.h>
...
FBUF *fbuf;
if ((fbuf = fballoc(100, 1000)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
/* result allocated size : 1408 bytes */

    The following is an example of an alternative method of allocating a field buffer using tpalloc(). If the third parameter of tpalloc() is set to 0 or a value less than the default value, the default value of 1024 bytes will be allocated.

    ...
FBUF *fbuf;
if ((fbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
/* result allocated size : 1024 bytes */

  • Related Functions

    fbisfbuf(), fbcalcsize(), tpalloc(), fbinit()

3. fbbufop

The fbbufop function copies, moves, and compares field data within a field buffer according to the mode parameter. The dest and src parameters cannot share the same buffer. Each parameter must use different buffers allocated to different memory.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbbufop(FBUF *dest, FBUF *src, int mode)

  • Parameter

    Parameter Description

    dest

    Pointer to a field buffer allocated by fballoc() or tpalloc(). Stores the contents of src by mode.

    src

    Pointer to a field buffer allocated by fballoc() or tpalloc(). Includes the value to be modified.

    mode

    Specifies one of the following process modes:

    • FBMOVE : Moves all src field buffer data to a dest field buffer. A string or carray buffer can be used for dest in this mode.

      To use a string or carray buffer, perform type casting on a field buffer (FBUF *) when using the dest parameter.

    • FBCOPY : Copies all src field buffer data to the dest field buffer. Both dest and src must be field buffers.

    • FBCOMP

      Compares src and dest buffers. Input options:

      • 0, 1 : Values of the dest and src field buffers match. If the values, structure, number, and order of the two buffers are identical, 0 is returned. If only the values are not identical, while the others are the same, 1 is returned.

      • -1 : dest and src field buffers do not match.

    • FBCONCAT : Adds fields from a src buffer to a dest buffer. In the dest field buffer, existing data and data from the src field buffer are stored.

    • FBJOIN : Fields whose occurrence matches the fields of a field key are copied from the src field buffer to the dest field buffer. All previously existing data in the dest field buffer is overwritten.

    • FBOJOIN : Functions the same as FBJOIN but the data of dest buffer fields that have no corresponding field key/occurrence in a source buffer are not deleted and remain in the destination buffer.

    • FBUPDATE : Similar to FBOJOIN. From the src field buffer to the dest field buffer, fields whose occurrence matches the fields of a field key are copied. Fields that do not have a corresponding field key/occurrence in the source buffer are also copied to a dest field buffer. This effectively updates a destination buffer with the contents of a source field buffer.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEMALLOC

    A system error occurred because memory allocation for field buffers failed.

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include "demo_fdl.h"
...
main()
{
    FBUF *destbuf, *srcbuf;
    …
    destbuf=fballoc(5,5);
    …
    fbput(destbuf, INPUT, "5555", 0);
    fbput(destbuf, INPUT, "7777", 0);
    fbput(destbuf, OUTPUT, "3333", 0);
    fbput(destbuf, SEQNO, "8888", 0);

    srcbuf=fballoc(5,5);
    …
    fbput(srcbuf, INPUT, "1111", 0);
    fbput(srcbuf, OUTPUT, "2222", 0);
    fbput(srcbuf, CORPNO, "3333", 0);

    /* Select a mode */
    …
    printf("input : ");
    scanf("%d", &a);

    switch(a)
    {
        /*FBMOVE mode */
        case 1:
            iRet=fbbufop(destbuf, srcbuf, FBMOVE);
            …

            fbprint(destbuf);
            break;
        /* destbuf : “1111”, “2222”, “3333”*/

        /*FBCOMP mode */
        case 2:
            iRet=fbbufop(destbuf, srcbuf, FBCOMP);
            printf("ret = %d\n", iRet);
            if(iRet < 0) {
               printf("Do not match!!!\n");
               fbfree(destbuf);
               fbfree(srcbuf);
               exit(0);
            }
            printf("Match!!!\n");
            break;
        /* “Do not match!!! */

        /*FBCOPY mode */
        case 3:
            iRet=fbbufop(destbuf, srcbuf, FBCOPY);
            …
            fbprint(destbuf);
            break;
        /* destbuf : “1111”, “2222”, “3333”*/

        /*FBCONCAT mode */
        case 4:
            iRet=fbbufop(destbuf, srcbuf, FBCONCAT);
            …
            fbprint(destbuf);
            break;
        /* destbuf : “5555”, “7777”, “3333”, “8888”, “1111”, “2222”, “3333”*/

        /*FBJOIN mode */
        case 5:
           iRet=fbbufop(destbuf, srcbuf, FBJOIN);
           …
           fbprint(destbuf);
           break;
        /* destbuf : “1111”, “2222”*/

        /*FBOJOIN mode */
        case 6:
           iRet=fbbufop(destbuf, srcbuf, FBOJOIN);
           …
           fbprint(destbuf);
           break;
        /*  destbuf : “1111”, “7777”, “2222”, “8888”*/

        /*FBUPDATE mode */
        case 7:
           iRet=fbbufop(destbuf, srcbuf, FBUPDATE);
            …
           fbprint(destbuf);
           break;
        /* destbuf : “1111”, “7777”, “2222”, “8888”, “3333”*/

    }
    fbfree(destbuf);
    fbfree(srcbuf);
}

  • Related Functions

    fbbufop_proj()

4. fbbufop_proj

The fbbufop_proj function copies the data of a specified field in a src field buffer to a dest field buffer.

The dest and src parameters cannot share the same buffer. Each parameter must use different buffers allocated to different memory.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbbufop_proj(FBUF *dest, FBUF *src, FLDKEY *fldkey)

  • Parameter

    Parameter Description

    dest

    Pointer to a field buffer allocated by fballoc() or tpalloc(). Stores the contents of src by mode.

    src

    Pointer to a field buffer allocated by fballoc() or tpalloc(). Includes the value to be modified. If src is set to NULL, the data from the specified field is copied to the dest field buffer.

    fldkey

    Specifies an array of fields to be copied. '0' must be specified at the end of an array. If the fldkey pointer is declared as an array and then multiple fields are specified to be copied to the array, field data is copied from src to dest.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEMALLOC

    A system error occurred because memory allocation for field buffers failed.

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h”
...

int iRet, i;
FBUF *destbuf, *srcbuf;
FLDKEY fkey[4];

...
fbput(destbuf, INPUT, "aaa", 0);
fbput(destbuf, OUTPUT, "bbb", 0);
fbput(destbuf, SEQNO, "ccc", 0);
...
fbput(srcbuf, TEST1, "AAA", 0);
fbput(srcbuf, TEST2, "BBB", 0);
fbput(srcbuf, TEST3, "CCC", 0);

fkey[0]=fbget_fldkey("INPUT");
fkey[1]=fbget_fldkey("SEQNO");
fkey[2]=0; /* The last entry in the array must be 0 */

ret=fbbufop_proj(destbuf, NULL, fkey);
...
/* destbuf : aaa, ccc */
...
fkey[0]=fbget_fldkey("TEST3");
fkey[1]=fbget_fldkey("TEST1");
fkey[2]=fbget_fldkey("TEST2");

fkey[3]=0; /* The last entry in the array must be 0 */

ret=fbbufop_proj(destbuf, srcbuf, fkey);
...
/* destbuf : AAA, BBB, CCC */
/* fkey array is sorted if the entries are not in numeric order */
...

  • Related Functions

    fbbufop()

5. fbcalcsize

The fbcalcsize function calculates the size of a field buffer. The calculated size is used when allocating memory for a buffer via fballoc() or tpalloc().

fbcalcsize determines the amount of data stored in a field buffer according to the number and the length of all fields in bytes.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
long fbcalcsize(int count, FLDLEN datalen)

  • Parameter

    Parameter Description

    count

    The number of fields used to store data.

    datalen

    The total size of the data stored in field buffers, in bytes.

  • Return Value

    Returns the size of a field buffer in bytes, which is calculated based on the count and datalen parameters.

  • Example

    #include “demo_fdl.h”
...

FBUF *fbuf;
long size;

size = fbcalcsize(100, 1000);
printf(“size : [%ld]\n”, size); /* output : size : [1408] */
if ((fbuf = (FBUF *)tpalloc(“FIELD”, NULL, size)) == NULL) {
    printf(“tpalloc failed, errno = %d\n”, tperrno);
    ...
}

/* fbuf is set in 1024 bytes by default if size is less than 1024*/
...

  • Related Functions

    fballoc(), tpalloc()

6. fbchg_tu

The fbchg_tu function replaces a value in a field key with another value at the specified start position in a field buffer allocated by fballoc() or tpalloc().

fbchg_tu modifies previously stored data. It also automatically adds a field key if the nth field occurrence is not in a field buffer. Performance can be reduced when adding field key data.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbchg_tu(FBUF *fbuf, FLDKEY fldkey, int nth, char *value, FLDLEN fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be changed in a field buffer.

    nth

    Index of the field key to be changed.

    value

    Field value to be replaced. value is a string. INTEGER and REAL data must be converted to CHARACTER type. If value is set to NULL, the corresponding field key is cleared.

    fldlen

    Optional. Note that the length of FB_CARRAY type fields is still required (in bytes).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long rcvlen, ret;
char buffer[100];
FLDLEN fldlen;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, tperrno);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);  /* "aaaa" is at index 0 */
ret = fbchg_tu(fbuf, INPUT, 1, “bbbb ”, 4);   /* "bbbb" is added at index 1 */
if (ret < 0) {
    error processing...
}
ret = fbget_tu(fbuf, INPUT, 1, buffer, &fldlen);
/* Load the data at index 0 into the buffer */
if (ret < 0) {
    error processing...
}
printf(“Field Data: [%s]\n”, buffer);
/* output : Field Data: [bbbb] */

fbprint(fbuf);
/* output : aaaa, bbbb   */
...

  • Related Functions

    fbbufop_proj()

7. fbchg_tut

The fbchg_tut function replaces a value in a field key with a type specified by type. The value is replaced at a specified start position in a field buffer allocated by the fballoc() or tpalloc() function.

fbchg_tut, similar to fbchg_tu(), modifies previously stored data by specifying a type of a field value. However, fbchg_tut is used when the data types of the new and old data differ. It also automatically adds a field key if the nth field key data value is not in a field buffer. Performance can be reduced when adding field key data.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbchg_tut(FBUF *fbuf, FLDKEY fldkey, int nth, char *value, FLDLEN fldlen,
              int type)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be changed in a field buffer.

    nth

    Index of the field to be changed.

    value

    Field value to be replaced. value is a string. INTEGER and REAL data must be converted to CHARACTER type. If value is set to NULL, the corresponding field key is cleared.

    fldlen

    Optional. Note that the length of FB_CARRAY type fields is still required (in bytes).

    type

    Field value type.

    Input options: FB_CARRAY, FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_FLOAT, FB_INT

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified. (For FB_CARRAY fields, this error occurs if the length is not specified.)

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field was used.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long ret, lVal=100000;
FBUF *fbuf;
...
fbputt(fbuf, INPUT, "aaaa", 0, FB_STRING);
fbchg_tut(fbuf, INPUT, 0, (char *)&lVal, 0, FB_LONG);
printf("1st occurrence of INPUT field is changed as follows : \n");
fbprint(fbuf);
...
/* fkey = 469762149, fname = INPUT, type = string, value = 100000 */

  • Related Functions

    fbput(), fbchg_tu(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

8. fbdelall

The fbdelall function deletes all field key data specified in a field buffer.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbdelall(FBUF *fbuf, FLDKEY fldkey)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be deleted. Before calling this function, at least 1 field occurrence must be saved in the field key in a field buffer. Otherwise, -1 is returned, and fberror is set to FBENOENT.

  • Return Value

    Value Description

    Number of deleted fields

    The function call succeeded.

    -1

    The function call failed because the specified field key was not found. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...
int ret;
FBUF *fbuf;
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

ret = fbdelall(fbuf, INPUT);
printf(“Delete Field Number: [%d]\n”, ret);
/* output: Delete Field Number: [3] */
...

  • Related Functions

    fbput(), fbget(), fbdelete(), fbdelall_tu()

9. fbdelall_tu

The fbdelall function deletes all field key data specified in a field buffer.

fbdelall_tu() is designed to delete all data in multiple field keys, while fbdelall() is designed to delete all data in a single field key.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbdelall_tu(FBUF *fbuf, FLDKEY *fldkey)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key array that contains multiple field keys to be deleted from a field buffer. The field key pointer points to a field key array that will be deleted. Specify a field key in the field key array, and enter 0 in the last index.

  • Return Value

    Value Description

    Number of deleted fields

    The function call succeeded.

    -1

    The function call failed because the field buffer was invalid. This happens when an input parameter is NULL. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    No data corresponding to the last field key specified at the fldkey array.

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...
FLDKEY fkey[3];

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, OUTPUT, “cccc”, 0);

fkey[0] = INPUT;
fkey[1] = OUTPUT;
fkey[2] = 0; /* The last entry in the array must be 0 */

ret = fbdelall_tu(fbuf, fkey);
printf(“The Number of deleted fields: [%d]\n”, ret);

/* output: Number of deleted fields: [3] */
...

  • Related Functions

    fbput(), fbget(), fbdelete(), fbdelall()

10. fbdelete

The fbdelete function deletes the data in a field at the specified position in a field buffer allocated by the fballoc() or tpalloc() function.

Unlike fbchg_tu(), if a field key is not found at the specified position, an error occurs and fberror is set to FBENOENT. A field buffer must contain a field key for this function to be called.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbdelete(FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be deleted from the field buffer.

    nth

    Index of a field to be deleted.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed because the field corresponding to the index of the specified field key was not found in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE). This error also occurs when the data corresponding to the index of the specified field does not exist in the field buffer.

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...
char buffer[100];
int ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);  /* The 0th data in fbuf is “aaaa”. */
fbput(fbuf, INPUT, “bbbb”, 0);  /* The 1st data in fbuf is “bbbb”. */
fbput(fbuf, INPUT, “cccc”, 0);  /* The 2nd data in fbuf is “cccc”. */
fbdelete(fbuf, INPUT, 1);         /* Delete 1st data in fbuf “bbbb”. */

ret=fbdelete(fbuf, INPUT, 3);
if(ret<0){
     printf("fbdelete error : %s\n", fbstrerror(fberror));
}                                 /* No data found in the 3rd position in fbuf. This results in a fbdelete error : FBENOENT (not found). */

fbget(fbuf, INPUT, buffer, 0);
printf(“INPUT: [%s]\n”, buffer);   /* output:  INPUT: [aaaa] */
fbget(fbuf, INPUT, buffer, 0);
printf(“INPUT: [%s]\n”, buffer);   /* output:  INPUT: [cccc] */
...

  • Related Functions

    fbput(), fbget(), fbdelall(), fbdelall_tu()

11. fbextread

The fbextread function reads a field key and its value from the file specified in iop and saves it to a field buffer allocated by fballoc() or tpalloc().

fbextread calls the fbput() function when no flags are set in <demo.f>. If the + flag is set, fbextread calls fbchg_tu() , if the - flag is set, fbextread calls fbdelete(), and if the = flag is set, fbextread calls fbchg_tu() after calling fbget_tu(). If an error occurs in a called function, the error will also occur in fbextread().

The following are the flags, which are set in the <demo.f> file.

Flag Description

+

Saves a value to index 0 of a field key in a field buffer.

-

Deletes the data at index 0 of a field key in a field buffer.

=

Replaces the value at index 0 of the first field name with the value at index 0 of the second field name. For example, in the code below, index 0 of field_name1 is replaced by index 0 of field_name2.

#

Comment.

Null

Adds a new field to a field buffer.

The following are the formats of the data contained in a file that is read by fbextread. The formats are listed by flag.

  1. flag '+' (Or no flag)

    [flag] field_name or field_id (tab) field_value

  2. flag '='

    [flag] field_name1 or field_id1 (tab) field_name2 or field_id2

  3. flag '–'

    [flag] field_name or field_id

The following shows how to use the function.

  • Prototype

    #include <stdio.h>
#include <usrinc/fbuf.h>

int fbextread(FBUF *fbuf, FILE *iop)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    iop

    Pointer to a file containing the field key and its values.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes. Additionally, other errors that occur in the fbput(), fbinsert(), fbdelete(), fbget_tu(), and fbchg_tu() functions are included.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

    FBESYSTEM

    The file has no data to be read.

  • Example

    #include <stdio.h>
#include <usrinc/atmi.h>
#include <usrinc/fbuf.h>
#include "demo_fdl.h"

int main()
{
        long len;
        int ret;
        FILE *fp;
        FBUF *fbuf;
        FLDLEN fldlen;
        char buffer[100];

        fbuf = (FBUF *)tpalloc("FIELD", NULL, 0);
        if (fbuf == NULL) {
            printf("fbuf tpalloc fail[%d]\n", tperrnㅇo);
        }
        ret = fbput(fbuf, INPUT, "user_input", 10);
        if (ret < 0) {
            printf("fbput fail[%d]\n", fberror);
            return -1;
        }
        ret = fbput(fbuf, OUTPUT, "user_output", 10);
        if (ret < 0) {
            printf("fbput fail[%d]\n", fberror);
            return -1;
        }
        ret = fbput(fbuf, STATLIN, "user_statlin", 10);
        if (ret < 0) {
            printf("fbput fail[%d]\n", fberror);
            return -1;
        }
        fp = fopen("file", "r");
        fbprint(fbuf);

        ret = fbextread(fbuf, fp);
        if (ret < 0) printf("Fextread fail[%s]\n", fberror);

        printf("\n\n<after Fextread>-----------------\n");
        fbprint(fbuf);
        tpfree((char *)fbuf);
}

    • With the '+' flag, the value at index 0 of the STSTLIN field key is changed to 'statlin0_'.

      +STATLIN       statlin0_

      [ Result ]

      user_input, user_output, statlin0_, user_statlin

    • The field value is added to the fbuf buffer.

      OUTPUT  OUTPUT0_
INPUT   INPUT0_
INPUT   INPUT1_

      [ Result ]

      user_input, user_output, user_statlin, OUTPUT0_, INPUT0_, INPUT1_

    • With the '=' flag, the INPUT values are saved to OUTPUT.

      =OUTPUT  INPUT
      user_input, user_input, user_statlin

    • With the '-' flag, the INPUT field key is deleted.

      –INPUT

      [ Result ]

      user_output, user_statlin

  • Related Functions

    fbput(), fbchg_tu(), fbdelete(), fbget_tu()

12. fbfldcount

The fbfldcount function returns the total number of fields within a field buffer allocated by the fballoc() or tpalloc() function.

fbfldcount counts the number of field values stored in a field buffer. Various built-in APIs can be used to check the number of fields stored in a field buffer. Even if multiple field keys have the same value, the function recognizes each value as a unique field.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbfldcount(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

  • Return Value

    Value Description

    Number of fields

    The function call succeeded. The number of fields currently stored in the field buffer is returned.

    0

    The function call failed because no fields were found in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to the following code.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h”
...

int cnt;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, OUTPUT, “cccc”, 0);
cnt = fbfldcount(fbuf);
printf(“Field Count: [%d]\n”, cnt);

/* output: Field Count: [3] */
...
}

  • Related Functions

    fbgetnth(), fbkeyoccur()

13. fbfprint

The fbfprint function outputs field data in a field buffer to a file stream.

fbfprint outputs data in a field buffer to a text file. The print format is the same as that of the fbprint() function.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbfprint(FBUF *fbuf, FILE *iop)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    iop

    File stream to store output data.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEBADFB

    An invalid field buffer was used. Use another buffer that is correctly allocated to memory.

    FBEINVAL

    An invalid input parameter was specified.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
FILE *iop;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

iop = fopen(“sample.text”, “w”);
fbput(fbuf, INPUT, “5555”, 0);
fbput(fbuf, INPUT, “7777”, 0);
fbfprint(fbuf, iop);
fclose(iop);

  • Related Functions

    fbprint()

14. fbfree

The fbfree function frees memory that is allocated by fballoc() or tpalloc() for a field buffer.

fbfree releases a previously allocated buffer from memory. Once this function is executed, the current buffer can no longer be used. Call this function only after the buffer is no longer needed.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbfree(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to the following code.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h”
...
int ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
ret = fbfree(fbuf);
printf(“fbfree, ret = %d\n”, ret);
/* output : fbfree, ret = 1 */
fbput(fbuf, INPUT, “bbbb”, 0);
fbprint(fbuf);
/* an error occurs since memory was not allocated. */

  • Related Functions

    fbcalcsize(), tpalloc(), fballoc(), fbinit()

15. fbftos

The fbftos function transfers field buffer data to a matching structure buffer.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbftos(FBUF *fbuf, char *cstruct, char *stname)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    cstruct

    Pointer to a structure-type variable cast to (char *).

    stname

    String that contains the name of the structure defined in VIEW.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBEBADSTRUCT

    An invalid structure was used, usually due to an unrecognized type or incorrectly compiled definition file.

  • Example

    #include “demo_fdl.h”
#include “demo_sdl.h”
...
int ret, fdllen, val = 1000;
struct demo temp;
FBUF *fbuf;
Char *cstruct;

if(tpstart((TPSTART_T *)NULL) == -1) {
    printf(“tpstart failed\n”);
    ...
}

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

cstruct = (char *)&temp;
if(fbstinit((char *)&temp, “demo”) < 1)  {
    printf(“fbstinit failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INTDATA, (char *)&val, 0);

if(fbftos(fbuf, cstruct, “demo”) < 0) {
    ...
}
...

  • Related Functions

    fbstof(), fbstinit(), fbstelinit()

  • Note

    The fbftos function transfers field buffer data to a matching structure buffer (stname).

    The ***.s structure file, which differs from a general structure file, must be defined in advance. Each field key within a structure file must be mapped to a single member variable of the structure to be defined.

    The following is a sample structure file that provides a mapping function between a field buffer and a C struct.

    VIEW demo
#type      cname      Fldkey      count      flag      size      null
string   demodata     INPUT          5        -         20       “”
carray  carraydata    CARRAYDATA     1        -         20     “star”
char    chardata      CHARDATA       1        -         -       “c”
int       inum        INTDATA        5        -         -         0
short     snum        SHORTDATA      1        -         -         0
long      lnum        LONGDATA       1        -         -         1
float     fnum        FLOATDATA      1        -         -        1.0
double    dnum        DOUBLEDATA     1        -         -        1.0
END
    Item Description

    type

    Data type of a member variable within a structure.

    cname

    Name of a member variable.

    Fldkey

    Field key mapped to a specified member variable. (Field key must be defined in advance in ***.f.)

    count

    Maximum number of field occurrences that can be stored in a structure.

    size

    Size of an array (for string type).

    null

    Value during initialization. The value is copied into the C structure by default when transferring field data to the C structure buffer. If no value is stored in a field buffer and no null value is set, an appropriate default value for each data type will be stored in the C structure. The default value for string, carray and char is NULL; 0 for int, short, and long; and 0.0 for float and double.

    After defining a view in demo.s or demo.v, the VIEW file must be compiled with the sdlc utility (structure file compiling utility) in the client.

    $TMAXDIR$/sample/sdl> sdlc –c –v demo.s –o tmax.sdl
$TMAXDIR$/sample/sdl> sdlc –c –v demo.v –o tmax.sdl

    With the SDLFILE name specified in a configuration file (.profile file for korn shell), create a '.sdl' file by using the [–o] option so that SDLFILE contains the conversion information between the field key and structure. The field key defined in VIEWFILE must be defined in *.f in this case.

    When compiling VIEWFILE, <demo_sdl.h> and <tmax.sdl> are generated. Include <demo_sdl.h> in the client program. In the server, VIEWFILE must be compiled with the sdlc utility.

    $TMAXDIR$/sample/sdl> sdlc –v demo.s

    When a structure file is compiled as shown above, <demo_sdl.c> and <demo_sdl.h> will be generated. Because <demo_sdl.c> contains conversion information between a field key and the structure, all server programs must be compiled together with <demo_sdl.c>. A server program does not need <tmax.sdl> because all required information will have been provided for compilation.

    If field keys are not mapped to member variable data when transferring field buffer data to a structure, the field keys will be ignored.

16. fbget

The fbget function gets the field data that corresponds to a field key in a field buffer.

fbget retrieves data from a field buffer. Field data for a specified key is read sequentially and then saved to loc. The fbget function reads all field data saved in the field key without having to manually increase the occurrence number. Once data is retrieved it cannot be read again. If this function is called more than the number of occurrences, the field data of the last field will be continuously returned.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbget(FBUF *fbuf, FLDKEY fldkey, char *loc, FLDLEN *fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be read from a field buffer.

    loc

    Pointer to the field data that is sequentially read. If a field key is an integer or real, use a variable appropriate for each type and perform type casting by using the prototype mentioned above.

    fldlen

    Length of data read.

  • Return Value

    Value Description

    1

    The function call suceeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified. For CARRAY-type data, this error occurs if fldlen is not specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long rcvlen, ret;
FLDLEN fldlen;
char buffer[100];
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

fbget(fbuf, INPUT, buffer, &fldlen);
printf(“Field Data: [%s]\n”, buffer);
/* output: Field Data: [aaaa] */
...

  • Related Functions

    fbput(), fbchg_tu(), fbget_tu(), fbchg_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

17. fbgetalloc_tu

The fbgetalloc_tut function stores field data that corresponds to a specified field occurrence of a specified field key.

fbgetalloc_tu reads field data that corresponds to the field occurrence of a field key specified in the nth and fldkey parameters. fbgetalloc_tu then allocates a new buffer with a length specified by extralen to store the field data in the buffer and returns a pointer.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetalloc_tu(FBUF *fbuf, FLDKEY fldkey, int nth, int *extralen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be read from a field buffer.

    nth

    Index of a field to be read.

    extralen

    Size of the buffer to be newly allocated in bytes. The memory allocated for the buffer must be released when it is no longer used. If extralen is 0, the buffer size is set to the length of the field data.

  • Return Value

    Value Description

    Pointer to the buffer

    The function call succeeded.

    NULL

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEMALLOC

    A system error occurred because memory allocation for field buffers failed.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long ret;
int extralen;
char *buffer;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

extralen = 4;
buffer = fbgetalloc_tu(fbuf, INPUT, 0, &extralen);
printf(“Field Data: [%s]\n”, buffer);
/* output: Field Data: [aaaa], returned after adding 4 bytes to
the length of the field value. */
fbfree(fbuf);
….

  • Related Functions

    fbgetalloc_tut(), fbput(), fbchg_tu(), fbget_tu(), fbchg_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

18. fbgetalloc_tut

The fbgetalloc_tut function stores field data that corresponds to the specified field occurrence of the specified field key. It converts the field data to the specified type and allocates a new buffer with a length specified by extralen. The new buffer stores the field data, and fbgetalloc_tut returns the pointer.

fbgetalloc_tut() is similar to fbgetalloc_tu(), however, fbgetalloc_tut() can convert field data types.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetalloc_tut(FBUF *fbuf, FLDKEY fldkey, int nth, int type, int *extralen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be retrieved from the field buffer.

    nth

    Index of a field to be read.

    type

    Field value type. Input options: FB_CARRAY, FB_SHORT , FB_DOUBLE , FB_LONG , FB_STRING, FB_CHAR, FB_FLOAT , FB_INT

    extralen

    Size in bytes to allocate for a new buffer. The memory allocated for the buffer must be released when it is no longer used. If extralen is 0, the buffer size will be set to the length of the field data.

  • Return Value

    Value Description

    Pointer to the buffer

    The function call succeeded. (Returns a pointer to a newly allocated buffer containing field data. If the value type is int, long, double, long, or float type, they cannot be expressed in char *, so perform type casting.)

    NULL

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEMALLOC

    A system error occurred because memory allocation for field buffers failed.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long ret;
int extralen;
char *buffer;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

extralen = 4;
buffer = fbgetalloc_tut(fbuf, INPUT, 0, FB_STRING, &extralen);
printf(“Field Data: [%s]\n”, buffer);
/* output: Field Data: [aaaa], returned after adding 4 bytes to the length of the
field value. */

fbfree(fbuf);
...

  • Related Functions

    fbgetalloc_tu (), fbput(), fbget_tu(), fbchg_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

19. fbget_fbsize

The fbget_fbsize function gets the size of a field buffer allocated by fballoc() or tpalloc().

A minimum of 1024 bytes is allocated to a field buffer by fballoc() or tpalloc() even if the calculated buffer size is less than 1024 bytes. If 1024 bytes are allocated, fbget_fbsize() returns 1024 + 8 = 1032 bytes because a 8-byte header that is internally used within Tmax is added. If the size of a field buffer is greater than 1024 bytes, fbget_fbsize() returns (fbcalcsize() + 8 (header size)).

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
long fbget_fbsize(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

  • Return Value

    Value Description

    Size of the field buffer

    The function call succeeded.

  • Error

    fberrno is set to the following code.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h”
...
long ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “1111”, 0);
ret = fbget_fbsize(fbuf ) ;
printf(“Field Buffer Size: [%ld]\n”, ret);
/* output: Field Buffer Size: [1024] */
...

  • Related Functions

    fbcalcsize(), tpalloc(), fballoc(), fbfree(), fbinit()

20. fbget_fldkey

The fbget_fldkey function gets the field key of a specified field name by referencing a table (FDL file set in FDLFILE) that was created after compilation by fdlc. A user must know the field key for a specified field name to store data in a field buffer because a field buffer is based on field key-data pairs.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
FLDKEY fbget_fldkey(char *name)

  • Parameter

    Parameter Description

    name

    Field name used to create a field table.

  • Return Value

    Value Description

    0

    The specified field name is not found in the field table.

    Field key matching the field name

    The specified field name is found in the field table.

  • Example

    #include “demo_fdl.h”
...
FLDKEY fkey;
FBUF *sndbuf;

fkey = fbget_fldkey(“INPUT”);
printf(“Field Key : [%d]\n”, fkey);

/* output : Field Key : [469762149] */
...
fbput(sndbuf, fkey, “1111", 0);
...

  • Related Functions

    fbget_fldname(), fbget_fldno(), fbget_fldtype(), fbget_strfldtype(), fbtypecvt()

21. fbget_fldname

In contrast to the fbget_fldkey() function, the fbget_fldname function returns the field name of a specified field key by referencing the table (FDL file set in FDLFILE) that was created after compilation by fdlc.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbget_fldname(FLDKEY fldkey)

  • Parameter

    Parameter Description

    fldkey

    Field key obtained by using fbget_fldkey() or by referring to a header file(***_fdl.h). The header file is generated by compiling the file(***.f), which is used to create a field table in fdlc.

  • Return Value

    Value Description

    Field key matching the field name

    The specified field name is found in the field table.

    NULL

    The specified field name is not found in the field table.

  • Example

    #include “demo_fdl.h”
...
FLDKEY fkey;
char *name;

fkey = fbget_fldkey(“INPUT”);
printf(“Field Key : [%d]\n”, fkey);
/* output : Field Key : [469762149] */

name = fbget_fldname(fkey);
printf(“Field Name : [%s]\n”, name);
/* output : Field Name : [INPUT] */
...

  • Related Functions

    fbget_fldkey(), fbget_fldno(), fbget_fldtype(), fbget_strfldtype(), fbtypecvt()

22. fbget_fldno

The fbget_fldno returns the field number that matches the specified field key. To create a field table, a field type, field name, and field number are required, and they can be combined to generate a unique field key. A field table manages these field keys.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbget_fldno(FLDKEY fldkey)

  • Parameter

    Parameter Description

    fldkey

    Field key obtained by using fbget_fldkey() or by referring to a header file(***_fdl.h). The header file is generated by compiling the file(***.f), which is used to create a field table in fdlc.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field was used.

  • Example

    #include “demo_fdl.h”
...
long ret;
FLDKEY len;
int nth;
char buffer[100];
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

fbgetlast_tu(fbuf, INPUT, &nth, buffer, &len);
printf(“Field Data: [%s], occurrence = %d, len = %d\n”, buffer, nth, len);
/* output: Field Data: [cccc], occurrence = 2, len = 4 */
...

  • Related Functions

    fbput(), fbchg_tu(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetalloc_tu()

23. fbget_fldtype

The fbget_fldtype returns the field type of a specified field key as an integer.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbget_fldtype(FLDKEY fldkey)

  • Parameter

    Parameter Description

    fldkey

    Field key obtained by using fbget_fldkey() or by referring to a header file(***_fdl.h). The header file is generated by compiling the file(***.f), which is used to create a field table in fdlc.

  • Return Value

    The return value is an integer between 1 and 8, as follows:

    Return value Field type

    1

    character

    2

    short integer

    3

    integer

    4

    long integer

    5

    float

    6

    double

    7

    string

    8

    character array(carray)

  • Example

    #include “demo_fdl.h”
...
FLDKEY fkey;
int type;

fkey = fbget_fldkey(“INPUT”);
printf(“Field Key : [%d]\n”, fkey);/* output: Field Key : [469762149] */
type = fbget_fldtype(fkey);
printf(“Field Type : [%d]\n”, type);/* output : Field Type : [7] */
...

  • Related Functions

    fbget_fldname(), fbget_fldno(), fbget_fldkey(), fbget_strfldtype(), fbtypecvt()

24. fbgetlast_tu

The fbgetlast_tu function returns the data of the final field occurrence of a field key in a field buffer. fbgetlast_tu also returns the data index and field data length.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbgetlast_tu(FBUF *fbuf, FLDKEY fldkey, int *nth, char *loc, int *len)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a buffer allocation by fballoc() or tpalloc().

    fldkey

    Field key to be read from the field buffer.

    nth

    Index of the field key to be read.

    loc

    Pointer to the field data retrieved.

    len

    Length of the field data retrieved.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field was used.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long ret;
FLDKEY len;
int nth;
char buffer[100];
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

fbgetlast_tu(fbuf, INPUT, &nth, buffer, &len);
printf(“Field Data: [%s], occurrence = %d, len = %d\n”, buffer, nth, len);
/* output: Field Data: [cccc], occurrence = 2, len = 4 */
...

  • Related Functions

    fbput(), fbchg_tu(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetalloc_tu()

25. fbget_strfldtype

The fbget_strfldtype returns the field type of each field as a string. While fbget_fldtype() returns a field type as an integer, fbget_strfldtype returns the field type as a string.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbget_strfldtype(FLDKEY fldkey)

  • Parameter

    Parameter Description

    fldkey

    Field key obtained by using fbget_fldkey() or by referring to a header file(***_fdl.h). The header file is generated by compiling the file(***.f), which is used to create a field table in fdlc.

  • Return Value

    Value Description

    Empty string (" ")

    The field type of the specified field key is not found or the field key is invalid.

    String (the field type of the specified field key)

    The specified field key is found.

  • Example

    #include “demo_fdl.h”
...
FLDKEY fkey;
char *stype;
...
fkey = fbget_fldkey(“INPUT”);
printf(“Field Key : [%d]\n”, fkey);
/* output : Field Key : [469762149] */

stype = fbget_strfldtype(fkey);
printf(“Field Type : [%s]\n”, stype);
/* output : Field type : [string] */

  • Related Functions

    fbget_fldname(), fbget_fldno(), fbget_fldtype(), fbtypecvt()

26. fbget_tu

The fbget_tu function retrieves the field data that corresponds to a specified field occurrence of a specified field key in a field buffer.

Like fbget_val(), fbget_tu() retrieves the value for a specified field key at a specified position. However, fbgetval() returns the field value as a pointer, while fbget_tu stores the data in a common character buffer. When compared to fbget_tu(), fbget() can read acquired data only once but fbget_tu() can read data many times.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbget_tu(FBUF *fbuf, FLDKEY fldkey, int nth, char *value, FLDLEN *len)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be read from the field buffer.

    nth

    Index of the field to be read.

    value

    Pointer to the field data retrieved. If the field key is an integer or real type, use a variable of the appropriate type and cast it according to the function prototype described above.

    len

    Length of the data retrieved.

  • Return Value

    Value Description

    1

    The specified field key was found in the field buffer.

    -1

    The specified field key was not found in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field was used.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
char buffer[100];
long rcvlen;
FLDLEN fldlen;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, OUTPUT, “cccc”, 0);

fbget_tu(fbuf, INPUT, 1, buffer, &fldlen);
printf(“Data: [%s]\n”, buffer) /* output: Data: [bbbb] */
...

  • Related Functions

    fbput(), fbget(), fbget_tut(), fbgetval(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu()

27. fbget_tut

The fbget_tut function converts the field data that corresponds to a specified field occurrence of a specified field key into a specified type and returns it. fbget_tut reads field data that corresponds to a field occurrence at the nth index of a field key.

Like fbget_tu(), fbget_tut() retrieves the field occurrence data of a specified field key. However, after retrieving the data, fbget_tut() converts the data to a specified type, while fbget_tu() does not.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbget_tut(FBUF *fbuf, FLDKEY fldkey, int nth, char *value, FLDLEN *len,
              int type)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be read from the field buffer.

    nth

    Index of the field to be read.

    value

    Pointer to the field data retrieved. If the field key is an integer or real type, use a variable of the appropriate type and cast it according to the function prototype described above.

    len

    Length of the data retrieved.

    type

    Field value type.

    Input options: FB_CARRAY, FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_FLOAT, FB_INT

  • Return Value

    Value Description

    1

    The specified field key was found in the field buffer.

    -1

    The specified field key was not found in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field was used.

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
FBUF *fbuf;
int ret, val=65;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbputt(fbuf, INPUT,  (char *)&val, 0, FB_INT);
fbputt(fbuf, INTDATA, "1111", 0, FB_STRING);
fbprint(fbuf);

fbget_tut(fbuf, INTDATA, 0, (char *)&ret, &fldlen, FB_INT);
printf("Field Data: [%d]\n", ret);
/* output: Field Data: [1111] */
...

  • Related Functions

    fbput(), fbget(), fbget_tu(), fbgetval(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu()

28. fbget_unused

The fbget_unused function calculates and returns the size (in bytes) of unused fields in a field buffer allocated by fballoc() or tpalloc().

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
long fbget_unused(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

  • Return Value

    Returns the size of unused memory in an allocated field buffer in bytes.

  • Error

    fberrno is set to the following value.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...
long ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “1111”, 0);
ret = fbget_unused (fbuf);
printf(“Unused Buffer Size: [%d]\n”, ret);

/* output: Unused Buffer Size: [1000] */
...

  • Related Functions

    fbcalcsize(), fbget_fbsize(), fbget_used()

29. fbget_used

The fbget_used function calculates and returns the size (in bytes) of the fields currently used in a field buffer allocated by fballoc() or tpalloc().

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
long fbget_used(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

  • Return Value

    Returns the size of the memory currently used by an allocated field buffer in bytes.

  • Error

    fberrno is set to the following code.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...
long ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “1111”, 0);
ret = fbget_used(fbuf);
printf(“Used Buffer Size: [%d]\n”, ret);

/* output: Used Buffer Size: [24] */
...

  • Related Functions

    fbcalcsize(), fbget_fbsize(), fbget_unused()

30. fbgetf

The fbgetf function sequentially returns the field data stored in a field buffer allocated by fballoc() or tpalloc().

fbgetf() is similar to the fbget() function, however, fbgetf() uses the location of a following field in order to improve processing time. In Microsoft Visual Basic, fbget() takes 400 seconds to get 20,000 pieces of field data while fbgetf() took only 2.5 seconds.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbgetf(FBUF *fbuf, FLDKEY fldkey, char *loc, int *fldlen, int *pos)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    loc

    Pointer to the data retrieved.

    fldlen

    Length of data read.

    pos

    Pointer to the next data to read. This parameter must be specified for each field key that uses fbgetf(), and must be initialized to 0 before calling fbgetf().

  • Return Value

    Value Description

    1

    The function call suceeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
int ret, int0_pos, str0_pos, fldlen;
char str0[30];
FBUF *fbuf;

if ((fbuf = fballoc(20000, 1000000)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

int0_pos = str0_pos = 0;
while(1)
{
    ret = fbgetf(fbuf, STR0, (char *)str0, (int *)&fldlen, &str0_pos);
    if(ret < 0)
    {
        printf(“FBERROR at STR0:%d\n”, fberror);
        break;
     }
     ret = fbgetf(fbuf, INT0, (char *)&int0, (int *)&fldlen, &int0_pos);
     if(ret < 0)
     {
        ... .
     }
     ... .
}
... .

  • Related Functions

    fbget(), fbgetval(), fbget_tu(), fbgetvals(), fbgetvali(), fbgetvalt(), fbgetvall_tu()

31. fbgetlen

The fbgetlen function returns the length of the data in a field occurrence of a specified field key.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbgetlen(FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

  • Return Value

    Value Description

    Field data length

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBEINVAL

    An invalid input parameter was specified.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
int ret;
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
if(fbgetlen(fbuf, INPUT, 1)  <  0)
{
      ...
}
...

  • Related Functions

    fbget_fbsize(), fbget_used(), fbget_unused(), fbcalcsize()

32. fbgetnth

The fbgetnth function returns the sequence of a field that contains specified field data stored in a specified field key. If data has been stored multiple times for a field, only the first number in a sequence will be returned.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbgetnth(FBUF *fbuf, FLDKEY fldkey, char *value, FLDLEN fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    value

    Pointer to the field data retrieved. If the field key is an integer or real type, use a variable of the appropriate type and cast it according to the function prototype described above.

    fldlen

    Length of data. Specify '0' if the field key type is not FB_CARRAY.

  • Return Value

    Value Description

    Field occurrence of the specified data

    The occurrence of the specified field key exists in the field buffer.

    -1

    The occurrence of the specified field key does not exist in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

    FBENOENT

    No data matching the field key was found in the field buffer.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
int occ;
FBUF *fbuf;
...
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “ddddd”, 0);
fbput(fbuf, INPUT, “eeeee”, 0);
fbput(fbuf, OUTPUT, “cccc”, 0);
occ = fbgetnth(fbuf, INPUT, “eeee”, 0);
printf(“Occurrence: [%d]\n”, occ); /* output: Occurrence: [3] */
...

  • Related Functions

    fbfldcount(), fbkeyoccur(), fbgetntht()

33. fbgetntht

The fbgetntht function returns a field occurrence for specified data that is stored in a specified field key.

If the data type of fromtype and the field type of fldkey are different, fbgetntht() will convert the data type of value into the field type of fldkey and return the field occurrence that has identical value, fldlen, and field type values. The first field data occurrence that matches value will be returned.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbgetntht(FBUF *fbuf, FLDKEY fldkey, char *value, FLDLEN fldlen, int fromtype)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    value

    Pointer to the field data retrieved. If the field key is an integer or real type, use a variable of the appropriate type and cast it according to the function prototype described above.

    fldlen

    Length of data. Specify '0' if the field key type is not FB_CARRAY.

    fromtype

    Data type.

    Input options: FB_CARRAY, FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_FLOAT, FB_INT

  • Return Value

    Value Description

    Field occurrence of the specified data

    The occurrence of the specified field key exists in the field buffer.

    -1

    The occurrence of the specified field key does not exist in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
int occ, val;
FBUF *fbuf;
...
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

val = 1111;
fbput(fbuf, INPUT,  "aaaa", 0);
fbput(fbuf, INPUT,  "dddd", 0);
fbput(fbuf, INPUT,  “1111”, 0);
fbput(fbuf, OUTPUT, "cccc", 0);

occ=fbgetntht(fbuf, INPUT, (char *)&val, 0, FB_INT);
printf("Occurrence: [%d]\n", occ); /* Occurrence: [2] */
...

  • Related Functions

    fbfldcount(), fbkeyoccur(), fbgetnth()

34. fbgetval

The fbgetval function returns field data that corresponds to a specified field occurrence (nth) in a specified field key.

Like fbget_tu(), fbget_val() retrieves the value for a specified field key at a specified position. However, fbgetval() returns the field value as a pointer, while fbget_tu stores the data in a common character buffer. The pointer within a buffer returned by fbgetval can be used to refer to but not modify the buffer. An address returned by fbgetval() is valid unless the buffer is modified. In addition, this value does not have to match a user-specified parameter type. The accuracy of this value is not guaranteed, and a system error can occur if fbgetval() refers to a value by casting long or double type.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetval(FBUF *fbuf, FLDKEY fldkey, int nth, FLDLEN *fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballField key to be read from the field buffer.

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

    fldlen

    Length of data read.

  • Return Value

    Value Description

    Pointer to data

    The occurrence of the specified field key exists in the field buffer.

    NULL

    The occurrence of the specified field key does not exist in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...

char *ptr;
long rcvlen;
FLDLEN fldlen;
FBUF *fbuf;

fbuf = fballoc(10, 100);
...

fbput(fbuf, INPUT, "aaaa", 0);
fbput(fbuf, INPUT, "bbbb", 0);

ptr=fbgetval(fbuf, INPUT, 0, &fldlen);
printf("Data: [%s]\n", ptr);    /* output: Data: [aaaa] */
printf("len = %d\n", fldlen);   /* len = 4 */
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetvalt(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu()

35. fbgetvali

The fbgetvali function converts the field data that corresponds to the specified field occurrence into an integer and then returns the value. The field data can only be converted into an integer. If the data cannot be converted into an integer (e.g. "aaaa"), 0 is returned.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbgetvali (FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

  • Return Value

    Value Description

    Integer

    The function call succeeded. The data was successfully read and returned as an integer.

    0

    The function call failed because the occurrence of the specified field key does not exist in the field buffer or an error occurred while executing the function. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBENOENT

    No data matching the field key was found in the field buffer.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h ”
...

int cnt;
int vali;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

cnt=111;
fbput(fbuf, TOTMON, (char *)&cnt, 0);
fbput(fbuf, INPUT, "aaaa", 0);
vali=fbgetvali(fbuf, TOTMON, 0);
printf("Field Data: [%d]\n", vali);  /* output: Field Data: [111] */

vali = fbgetvali(fbuf, INPUT, 0);
printf("Field Data : [%d]\n", vali);  /* output: Field Data: [0] */

fbfree(fbuf);
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetvalt(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu()

36. fbgetval_last_tu

The fbgetval_last_tu function returns the data of the last field occurrence of a field key specified by fldkey. It also returns the field occurrence value and the length of returned data.

fbgetval_last_tu is similar to the fbgetlast_tu() function. However, the data read by fbgetlast_tu() is returned as a parameter, while the data read by fbgetval_last_tu() is returned as return value. To use data, fbgetlast_tu() must move data to a local buffer in the program, while fbgetval_last_tu() can use data as a parameter of another function.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetval_last_tu(FBUF *fbuf, FLDKEY fldkey, int *nth, FLDLEN *fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

    fldlen

    Length of data read.

  • Return Value

    Value Description

    Pointer to data

    The specified field key was found in the field buffer. A pointer the retrieved data (char type) is returned.

    NULL

    The specified field key was not found in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...

char     *ptr;
long     rcvlen;
int      i,occ ;
FLDLEN   fldlen;
FBUF     *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “ddddd”, 0);
fbput(fbuf, INPUT, “eeeee”, 0);
fbput(fbuf, OUTPUT, “cccc”, 0);

ptr = fbgetval_last_tu(fbuf, INPUT, &occ, &fldlen);
printf(“Data: [%s], Occurrence: [%d]\n”, ptr, occ);
/* output: Data: [eeeee], Occurrence: [3] */
for (i = 0; i < occ; i++) {
    ptr = fbgetval(fbuf, INPUT, i, &fldlen);
    printf(“Data: [%s]\n”, ptr);
}
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetvalt(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu(), fbgetlast_tu()

37. fbgetvall_tu

The fbgetvall_tu() function converts the field data that corresponds to a specified field occurrence (nth) in a specified field key to long type and then returns it. The field type of field data must be short, int, or long to be converted into long type. If the data type is not short, int, or long, fbgetvall_tu() returns 0.

fbgetvall_tu() is similar to fbgetval(), however, fbgetval() returns field data without converting the field type, while fbgetvall_tu() converts the data into long type.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
long fbgetvall_tu(FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

  • Return Value

    Value Description

    Field data

    The function call succeeded. The field data is returned as long-type data.

    0

    The function call failed. The specified field key was not found in the field buffer, or the field key type was not short, int, or long. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBETYPE

    An invalid type (unsupported by Tmax) was used. The field key type was not short, int, or long.

    FBEINVAL

    An invalid input parameter was specified.

  • Example

    #include “demo_fdl.h”
...
long lval;
short sval;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

sval = 111;
fbput(fbuf, INPUT, (char *)&sval, 0);
lval = fbgetvall_tu(fbuf, INPUT, 0);

printf(“Field Data: [%ld]\n”, lval); /* output: Field Data: [111] */
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetvalt(), fbgetval_tu(), fbgetvals_tu(), fbgetval_last_tu()

38. fbgetvals

The fbgetvals function converts the field data of a specified field occurrence into a string and then returns the value. If field data that corresponds to a specified field occurrence does not exist, NULL will be returned.

fbgetvals() is similar to fbgetval(), however, fbgetval() returns field data without converting its field type, while fbgetvals() converts the data into a string.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetvals (FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

  • Return Value

    Value Description

    Field data

    The function call succeeded. The field data is returned as a text string.

    NULL

    The function call failed because the the specified field key was not found in the field buffer, or an error occurred while executing the function. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
char *ptr;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
ptr = fbgetvals(fbuf, INPUT, 0);
printf(“Field Data: [%s]\n”, ptr);
/* output: Field Data: [aaaa] */
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetvalt(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu()

39. fbgetvals_tu

The fbgetvals_tu function returns the field data of a specified field occurrence (nth) in a specified field key.

fbgetvals_tu() is similar to fbgetval(). fbgetval() returns field data without converting a field type, while fbgetvals_tu() returns field data only if it is a string type.

If field data that corresponds to a specified field occurrence does not exist, a blank string(" ") will be returned while fbgetvals() will return NULL. While fbgetvals() can be used on all field data types, fbgetvals_tu() can be used if the type of field data is a string. If the field data type is not a string, fbgetvals_tu() will return a blank string (" ").

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetvals_tu(FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

  • Return Value

    Value Description

    Field data

    The function call succeeded.The field data is returned as a text string.

    Empty string (“ ”)

    The function call failed because the the specified field key was not found in the field buffer, or an error occurred while executing the function. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

    FBENOENT

    No data matching the field key was found in the field buffer.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
char *ptr;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
ptr = fbgetvals_tu(fbuf, INPUT, 1);
printf(“Field Data: [%s]\n”, ptr); /* output: Field Data: [bbbb] */
...

  • Related Functions

    fbget(), fbgetval(), fbgetvalt(), fbgetvals(), fbgetval_tu(), fbgetvall_tu(), fbgetval_last_tu()

40. fbgetvalt

The fbgetvalt function converts the field data that corresponds to a specified field occurrence of a specified field key into a specified type (totype) and returns it.

fbgetvalt() is similar to the fbget_tut() function. However, while the data read by fbget_tut() is returned by its own parameter, the data read by fbgetvalt() is returned by its own return value. Therefore, fbget_tut() must move data to a local buffer within the program but fbgetvalt() can immediately use the parameter of other functions.

fbgetvalt() is also similar to fbgetval(). However, while fbgetval() directly reads field data, fbgetvalt() can convert field data to a specified type and read it. Unlike fbgetval(), fbgetvalt() follows a user-defined-type parameter so it performs type casting for long or double types to return a value.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbgetvalt(FBUF *fbuf, FLDKEY fldkey, int nth, FLDLEN *len, int totype)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of data to be retrieved from the field buffer.

    nth

    Index of the field to be read.

    len

    Length of the data retrieved.

    totype

    Field value type.

    Input options: FB_CARRAY, FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_INT, FB_FLOAT

  • Return Value

    Value Description

    Pointer to data

    The function call succeeded. A pointer to the retrieved data (char type) is returned.

    NULL

    The function call failed because the occurrence of the specified field key does not exist in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...

int *ptr;
long rcvlen;
FLDLEN fldlen;
FBUF *fbuf;
Int totype;
Int val = 111;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, (char *)&val, 0, FB_INT);

ptr = fbgetvalt(fbuf, INPUT, 2, &fldlen, FB_INT);
printf(“Data: [%d]\n”, ptr); /* output: Data: [111] */
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu()

41. fbinit

The fbinit function initializes a field buffer allocated by tpalloc() or fballoc(). To use fbinit(), memory must first be allocated for a field buffer. When fbinit is called, existing data in the field buffer will be deleted.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbinit(FBUF *fbuf, FLDLEN buflen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    buflen

    Size of the field buffer to be allocated and initialized.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
FBUF *fbuf;
int ret;
long size;
size = fbcalcsize(10, 100);

if ((fbuf = (FBUF *)tpalloc(“FIELD”, NULL, size)) == NULL) {
    printf(“tpalloc failed, errno = %d\n”, tperrno);
    ...
}
ret = fbinit(fbuf, size);
printf(“fbinit, ret : [%d]\n”, ret); /* fbinit, ret: [1] */
...

  • Related Functions

    fbcalcsize(), tpalloc(), fballoc()

42. fbinsert

The fbinsert function stores specified data to a specified field occurrence in a specified field key of a field buffer allocated by fballoc() or tpalloc(). fbinsert stores data pointed to by the value in the nth field occurrence of fldkey in fbuf.

A field key and field sequential numbers must be specified in this parameter. As a result, the fbinsert function can be useful for storing data in a specific location in a field buffer. When field data is sequentially stored, a user must manually increase the nth parameter. When multiple field data is stored in a field key, field data is inserted in the field sequential number. Data can then be stored in a specified field sequential number.

Generally, fbinsert saves data to pass it to other processes in a field buffer. When saving data to a field key, increment a field occurrence to store a field value to a specified position. If a field key has multiple field occurrences, the value of the last occurrence will be valid, and the occurrence of the next field key will be incremented by one.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbinsert(FBUF *fbuf, FLDKEY fldkey, int nth, char *value, int fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to store in the field buffer.

    nth

    Index of the field to store data.

    value

    Pointer to the field data retrieved. If the field key is an integer or real type, use a variable of the appropriate type and cast it according to the function prototype described above.

    fldlen

    Length of data. If the field key type is FB_CARRAY, the length is required. Otherwise, specify '0'.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified. For example, this error occurs if the nth value exceeds the current field count for a CARRAY-type field key.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long rcvlen, ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbinsert(fbuf, INPUT, 0, “aaaa”, 0);
fbinsert (fbuf, INPUT, 1, “bbbb”, 0);
fbinsert (fbuf, INPUT, 2, “cccc”, 0);
...

  • Related Functions

    fbput(), fbchg_tu(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

43. fbisfbuf

The fbisfbuf function is required for allocating memory for a field buffer before saving field data. fbisfbuf() checks the validity of a specified field buffer.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbisfbuf(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to the field buffer to be checked.

  • Return Value

    Value Description

    1

    The specified field buffer is valid.

    0

    The specified field buffer is invalid. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
FBUF *fbuf;
int ret;

if ((fbuf = (FBUF *)tpalloc(“FIELD”, NULL, 0)) == NULL) {
    printf(“tpalloc failed, errno = %d\n”, tperrno);
    ...
}
ret = fbisfbuf(fbuf);
printf(“ret : [%d]\n”, ret); /* output : ret : [1] */
...

  • Related Functions

    fballoc(), tpalloc()

44. fbispres

The fbispres function checks whether field data in a specified field occurrence (nth) exists.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbispres(FBUF *fbuf, FLDKEY fldkey, int nth)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to check if the field data exists in the field buffer.

    nth

    Index of the field to be read.

  • Return Value

    Value Description

    1

    The specified field occurrence contains data.

    0

    The specified field occurrence does not contain data. An error code is set to fberror.

  • Error

    fberrno is set to the following.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h”
...
int ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
ret = fbispres(fbuf, INPUT, 1);
printf(“Field Occ: [%d]\n”, ret); /* output: Field Occ: [1] */
...

  • Related Functions

    fbgetnth(), fbfldcount(), fbkeyoccur()

45. fbkeyoccur

The fbkeyoccur function returns the number of fields of a specified field key. Unlike fbfldcount(), fbkeyoccur() returns the total number of fields, while fbfldcount() returns the number of all currently available fields starting from 1.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbkeyoccur(FBUF *fbuf, FLDKEY fldkey)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to retrieve the count.

  • Return Value

    Value Description

    Number of fields

    Field data exists for the specified field key in the field buffer.

    0

    No field data exists for the specified field key in the field buffer. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h”
...
int cnt;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, OUTPUT, “cccc”, 0);
cnt = fbkeyoccur(fbuf, INPUT);
printf(“Field Count: [%d]\n”, cnt);
/* output: Field Count: [2] */
...

  • Related Functions

    fbgetnth(), fbfldcount()

46. fbmake_fldkey

The fbmake_fldkey function is not defined in a field definition file(*.f). However, it can be used to dynamically create a new field key in the program.

To create a field key, a field type and a unique field number are required. The two can be specified as parameters, and a field key will be generated and returned after executing this function. To create the same field key as an existing field key, specify the already existing number in a field number. To save data in a generated field key and pass the data to another process, the same field key as a generated field key (their type and number should be identical) should be created in the process as well.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
FLDKEY fbmake_fldkey(int type, int no)

  • Parameter

    Parameter Description

    type

    Type of the new field key.

    no

    Field number required to create a field key.

    Input options: FB_CARRAY, FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_INT, FB_FLOAT

  • Return Value

    Creates and returns a new field key created by combining the specified type and number.

  • Example

    #include “demo_fdl.h”
...
FLDKEY fkey;

fkey = fbmake_fldkey(FB_STRING, 101);
printf(“Field Key : [%d]\n”, fkey);
/* output : Field Key : [469762149] */
...

  • Related Functions

    fbget_fldkey()

47. fbnext_tu

The fbnext_tu function returns the next field key and its associated data in a field buffer. Starting from the field key specified in fldkey, the function sequentially returns all field keys and their data in the buffer. To read from the beginning, specify FIRSTFLDKEY as the starting field key.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbnext_tu(FBUF *fbuf, FLDKEY *fldkey, int *nth, char *value, int *len)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Pointer to the field key.

    nth

    Index of the next field occurrence.

    value

    Pointer to the next field data. If not NULL, the next field data is copied. If NULL (when no more data exists), the value remains unchanged while only fldkey and nth are updated.

    len

    Length of the next field data. This parameter verifies whether the buffer has enough space to store the field data. If sufficient, len is set to the length of the next field data.

  • Return Value

    Value Description

    1

    The next field was found. A pointer to the value (fldkey, nth, value, or len) is returned.

    0

    No more fields exist.

    -1

    The function failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...

char data[100];
long rcvlen;
int i, occ, nth, fc, len;

FLDKEY fkey;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbput(fbuf, INPUT, “dddd”, 0);
fbput(fbuf, INPUT, “eeee”, 0);
fbput(fbuf, INPUT, “cccc”, 0);

len = 4;
for(fkey = FIRSTFLDKEY;fc = fbnext_tu(fbuf, &fkey , &occ, data, &len) > 0;

len = sizeof(data))
printf(“fkey = %ld Data: [%s], Occurrence: [%d] len [%d]\n”, fkey, data, occ,
len);

/* output: fkey = 469762149 Data: [aaaa], Occurrence: [0] len [4]
  output: fkey = 469762149 Data: [bbbb], Occurrence: [0] len [4]
  output: fkey = 469762149 Data: [dddd], Occurrence: [0] len [4]
  output: fkey = 469762149 Data: [eeee], Occurrence: [0] len [4]
  output: fkey = 469762149 Data: [cccc], Occurrence: [0] len [4] */
...

  • Related Functions

    fbput(), fbget(), fbgetval(), fbgetvalt(), fbgetval_tu(), fbgetvals_tu(), fbgetvall_tu(), fbgetval_last_tu(), fbgetlast_tu()

48. fbprint

The fbprint function prints out the data in a field buffer in a standard output. It is also used to display the data on the screen.

The output format is as follows.

fkey = 469762149, fname = INPUT, type = string, value = 5555 fkey = 469762149,
fname = INPUT, type = string, value = 7777 fkey = 469762149, fname = INPUT,
type = string, value = 3333 fkey = 469762149, fname = INPUT, type = string,
value = 8888

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbprint(FBUF *fbuf)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

    FBEBADFB

    An invalid field buffer was used. Use another buffer that is correctly allocated to memory.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...

FBUF *fbuf;
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “5555”, 0);
fbput(fbuf, INPUT, “7777”, 0);
fbput(fbuf, INPUT, “3333”, 0);
fbput(fbuf, INPUT, “8888”, 0);

fbprint(fbuf);
...

  • Related Functions

    fbfprintf()

49. fbput

The fbput function adds a new field in a field buffer allocated by fballoc() or tpalloc().

When adding a field to the field key specified by a parameter of the function, if a field does not exist in the field key, a field of the first field sequential number will be created. If one or more fields already exist, a field with an automatically increased sequential number will be created and its value will be saved in the field as field data. Note that the field sequence automatically increases and thus a user does not need to consider sequential numbers to save data.

If a data type of value is char *, but the field type of a field key is not a string, declare a variable appropriate for the field type to save data, and perform type casting to call the function. Even though the prototype is defined as follows, data such as FB_INT, FB_LONG, and FB_FLOAT can be saved by adding a field to a field key.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbput(FBUF *fbuf, FLDKEY fldkey, char *value, FLDLEN len)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of a new field to be created.

    value

    Data to be stored in the new field.

    len

    Length of the data. If the field key type is FB_CARRAY, the length is required. Otherwise, specify '0'.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...

long rcvlen, ret;
FBUF *fbuf;
int ival = 1000;
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INTDATA, (char *)&ival, 0);

  • Related Functions

    fbinsert(), fbchg_tu(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

50. fbputt

The fbputt function adds a new field to a field buffer allocated by fballoc() or tpalloc(). Before adding a field to a field buffer, the user-defined data type of a value is converted into a field key that will be used to save the field.

fbputt() is similar to fbput(). While fbput() saves data into a created field without conversion, fbputt() can convert the data type into the field key type if the data type is different from the field type.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbputt(FBUF *fbuf, FLDKEY fldkey, char *value, FLDLEN len, int type)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key of a new field to be created.

    value

    Data to be stored in the new field.

    len

    Length of value. If the field type is FB_CARRAY, the length is required. Otherwise, specify '0'.

    type

    Field value type. It is converted into field key type before the data is stored in the field.

    Input options: FB_CARRAY, FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_INT, FB_FLOAT

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long rcvlen, ret;
FBUF *fbuf;
int ival;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
ival = 1111;
fbputt(fbuf, INPUT, “aaaa”, 0, FB_STRING);
/* Specify FB_INT to store an int-type value ival (1111) into a string-type INPUT field key. */
fbputt(fbuf, INPUT, (char *)&ival, 0, FB_INT);
...
fbprint(fbuf);
fbfree(fbuf);
...
/* output :    fkey = 469762149, fname = NAME, type = string, value = aaaa
               fkey = 469762149, fname = NAME, type = string, value = 1111  */
...

  • Related Functions

    fbinsert(), fbchg_tu(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

51. fbrealloc

The fbrealloc function re-allocates a field buffer by increasing memory capacity when the size of the buffer is not enough.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
FBUF *fbrealloc(FBUF *fbuf, int ncount, int nlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    ncount

    Number of fields to store data.

    nlen

    Total size of field buffers in bytes.

  • Return Value

    Value Description

    Pointer to memory

    The function call succeeded.

    NULL

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEOS

    A system error occurred, such as an operating system error, memory allocation failure, Tmax connection issue (e.g., service call, send, recv), or unstable network.

    FBEINVAL

    An invalid input parameter was specified. For example, fbuf is set to NULL.

  • Example

    #include “demo_fdl.h“
...
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n“, fberror);
    ...
}
printf(“Buffer Size: [%ld]\n“, fbget_fbsize(fbuf));
/* output: Buffer Size: [1024] */
if ((fbuf = (FBUF *)fbrealloc(fbuf, 1000, 150)) == NULL) {
    printf(“fbrealloc failed, errno = %d\n“, fberror);
    ...
}

printf(“Buffer Size: [%ld]\n”fbget_fbsize(fbuf));
/* output: Buffer Size: [4158] */

  • Related Functions

    fballoc(), tpalloc(), fbget_fbsize(), fbget_used(), fbget_unused()

52. fbread

The fbread function reads data from a specified file stream and loads it in a field buffer. The function reads data from a file stream specified in iop, and loads it in a field buffer allocated by fballoc() or tpalloc().

The file stream used in fbread() should specify a file created by calling fbwrite(). The file is used to load data from another process into a field buffer of the current process.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbread(FBUF *fbuf, FILE *iop)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    iop

    File stream to read data.

  • Return Value

    Value Description

    1

    The function call suceeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

    FBEOS

    A system error occurred, such as an operating system error, memory allocation failure, Tmax connection issue (e.g., service call, send, recv), or unstable network.

  • Example

    #include “demo_fdl.h”
...
int ret;
FILE *iop;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
iop = fopen(“sample.dat”, “r”);
ret = fbread(fbuf, iop);

if (ret == 1)
   fbprint(fbuf);
fclose(iop)
...

  • Related Functions

    fbwrite()

53. fbsnull

The fbsnull function checks whether or not the member variable in a structure mapped to a field sequential number of a specified field key is NULL.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbsnull(char *cstruct, char *cname, int nth, char *stname)

  • Parameter

    Parameter Description

    cstruct

    Casts a structure-type variable to a char* type.

    cname

    Name of the member variable in the structure (string).

    nth

    Index of the field.

    stname

    Name of the structure defined in VIEW (string).

  • Return Value

    Value Description

    1

    The field data at the specified index is NULL.

    0

    The field data at the specified index is not NULL.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEBADSTRUCT

    An invalid structure was used, usually due to an unrecognized type or incorrectly compiled definition file.

    FBENOENT

    No member variable of the structure was found.

  • Example

    #include “demo_fdl.h”
#include “demo_sdl.h”
...
int val = 1000, ret;
struct demo temp;
char *cstruct;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

if(tpstart((TPSTART_T *)NULL) == NULL){
    printf(tpstart error\n”);
    ...
}

cstruct = (char *)&temp;
if(fbstinit(cstruct, “demo”) < 0){
     ...
}

fbput(fbuf, INPUT, “aaaa”, 0);
if(fbftos(fbuf, cstruct, “demo”) < 0){
     ...
}
ret = fbsnull(cstruct, “demodata”, 0, “demo”);
if(ret < 0) {
     printf(“fbsnull failed\n”);
     ...
}
else if(ret == 0)
     printf(“This occurrence is not null\n”);
else
     printf(“This occurrence is null\n”);
...

  • Related Functions

    fbgetlen(), fbstinit(), fbstelinit(), fbinit()

54. fbstelinit

The fbstelinit function initializes the member variables of a structure to NULL. If the data type of a member variable is an integer, it will be initialized to 0, and if the type is a string, it will be initialized to NULL.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbstelinit(char *cstruct, char *cname, char *stname)

  • Parameter

    Parameter Description

    cstruct

    Casts a structure-type variable to a char* type.

    cname

    Name of the member variable in the structure (string), or a char * type.

    stname

    Name of the structure defined in VIEW (string).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to the following code.

    Error Code Description

    FBEBADSTRUCT

    An invalid structure was used, usually due to an unrecognized type or incorrectly compiled definition file.

  • Example

    #include “demo_fdl.h”
#include “demo_sdl.h”
...
cstruct demo temp;
char *cstruct;
if(tpstart((TPSTART_T *)NULL) == NULL) {
     printf(“tpstart failed\n”);
     ...
}
cstruct = (char *)&temp;
if(fbstelinit(cstruct, “demodata”, “demo”) < 0) {
     ...
}
...

  • Related Functions

    fbstinit(), fbinit(), fbsnull()

55. fbstinit

The fbstinit function initializes a specified struct variable. While fbstelinit() properly initializes each member variable in ta specified struct, fbstinit() initializes the whole struct at once. It is recommended to use fbstelinit() to initialize a member variable, and fbstinit() to initialize a structure.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbstinit(char *cstruct, char *stname)

  • Parameter

    Parameter Description

    cstruct

    Casts a structure-type variable to a char* type.

    stname

    Name of the structure defined in VIEW (string).

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEBADSTRUCT

    An invalid structure was used, usually due to an unrecognized type or incorrectly compiled definition file.

  • Example

    #include “demo_fdl.h”
#include “demo_sdl.h”
...
cstruct demo temp;
char *cstruct;
if(tpstart((TPSTART_T *)NULL) == NULL) {
     printf(“tpstart failed\n”);
     ...
}
cstruct = (char *)&temp;
if(fbstinit(cstruct, “demo”) < 0) {
     ...
}
...

  • Related Functions

    fbstelinit(), fbinit(), fbsnull()

56. fbstof

Unlike fbftos(), the fbstof function sends data stored in a C struct buffer(stname) to a matching field buffer. The struct file(VIEW definition file) which is slightly different from general struct files(*.s) should be defined first. The field key within a structure file should be mapped one to one onto a member variable of a structure to be specified. For information about VIEW definition file, refer to fbftos().

In these cases given below, the value in a C structure is not copied into a field buffer with fbstof() which is different from fbftos():

  • When the value in a C structure has the same value as a value specified in the NULL item of a VIEW file.

  • When the value in a C structure field to be copied into a field buffer has the same value as a default value.

This, therefore, means that when copying a value in a C structure using fbftos() without any value stored in a field buffer, the value specified in the NULL item of the VIEW file will be copied. When trying to copy the value in a field buffer using fbftof() without any value stored in a C structure or after saving it with the same value that is specified in a NULL item, it won’t be copied in a field buffer at all.

When trying to copy a value in a C structure using fbftos() without defining a value in the NULL item of a VIEW file and saving the value in a field buffer, a default value will be copied. When trying to copy a value into a field buffer using fbstof() without saving the value in a C structure, or when copying a value after storing the same value as the default value, no value can be copied.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbstof(FBUF *fbuf, char *cstruct, int mode, char *stname)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    cstruct

    Casts a structure-type variable to a char* type.

    mode

    Transmits data to a field buffer. The fbstof() function has functional differences depending on its mode. The modes below work completely the same as the each mode of fbbufop(), so refer to fbbufop().

    The following values can be specified to mode.

    • FBUPDATE : If the FBUPDATE mode is specified, and a member variable of a structure is specified to NULL, the data will be ignored, and will not be transmitted to a field buffer.

    • FBJOIN

    • FBOJOIN

    • FBCONCAT

    stname

    Name of the structure defined in VIEW (string).

  • Return Value

    Value Description

    1

    The function call suceeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEINVAL

    An invalid input parameter was specified.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBEBADSTRUCT

    An invalid structure was used, usually due to an unrecognized type or incorrectly compiled definition file.

    FBEMALLOC

    A system error occurred because memory allocation for field buffers failed.

  • Example

    #include “demo_fdl.h”
#include “demo_sdl.h”
...
int ret, fdllen, val = 1000;
struct demo temp;
FBUF *fbuf;
Char *cstruct;

if(tpstart((TPSTART_T *)NULL) == -1) {
    printf(“tpstart failed\n”);
    ...
}

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

cstruct = (char *)&temp;
if(fbstinit((char *)&temp, “demo”) < 1)  {
    printf(“fbstinit failed, errno = %d\n”, fberror);
    ...
}

strcpy(temp.demodata, “aaaa”);
temp.num = 1000;
if(fbstof(fbuf, cstruct, FBUPDATE, “demo”) < 0) {
...
}
...

  • Related Functions

    fbftof(), fbbufop(), fbstinit(), fbstelinit(), fbsnull()

57. fbstrerror

In the event of a field buffer operation, the fbstrerror function returns error details to a string.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbstrerror(int fberror)

  • Parameter

    Parameter Description

    fberror

    Set when an error occurs in a field buffer API function. The error code is stored in fberror, and its details can be displayed as a string by passing fberror as an input parameter to the function. All possible errors are defined in <fbuf.h>, the FDL-related header file.

  • Return Value

    Value Description

    String

    The function call succeeded. Details for the error is returned in a string.

    NULL

    The function call failed.

  • Example

    #include “demo_fdl.h”
...
int ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

ret = fbget(fbuf, INPUT, “aaaa”, 0);
if( ret < 0 )
    printf(“ret = %d , fberror = %s[%d]\n”, ret, fbstrerror(fberror) , fberror);
/* output : ret = -1, fberror = not found[6] */
...

  • Related Functions

    fberror()

58. fbtypecvt

The fbtypecvt function converts the field data type specified in fromval from fromtype to totype, and then returns the data.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
char *fbtypecvt(FLDLEN *tolen, int totype, char *fromval, int fromtype,
                FLDLEN fromlen)

  • Parameter

    Parameter Description

    tolen

    Pointer to the length of the converted data.

    totype

    Data can be converted into one of the following types: FB_CARRAY,FB_SHORT, FB_DOUBLE, FB_LONG, FB_STRING, FB_CHAR, FB_INT, FB_FLOAT

    fromval

    Pointer to the data to be converted.

    fromtype

    Data type of fromval.

    fromlen

    Default size of the type specified in fromtype.

  • Return Value

    Value Description

    Pointer to the converted data

    The function call succeeded.

    NULL

    The function call failed. An error code is set in fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified. (For FB_CARRAY fields, this error occurs if the length is not specified.)

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBEBADFLD

    An invalid field key was specified, usually because the key was not compiled with the fdlc utility.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
int tolen, totype, fromtype, fromlen;
long vall;
FBUF *fbuf;
char *ptr;

if ((fbuf = fballoc(10, 100)) == NULL) {
      printf(“fballoc failed, errno = %d\n”, fberror);
      ...
}

vall = 1111;
fromlen = sizeof(long);

fbput(fbuf, TOTMON,(char *)&vall, 0);
ptr = fbtypecvt(&tolen, FB_STRING, (char *)&vall, FB_LONG, fromlen);

printf(“Converted string = %s\n”, ptr);
/* output Converted string = 1111 */
...

  • Related Functions

    fbget_fldname(), fbget_fldno(), fbget_fldtype(), fbget_strfldtype()

59. fbupdate

The fbupdate function updates the field value for a field key in a field buffer allocated by the fballoc() or tpalloc() function at a specified position. Generally the function is used to replace the data that was passed from the other processes in a field buffer.

When saving data using the same field key, it is necessary to specify the field key and the field occurrence to update the field value at a specified position. If one field key has several field sequences, the field value of the last defined occurrence will be valid because its data will have been replaced.

The fbupdate() functions works the same as fbchg_tu(). While fbchg_tu() automatically adds a new field and saves data if there is no field occurrences for a specified field key, fbupdate() will experience an error, and FBENOENT will be set to fberror.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbupdate(FBUF *fbuf, FLDKEY fldkey, int nth, char *value, int fldlen)

  • Parameter

    Parameter Description

    fbuf

    Pointer to a field buffer allocated by fballoc() or tpalloc().

    fldkey

    Field key to be changed in a field buffer.

    nth

    Index of the field key to be changed. Also, since the value is a string, INTEGER and REAL data must be converted to CHARACTER type.

    value

    Field value to be replaced. value is a string. INTEGER and REAL data must be converted to CHARACTER type. If value is set to NULL, the corresponding field key is cleared.

    fldlen

    Optional. Note that the length of FB_CARRAY type fields is still required (in bytes).

  • Return Value

    Value Description

    1

    The function call suceeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBENOENT

    The specified field key is not available in the field buffer because it is not defined in the FDL file (default: tmax.fdl, set by environment variable FDLFILE).

    FBENOSPACE

    Insufficient space in the field buffer to store or copy data.

    FBEINVAL

    An invalid input parameter was specified.

    FBETYPE

    An invalid type (unsupported by Tmax) was used.

    FBESETVER

    The version of the specified field buffer does not match the FDL_VERSION setting.

  • Example

    #include “demo_fdl.h”
...
long rcvlen, ret;
FBUF *fbuf;
char buf[20];
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
fbinsert(fbuf, INPUT, 0, “aaaa”, 0);
ret = fbupdate(fbuf, INPUT, 0, “bbbbb”, 0);
fbget (fbuf, INPUT, buf, 0);
printf(“ret = [%d] INPUT = %s \n”, ret, buf);
/* output: “ret = 1 INPUT = bbbbbb” */
...

  • Related Functions

    fbinsert(), fbput(), fbchg_tu(), fbegt(), fbget_tu(), fbgetval(), fbgetval_last_tu(), fbgetvals_tu(), fbgetvall_tu()

60. fbwrite

The fbwrite function stores contents of a field buffer allocated by fballoc() or tpalloc() into the file stream specified in iop.

The data to be stored in a file stream includes binary data. This function is used for passing the data in a field buffer to another process through a file stream. The data stored by the fbwrite() function can also be loaded by the fbread() function.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int fbwrite(FBUF *fbuf, FILE *iop)

  • Parameter

    Parameter Description

    fbuf

    Pointer to the field buffer allocated by fballoc() or tpalloc().

    iop

    Pointer to the file stream to store data.

  • Return Value

    Value Description

    1

    The function call succeeded.

    -1

    The function call failed. An error code is set to fberror.

  • Error

    fberrno is set to one of the following codes.

    Error Code Description

    FBEINVAL

    An invalid input parameter was specified.

    FBEOS

    A system error occurred, such as an operating system error, memory allocation failure, Tmax connection issue (e.g., service call, send, recv), or unstable network.

  • Example

    #include “demo_fdl.h”
...
int ret;
FILE *iop;
FBUF *fbuf;
if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
iop = fopen(“sample.dat”, “w”);
fbput(fbuf, INPUT, “aaaa”, 0);
fbput(fbuf, INPUT, “bbbb”, 0);
fbwrite(fbuf, iop);
fclose(iop)
...

  • Related Functions

    fbread()

61. getfberrno

The getberrono function returns an error code when an error occurrs while performing an API function related to a field buffer. To see the error message of the returned error code, use fbstrerror() with this function as an input parameter. getfberrno() requires no input parameter.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int getfberrno(void)

  • Return Value

    Returns the value specified in fberror.

  • Example

    #include “demo_fdl.h”
...
int ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}

ret = fbget(fbuf, INPUT, “aaaa”, 0);
if( ret < 0 )
    printf(“ret = %d , error = %s[%d]\n”, ret, fbstrerror(getfberrno()) ,
             getfberrno());

/* output : ret = -1, error = not found[6] */
...

  • Related Functions

    fbstrerror(), getfberror()

62. getfberror

The getfgerror function returns an error code when an error occurrs while performing an API function related to a field buffer.

To see the error message of the returned error code, use fbstrerror() with this function as an input parameter. getfberrno() requires no input parameter.

  • Prototype

    #include <fbuf.h>
#include <atmi.h>
int getfberror(void)

  • Return Value

    Returns the value specified in fberror.

  • Example

    #include “demo_fdl.h”
...
int ret;
FBUF *fbuf;

if ((fbuf = fballoc(10, 100)) == NULL) {
    printf(“fballoc failed, errno = %d\n”, fberror);
    ...
}
ret = fbget(fbuf, INPUT, “aaaa”, 0);
if( ret < 0 )
    printf(“ret = %d , error = %s[%d]\n”, ret, fbstrerror(getfberror()) ,
            getfberror());
/* output : ret = -1, error = not found[6] */
...

  • Related Functions

    fbstrerror(), getfberror()