Fuxedo logotpadvertise()

advertise a service at runtime (server only)

Synopsis

#include <atmi.h>

int tpadvertise(char *svcname,
                  void (*func)(TPSVCINFO *));

Description

tpadvertise() binds a service name to a service function so requests start arriving at this server. It is the runtime equivalent of the buildserver() -s table and the usual content of tpsvrinit(); it can also be called later to switch a name to a different implementation.

Arguments

ArgumentDescription
svcnameThe service name to advertise.
funcThe function that handles it, with the TPSVCINFO signature.

Errors (tperrno)

CodeDescription
TPELIMITThe service table is full (MAXSERVICES).
TPEINVALsvcname or func is invalid.
TPESYSTEMPlatform failure.

Example

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

// Server lifecycle examples: tpsvrinit/tpsvrdone, the per-dispatch
// thread pair, runtime advertising, and tpreturn. Booted without -s
// advertisements; everything is advertised from tpsvrinit().

#include <stdio.h>
#include <string.h>
#include <atmi.h>
#include <userlog.h>

void GREET(TPSVCINFO *svcinfo) {
  // tpreturn ends the call: TPSUCCESS delivers data as the reply,
  // TPFAIL reports an application failure (tpurcode carries rcode),
  // TPEXIT ends the call and takes the server down
  tpreturn(TPSUCCESS, 0, svcinfo->data, 0, 0);
}

int tpsvrthrinit(int argc, char **argv) {
  // called once per dispatch thread, before it takes requests
  return 0;
}

void tpsvrthrdone() {
  // called when a dispatch thread exits
}

int tpsvrinit(int argc, char **argv) {
  // called once at boot, before the server takes requests: advertise
  // the services this server implements. Functions must be declared at
  // buildserver time; runtime advertising binds names to them
  if (tpadvertise((char *)"GREETX", GREET) == -1) {
    return -1;
  }
  // tpadvertisex (re)binds a name to a function with extended
  // placement flags (0 = plain); here it takes over the buildserver
  // -s advertisement of GREET
  if (tpadvertisex((char *)"GREET", GREET, 0) == -1) {
    return -1;
  }
  return 0;
}

void tpsvrdone() {
  // called once at orderly shutdown; withdraw the extra advertisement
  tpunadvertise((char *)"GREETX");
  userlog("advsvr done");
}

See also: tpunadvertise, tpadvertisex, tpsvrinit.

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