advertise a service with placement flags
#include <atmi.h>
int tpadvertisex(char *svcname,
void (*func)(TPSVCINFO *),
long flags);
tpadvertisex() is tpadvertise() with placement control, and the
flags are the point of the call. flags=0 behaves exactly like
tpadvertise(): the name binds to the function on the
server's main request queue, replacing the binding when the name is
already advertised on this server with the same function. The other
combinations move the advertisement or guard it:
| Argument | Description |
|---|---|
| svcname | The service name. |
| func | The handler function, declared with buildserver -s. |
| flags | 0, TPSINGLETON, TPSECONDARYRQ, or both ORed. |
| Flag | Description |
|---|---|
| 0 | Plain advertisement on the main request queue, like tpadvertise(). |
| TPSINGLETON | Advertise on the main queue and require the name to be unique in the application: when another server already advertises it, the call fails with TPENOSINGLETON. |
| TPSECONDARYRQ | Advertise on the server's secondary request queue, which requires SECONDARYRQ=Y in the server configuration; otherwise the call fails with TPENOSECONDARYRQ. Multiple servers may advertise the same name this way. |
| TPSINGLETON | TPSECONDARYRQ | Both: the secondary-queue placement plus the uniqueness check, so either TPENOSECONDARYRQ or TPENOSINGLETON can fail the call. |
| Code | Description |
|---|---|
| TPENOSINGLETON | TPSINGLETON was set and another server already advertises the name. |
| TPENOSECONDARYRQ | TPSECONDARYRQ was set and the server is not booted with SECONDARYRQ=Y. |
| TPEMATCH | The name is advertised on this server with a different function. |
| TPELIMIT | The service table is full. |
| TPEINVAL | Invalid name, function, or flags. |
| TPESYSTEM | Platform failure. |
Services on the secondary queue show up in the MIB with
TA_RQADDR=UNKNOWN, which distinguishes them from
main-queue advertisements. The four flag combinations were mapped out
in the
tpadvertisex post on the author's blog; Oracle's own documentation
of the flags is thin.
Full source: docs/api/examples/advsvr.c
(build and run with make -C docs/api/examples check
TUXDIR=<install>); the lines documenting tpadvertisex() 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: tpadvertise, tpunadvertise.
fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.