Section 3c - C Functions

e-docs > Tuxedo > ATMI C Function Reference > Section 3c - C Functions

ATMI C Function Reference

tpadvertise(3c)

Name

tpadvertise()—Routine for advertising a service name.

Synopsis

#include <atmi.h>
int tpadvertise(char *svcname, void (*func)(TPSVCINFO *))

Description

tpadvertise() allows a server to advertise the services that it offers. By default, a server's services are advertised when it is booted and unadvertised when it is shutdown.

All servers belonging to a Multiple Server, Single Queue (MSSQ) set must offer the same set of services. These routines enforce this rule by affecting the advertisements of all servers sharing an MSSQ set.

tpadvertise() advertises svcname for the server (or the set of servers sharing the caller's MSSQ set). svcname should be 15 characters or less, but cannot be NULL or the NULL string (""). (See *SERVICES section of UBBCONFIG(5).)func is the address of a BEA Tuxedo ATMI system service function. This function will be invoked whenever a request for svcname is received by the server. func cannot be NULL. Explicitly specified function names (see servopts(5)) can be up to 128 characters long. Names longer than 15 characters are accepted and truncated to 15 characters. Users should make sure that truncated names do not match other service names.

If svcname is already advertised for the server and func matches its current function, then tpadvertise() returns success (this includes truncated names that match already advertised names). However, if svcname is already advertised for the server but func does not match its current function, then an error is returned (this can happen if truncated names match already advertised names).

Service names starting with dot (.) are reserved for administrative services. An error will be returned if an application attempts to advertise one of these services.

Return Values

Upon failure, tpadvertise() returns -1 and sets tperrno to indicate the error condition.

Errors

Upon failure, tpadvertise() sets tperrno to one of the following values:

[TPEINVAL]

svcname is NULL or the NULL string (""),or begins with a "." or func is NULL.

[TPELIMIT]

svcname cannot be advertised because of space limitations. (See MAXSERVICES in the RESOURCES section of UBBCONFIG(5).)

[TPEMATCH]

svcname is already advertised for the server but with a function other than func. Although the function fails, svcname remains advertised with its current function (that is, func does not replace the current function).

[TPEPROTO]

tpadvertise() was called in an improper context (for example, by a client).