Diagnostics

There are two general types of errors that may be returned to the user when interfacing with WS_MIB(5). First, any of the three ATMI verbs (tpcall(), tpgetrply() and tpdequeue()) used to retrieve responses to administrative requests may return any error defined for them. These errors should be interpreted as described on the appropriate reference pages.

When a service failure occurs during processing of an administrative request, the FML32 field TA_STATUS is set to a textual description of the failure, the FML32 field TA_ERROR is set to indicate the cause of the failure as indicated below. All error codes specified below are guaranteed to be negative.

The following diagnostic codes are returned in TA_ERROR to indicate successful completion of an administrative request. These codes are guaranteed to be non-negative.

Interoperability

The header files and field tables defined in this reference page are available on BEA Tuxedo release 5.0 and later. Fields defined in these headers and tables will not be changed from release to release. New fields may be added which are not defined on the older release site. Access to the AdminAPI is available from any site with the header files and field tables necessary to build a request. The T_WSL and T_WSH classes are new with BEA Tuxedo system release 6.0; therefore, local administration of WSL and WSH processes on earlier release sites via the AdminAPI is not available. However, many of the administrative actions defined in this reference page are available for pre-release 6.0 sites if they are interoperating with a release 6.0 site. If sites of differing releases, both greater than or equal to release 6.0, are interoperating, information on the older site is available for access and update as defined in the MIB reference page for that release and may be a subset of the information available in the later release.

Portability

The existing FML32 and ATMI functions necessary to support administrative interaction with BEA Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and Workstation platforms.

Example

Field Tables

The field table tpadm must be available in the environment to have access to attribute field identifiers. This can be done at the shell level as follows:

$ FIELDTBLS=tpadm
$ FLDTBLDIR=${TUXDIR}/udataobj
$ export FIELDTBLS FLDTBLDIR

Header Files

The following header files are included.

#include <atmi.h> 
#include <fml32.h>
#include <tpadm.h>

Suspend Workstation Group

The following code fragment sets the state of the Workstation group to SUSpended. This disables the Workstation group from accepting new connections from Workstation clients and suspends all Workstation clients that are currently part of the group. This code fragment and those that follow assume that the local variables ta_srvgrp and ta_srvid are already set to identify the Workstation group with which we are working.

/* Allocate input and output buffers */ ibuf = tpalloc("FML32", NULL, 1000);
 obuf = tpalloc("FML32", NULL, 1000);
 /* Set MIB(5) attributes defining request type */
 Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
 Fchg32(ibuf, TA_CLASS, 0, "T_WSL", 0);
 /* Set WS_MIB(5) attributes */
 Fchg32(ibuf, TA_SRVGRP, 0, ta_srvgrp, 0);
 Fchg32(ibuf, TA_SRVID, 0, (char *)ta_srvid, 0);
 Fchg32(ibuf, TA_SUSPENDED, 0, "ALL", 0);
 /* Make the request */
 if (tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0) 0) {
 fprintf(stderr, "tpcall failed: %s\en", tpstrerror(tperrno));
 if (tperrno == TPESVCFAIL) {
 Fget32(obuf, TA_ERROR, 0,(char *)ta_error, NULL);
 ta_status = Ffind32(obuf, TA_STATUS, 0, NULL);
 fprintf(stderr, "Failure: %ld, %s\en",
 ta_error, ta_status);
 }
 /* Additional error case processing */
 }
 /* Copy the logical machine identifier for later use */
 strcpy(ta_lmid, Ffind32(obuf, TA_LMID, 0, NULL));

Get List of WSH Objects

Using the existing input buffer, simply change the class and operation and make a new request. We'll retrieve all T_WSH objects associated with the given T_WSL object key fields, ta_srvgrp and ta_srvid. Set the TA_FILTER attribute to limit the retrieval for efficiency.

/* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_CLASS, 0, "T_WSH", 0);
 Fchg32(ibuf, TA_OPERATION, 0, "GET", 0);
 longval = TA_WSHCLIENTID;
 Fchg32(ibuf, TA_FILTER, 0, (char *)longval, 0);
 /* Set WS_MIB(5) attributes */
 Fchg32(ibuf, TA_LMID, 0, ta_lmid, 0);
 /* Allocate a separate output buffer to save the TA_WSHCLIENTID values */
 wshcltids = tpalloc("FML32", NULL, 1000);
 /* Make the request */
 tpcall(".TMIB", (char *)ibuf, 0, (char **)wshcltids, olen, 0);
 /* See how many we got */
 Fget32(wshcltids, TA_OCCURS, 0,(char *)wshcltcnt, NULL);

Get T_CLIENT Objects

Use the retrieved TA_WSHCLIENTID values to get a list of associated TA_CLIENTID values for Workstation clients in this Workstation group.

/* Initialize request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
 /* Set MIB(5) attributes defining request type */
 Fchg32(ibuf, TA_OPERATION, 0, "GET", 0);
 Fchg32(ibuf, TA_CLASS, 0, "T_CLIENT", 0);
 longval = TA_CLIENTID;
 Fchg32(ibuf, TA_FILTER, 0, (char *)longval, 0);
 longval = TA_WSHCLIENTID;
 Fchg32(ibuf, TA_FILTER, 1, (char *)longval, 0);
 /* Set WS_MIB(5) attributes */
 Fchg32(ibuf, TA_LMID, 0, ta_lmid, 0);
 Fchg32(ibuf, TA_WSC, 0, "Y", 0);
 if (wshcltcnt == 1) {
 /* Since only 1, use it as key field. */
 Fchg32(ibuf, TA_WSHCLIENTID, 0,
 Ffind32(wshcltids, TA_WSHCLIENTID, 0, NULL));
 }
 /* Allocate output buffer to save TA_CLIENTID/TA_WSHCLIENTID values */
 cltids = tpalloc("FML32", NULL, 1000);
 /* Make the request */
 tpcall(".TMIB", (char *)ibuf, 0, (char **)cltids, olen, 0);
 /* See how many we got */
 Fget32(cltids, TA_OCCURS, 0,(char *)cltcnt, NULL);
 /* Eliminate unassociated clients if necessary */
 if (wshcltcnt > 1) {
 for (i=(cltcnt-1); i >= 0 ;i--) {
 p = Ffind32(cltids, TA_WSHCLIENTID, i, NULL);
 for (j=0; j wshcltcnt ;j++) {
 q = Ffind32(wshcltids, TA_WSHCLIENTID, j, NULL);
 if (strcmp(p, q) == 0) {
 break; /* This client is in our group */
 }
 }
 if (j >= wshcltcnt) {
 /* Client not found, delete it from list */
 Fdel32(cltids, TA_CLIENTID, i);
 Fdel32(cltids, TA_WSHCLIENTID, i);
 cltcnt--;
 }
 }
 }

Notify T_CLIENT Objects

Use the retrieved TA_CLIENTID values to notify Workstation clients in this Workstation group that they should log off.

notstr = tpalloc("STRING", NULL, 100);
(void)strcpy(notstr, "Please logoff now!"); 
 
/* Now loop through affected clients and suspend/notify them */ 
for (i=0; i cltcnt ;i++) { 
  p = Ffind32(cltids, TA_CLIENTID, i, NULL); 
 
  /* Notify the client to logoff */ 
  tpconvert(p, (char *)ci, TPCONVCLTID); 
  tpnotify(ci, notptr, 0, 0); 
}

Deactivate Remaining T_CLIENT Objects

Use the retrieved TA_CLIENTID values to deactivate any remaining Workstation clients in this Workstation group. Note that those that are already gone will return an error on the SET that we will ignore.

/* Initialize request buffer */ 
Finit32(ibuf, Fsizeof32(ibuf)); 
/* Set MIB(5) attributes defining request type */ 
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); 
Fchg32(ibuf, TA_CLASS, 0, "T_CLIENT", 0); 
Fchg32(ibuf, TA_STATE, 0, "DEAd", 0); 
 
/* Now loop through affected clients and deactivate them */ 
for (i=0; i cltcnt ;i++) { 
  p = Ffind32(cltids, TA_CLIENTID, i, NULL); 
  Fchg32(ibuf, TA_CLIENTID, 0, p); 
 
  /* Make the request */ 
  tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0); 
}

Deactivate T_WSL Object

Now deactivate the T_WSL object. This will automatically deactivate any associated active T_WSH objects.

/* Set MIB(5) attributes defining request type */ 
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); 
Fchg32(ibuf, TA_CLASS, 0, "T_WSL", 0); 
Fchg32(ibuf, TA_STATE, 0, "INActive", 0); 
 
/* Set WS_MIB(5) attributes */ 
Fchg32(ibuf, TA_SRVGRP, 0, ta_srvgrp, 0); 
Fchg32(ibuf, TA_SRVID, 0, (char *)ta_srvid, 0); 
 
/* Make the request */ 
tpcall(".TMIB", (char *)ibuf, 0, (char **)obuf, olen, 0);
}

Files

${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm

See Also

Setting Up a BEA Tuxedo Application

Administering a BEA Tuxedo Application at Run Time

Programming a BEA Tuxedo ATMI Application Using C

Programming a BEA Tuxedo ATMI Application Using FML

WSL(5)

Name

WSL—Workstation Listener server

Synopsis

WSL SRVGRP="identifier" 
  SRVID="number" 
  CLOPT="[-A] [servopts options] -- -n netaddr [-d device]
      [-w WSHname] [-t timeout-factor] [-T Client-timeout]
      [-m minh] [-M maxh] [-x mpx-factor]
      [-p minwshport] [-P maxwshport] [-I init-timeout]
      [-c compression-threshold] [-k compression-threshold] 
      [-K {client|handler|both|none}]
      [-z bits] [-Z bits] [-H external-netaddr][-N network-timeout]"

Description

The workstation listener is a BEA Tuxedo system-supplied server that enables access to native services by Workstation clients. The application administrator enables workstation access to the application by specifying the workstation listener server as an application server in the SERVERS section. The associated command-line options are used to parameterize the processing of the workstation listener and workstation handlers.

The location, server group, server ID, and other generic server related parameters are associated with the workstation listener using the already defined configuration file mechanisms for servers. Workstation listener specific command-line options are specified to allow for customization.

Each WSL booted as part of an application facilitates application access for a large number of Workstation clients by providing access via a single well known network address to a set of workstation handlers (WSHs) acting as surrogate clients for the users running on the workstations. The WSHs are started and stopped dynamically by the WSL as necessary to meet the incoming load from the application workstations. The advantages to the application administrator are that a small number of native site processes (WSHs) can support a much larger number of clients, thus reducing the process count on the native site, and that the native site does not need to incur the overhead of maintaining bulletin board information on the workstation sites, which may be quite numerous.

The following WSL-specific command-line options are available and may be listed after the double-dash (--) in the CLOPT parameter.

Any configuration that prevents the WSL from supporting Workstation clients will cause the WSL to fail at boot time, for example, if the MAXWSCLIENTS value for the site is 0.

Portability

WSL is supported as a BEA Tuxedo system-supplied server on all supported server platforms.

Interoperability

WSL may be run in an interoperating application, but it must run on a BEA Tuxedo release 4.2 or later node.

Examples

*SERVERS 
WSL SRVGRP="WSLGRP" SRVID=1000 RESTART=Y GRACE=0 
  CLOPT="-A -- -n 0x0002ffffaaaaaaaa -d /dev/tcp" 
WSL SRVGRP="WSLGRP" SRVID=1001 RESTART=Y GRACE=0 
  CLOPT="-A -- -n 0x0002aaaaffffffff -d /dev/tcp -H 0x0002MMMMdddddddd" 
WSL SRVGRP="WSLGRP" SRVID=1002 RESTART=Y GRACE=0 
  CLOPT="-A -- -n //hostname:aaaa -d /dev/tcp -H //external_hostname:MMMM"

See Also

Setting Up a BEA Tuxedo Application

Administering a BEA Tuxedo Application at Run Time

Programming a BEA Tuxedo ATMI Application Using C