Advertising and Unadvertising Services


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Programming \| Topic List \| Previous \| Next \| Contents

Programming a BEA Tuxedo Application Using COBOL

When a server is booted, it advertises the services it offers based on the values specified for the CLOPT parameter in the configuration file.

Note: The services that a server may advertise are initially defined when the buildserver command is executed. The -s option allows a comma-separated list of services to be specified. It also allows you to specify a routine with a name that differs from that of the advertised service that is to be called to process the service request. Refer to the buildserver(1) in the BEA Tuxedo Command Reference for more information.

The default specification calls for the server to advertise all services with which it was built. Refer to the UBBCONFIG(5) or servopts(5) reference page in the BEA Tuxedo File Formats and Data Descriptions Reference for more information.

Because an advertised service uses a service table entry in the bulletin board, and can therefore be resource-expensive, an application may boot its servers in such a way that only a subset of the services offered are available. To limit the services available in an application, define the CLOPT parameter, within the appropriate entry in the SERVERS section of the configuration file, to include the desired services in a comma-separated list following the -s option. The -s option also allows you to specify a routine with a name other than that of the advertised service to be called to process the request. Refer to the servopts(5) reference page in the BEA Tuxedo File Formats and Data Descriptions Reference for more information.

A BEA Tuxedo application administrator can use the advertise and unadvertise commands of tmadmin(1) to control the services offered by servers. The TPADVERTISE and TPUNADVERTISE routines enable you to dynamically control the advertisement of a service in a request/response or conversational server. The service to be advertised (or unadvertised) must be available within the same server as the service making the request.

Advertising Services

Use the following signature to call the TPADVERTISE(3cbl) routine.

01 SERVICE-NAME           PIC X(15).
01 PROGRAM-NAME           PIC X(32).
01 TPSTATUS-REC.
    COPY TPSTATUS.
CALL "TPADVERTISE" USING SERVICE-NAME PROGRAM-NAME TPSTATUS-REC.

The following table describes the members of a TPADVERTISE data structure.

TPADVERTISE Data Structure Members

Member
Description

SERVICE-NAME

Name of the service to be advertised. The service name must be a character string of up to 15 characters. Names longer than 15 characters are truncated. The SPACES string is not a valid value. If it is specified, an error (TPEINVAL) results.

PROGRAM-NAME

BEA Tuxedo system routine that is called to perform a service. Frequently, this name is the same as the name of the service. The SPACES string is not a valid value. If it is specified, an error results.

Member	Description
SERVICE-NAME	Name of the service to be advertised. The service name must be a character string of up to 15 characters. Names longer than 15 characters are truncated. The SPACES string is not a valid value. If it is specified, an error (TPEINVAL) results.
PROGRAM-NAME	BEA Tuxedo system routine that is called to perform a service. Frequently, this name is the same as the name of the service. The SPACES string is not a valid value. If it is specified, an error results.

Unadvertising Services

The TPUNADVERTISE(3cbl) routine removes the name of a service from the service table of the bulletin board so that the service is no longer advertised.

Use the following signature for the TPUNADVERTISE routine.

01 SERVICE-NAME           PIC X(15).
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPUNADVERTISE" USING SERVICE-NAME TPSTATUS-REC.

The TPUNADVERTISE data structure contains one member, which is described in the following table.

TPUNADVERTISE Data Structure Member

Member
Description

SERVICE-NAME

Name of the service to be advertised. The service name must be a character string of up to 15 characters. Names longer than 15 characters are truncated. The SPACES string is not a valid value. If it is specified, an error (TPEINVAL) results.

Member	Description
SERVICE-NAME	Name of the service to be advertised. The service name must be a character string of up to 15 characters. Names longer than 15 characters are truncated. The SPACES string is not a valid value. If it is specified, an error (TPEINVAL) results.

Example: Dynamic Advertising and Unadvertising of a Service

The following example shows how to use the TPADVERTISE routine. In this example, a server called TLR is programmed to offer only the service called TLRINIT when booted. After some initialization, TLRINIT advertises two services called DEPOSIT and WITHDRAW. Both are performed by the TLRFUNCS routine, and both are built into the TLR server.

After advertising DEPOSIT and WITHDRAW, TLRINIT unadvertises itself.

Dynamic Advertising and Unadvertising

    . . .
**************************************************
* Advertise DEPOSIT service to be processed by
* routine TLRFUNCS
**************************************************
    MOVE "DEPOSIT" TO SERVICE-NAME.
    MOVE "TLRFUNCS" TO PROGRAM-NAME.
    CALL "TPADVERTISE" USING SERVICE-NAME
                       PROGRAM-REC
                       TPSTATUS-REC.
    IF NOT TPOK
           error processing
**************************************************
* Advertise WITHDRAW service to be processed by
* the same routine TLRFUNCS
**************************************************
    MOVE "WITHDRAW" TO SERVICE-NAME.
    MOVE "TLRFUNCS" TO PROGRAM-NAME.
    CALL "TPADVERTISE" USING SERVICE-NAME
                       PROGRAM-REC
                       TPSTATUS-REC.
    IF NOT TPOK
           error processing
**************************************************
* Unadvertise TLRINIT service  (yourself)
**************************************************
    MOVE "TLRINIT" TO SERVICE-NAME.
    CALL "TPUNADVERTISE" USING SERVICE-NAME
                         TPSTATUS-REC.
    IF NOT TPOK
            error processing