Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPADVERTISE(3cbl)

Name

TPADVERTISE() - routine for advertising service names

Synopsis

01 SVC-NAMEPIC X(15). 01PROGRAM-NAMEPIC X(32). 01TPSTATUS-REC. COPY TPSTATUS. CALL "TPADVERTISE" USINGSVC-NAME PROGRAM-NAME TPSTATUS-REC.

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 shut down.

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 SVC-NAME for the server (or the set of servers sharing the caller's MSSQ set). SVC-NAME should be 15 characters or less, but cannot be SPACES. (See SERVICES section of UBBCONFIG(5).) Longer names are truncated to 15 characters. Users should make sure that truncated names do not match other service names. PROGRAM-NAME is the name of a BEA Tuxedo ATMI service program. This program will be invoked whenever a request for SVC-NAME is received by the server. PROGRAM-NAME cannot be SPACES.

If SVC-NAME is already advertised for the server and PROGRAM-NAME matches its current program, then TPADVERTISE() returns success (this includes truncated names that match already advertised names). However, if SVC-NAME is already advertised for the server but PROGRAM-NAME does not match its current program, then an error is returned (this can happen if truncated names match already advertised names).

Return Values

TPADVERTISE() Upon successful completion, TPADVERTISE() sets TP-STATUS to [TPOK].

Errors

Under the following conditions, TPADVERTISE() fails and sets TP-STATUS to:

[TPEINVAL]

Either SVC-NAME or PROGRAM-NAME is SPACES, or PROGRAM-NAME is not a name of a valid program.

[TPELIMIT]

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

[TPEMATCH]

SVC-NAME is already advertised for the server but with a program other than PROGRAM-NAME. Although TPADVERTISE() fails, SVC-NAME remains advertised with its current program (that is, PROGRAM-NAME does not replace the current program).

[TPEPROTO]

TPADVERTISE() was called improperly.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Portability

On AIX on the RS6000, any services provided in the first COBOL object file are not available in the symbol table; their names must be specified using the -s option on the buildserver command so that they can be advertised at run time using TPADVERTISE().