Fuxedo logoFchg32()

change a field occurrence (the Swiss Army knife)

Synopsis

#include <fml32.h>

int Fchg32(FBFR32 *fbfr, FLDID32 fieldid,
           FLDOCC32 oc, char *value, FLDLEN32 len);

Description

Fchg32() replaces the value of one occurrence, and with three edges it covers the write half of the whole API. First, with occurrence -1 it behaves exactly like Fadd32() and appends. Second, changing an occurrence beyond the current count pads the intermediate occurrences with default values (0 for numeric fields). Third, passing NULL as the value deletes that occurrence, like Fdel32().

Read together: Fchg32(buf, id, -1, ...) appends, Fchg32(buf, id, n, ...) sets, Fchg32(buf, id, n, NULL, ...) deletes, so most programs need nothing else for field writes.

Arguments

ArgumentDescription
fbfrThe FML32 buffer.
fieldidThe field to change.
ocZero-based occurrence; -1 appends.
value, lenNew value; NULL deletes the occurrence.

Errors (tperrno)

CodeDescription
FEINVALBad field id or length.
FNOSPACENo room for a padded append; see Fneeded32().
FNOTFLDfbfr is not an FML32 buffer.

Notes

These three behaviors are demonstrated with runnable programs in the Fchg32 post on the author's blog.

Example

Full source: docs/api/examples/fmldemo.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the lines documenting Fchg32() are highlighted.

// FML32 API examples: the API pages highlight the lines of each
// documented function. The field identifiers come from the "demo"
// field table via mkfldhdr32 (see the Makefile). Run inside the
// sample domain: FLDTBLDIR32=. FIELDTBLS32=demo

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <atmi.h>
#include <fml32.h>
#include "demo.h"

static int fmlfail(const char *what) {
  // Ferror32 holds the code of the last failed FML32 call; it is not
  // cleared by success, so read it only after a -1/NULL return
  int code = Ferror32;
  // Fstrerror32 renders an FML32 error code as text
  fprintf(stderr, "%s failed: %s (%d)\n", what, Fstrerror32(code), code);
  return 1;
}

int main(void) {
  FBFR32 *fb = (FBFR32 *)tpalloc((char *)"FML32", NULL, 1024);
  if (fb == NULL) {
    fprintf(stderr, "tpalloc failed: tperrno=%d\n", tperrno);
    return 1;
  }

  // Fadd32 appends a new occurrence; len 0 lets a string field measure
  // itself
  if (Fadd32(fb, FIRSTNAME, (char *)"Ada", 0) == -1) {
    return fmlfail("Fadd32 FIRSTNAME");
  }
  if (Fadd32(fb, LASTNAME, (char *)"Lovelace", 0) == -1) {
    return fmlfail("Fadd32 LASTNAME");
  }
  long amount = 100;
  if (Fadd32(fb, AMOUNT, (char *)&amount, 0) == -1) {
    return fmlfail("Fadd32 AMOUNT");
  }
  // the same append can be written with Fchg32 and oc -1
  if (Fadd32(fb, FIRSTNAME, (char *)"Grace", 0) == -1) {
    return fmlfail("Fadd32 FIRSTNAME #2");
  }

  // Fchg32 replaces the value at one occurrence...
  long big = 500;
  if (Fchg32(fb, AMOUNT, 0, (char *)&big, 0) == -1) {
    return fmlfail("Fchg32 AMOUNT");
  }
  // ...appends a new occurrence with oc -1 (like Fadd32)...
  if (Fchg32(fb, AMOUNT, -1, (char *)&big, 0) == -1) {
    return fmlfail("Fchg32 AMOUNT append");
  }
  // ...pads skipped occurrences with default values, and deletes the
  // occurrence when value is NULL
  if (Fchg32(fb, AMOUNT, 0, NULL, 0) == -1) {
    return fmlfail("Fchg32 AMOUNT delete");
  }

  long got = 0;
  if (Fget32(fb, AMOUNT, 0, (char *)&got, 0) == -1) {
    return fmlfail("Fget32 AMOUNT");
  }
  printf("AMOUNT[0]=%ld\n", got);

  // Fnext32 walks the buffer in field order; FIRSTFLDID starts the walk
  FLDID32 id = FIRSTFLDID;
  FLDOCC32 oc = 0;
  char value[128];
  FLDLEN32 vlen = sizeof(value);
  printf("fields:\n");
  while (true) {
    vlen = sizeof(value);  // len is in/out: Fnext32 reports the copy
    if (Fnext32(fb, &id, &oc, value, &vlen) != 1) {
      break;  // 0 = no more fields, -1 = error (Ferror32)
    }
    printf("  field=%u oc=%d\n", id, oc);
  }

  // the expression is compiled once and evaluated against the buffer
  // Fboolco32 compiles the expression into a tree; field names are
  // resolved through the loaded field tables
  char *tree = Fboolco32((char *)"AMOUNT > 200");
  if (tree == NULL) {
    return fmlfail("Fboolco32");
  }
  int match = Fboolev32(fb, tree);
  if (match == -1) {
    return fmlfail("Fboolev32");
  }
  printf("AMOUNT > 200: %s\n", match ? "true" : "false");

  // Fboolpr32 prints the parsed expression tree
  Fboolpr32(tree, stdout);

  free(tree);

  // Flen32 is the stored length of one occurrence
  long len0 = Flen32(fb, FIRSTNAME, 0);
  if (len0 == -1) {
    return fmlfail("Flen32");
  }
  printf("FIRSTNAME[0] len=%ld\n", len0);

  // Fsizeof32 is the whole buffer size; Fneeded32 sizes an addition
  long used = Fsizeof32(fb);
  long need = Fneeded32(3, 32);
  printf("sizeof=%ld needed=%ld\n", used, need);

  // Fwrite32/Fread32 move a buffer to and from a FILE
  FILE *out = fopen("demo.fml", "w");
  if (out == NULL || Fwrite32(fb, out) == -1) {
    return fmlfail("Fwrite32");
  }
  fclose(out);

  FBFR32 *copy = (FBFR32 *)tpalloc((char *)"FML32", NULL, 1024);
  FILE *in = fopen("demo.fml", "r");
  if (copy == NULL || in == NULL || Fread32(copy, in) == -1) {
    return fmlfail("Fread32");
  }
  fclose(in);

  // Fprint32 prints the buffer to stdout; Ffprint32 takes a FILE
  if (Fprint32(copy) == -1) {
    return fmlfail("Fprint32");
  }

  // Ffprint32 prints the same form to any FILE destination
  if (Ffprint32(copy, stdout) == -1) {
    return fmlfail("Ffprint32");
  }

  // Fdel32 removes one occurrence; oc -1 removes them all
  if (Fdel32(fb, FIRSTNAME, 1) == -1) {
    return fmlfail("Fdel32");
  }

  tpfree((char *)fb);
  tpfree((char *)copy);
  return 0;
}

See also: Fadd32, Fget32, Fdel32.

fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.