BEA Logo BEA Tuxedo Release 7.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo File Formats and Data Descriptions Reference

WS_MIB(5)

Name

WS_MIB - Management Information Base for Workstation

Synopsis

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

Description

The BEA Tuxedo system MIB defines the set of classes through which a Workstation group (one WSL and its associated WSH processes) may be managed.

WS_MIB(5) should be used in combination with the generic MIB reference page MIB(5) to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5) using classes and attributes described in this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. WS_MIB(5) consists of the following classes.

WS_MIB Classes

Class Name

Attributes

T_WSH

Workstation Handler

T_WSL

Workstation Listener

Each class description section has four subsections:

Overview

High level description of the attributes associated with the class.

Attribute Table

A table that lists the name, type, permissions, values and default for each attribute in the class. The format of the attribute table is described below.

Attribute Semantics

Tells how each attribute should be interpreted.

Limitations

Limitations in the access to and interpretation of this class.

Attribute Table Format

As described above, each class that is a part of this MIB is defined below in four parts. One of these parts is the attribute table. The attribute table is a one-page reference guide to the attributes within a class and how they may used by administrator's, operator's and general user's to interface with an application. There are five components to each attribute description in the attribute tables; name, type, permissions, values and default. Each of these components is discussed in MIB(5).

TA_FLAGS Values

MIB(5) defines the generic TA_FLAGS attribute which is a long valued field containing both generic and component MIB specific flag values. At this time, there are no WS_MIB(5) specific flag values defined.

FML32 Field Tables

The field tables for the attributes described in this reference page are found in the file udataobj/tpadm relative to the root directory of the BEA Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj should be included by the application in the colon separated list specified by the FLDTBLDIR environment variable and the field table name tpadm should be included in the comma separated list specified by the FIELDTBLS environment variable.

Limitations

Access to the header files and field tables for this MIB is being provided only on BEA Tuxedo system 6.0 sites and later, both native and Workstation.

T_WSH Class Definition

Overview

The T_WSH class represents run-time attributes of WSH client processes. These attribute values characterize Workstation statistics specific to a particular WSH client process. This class is linked to the T_WSL class by the common key fields, TA_SRVGRP and TA_SRVID. It is also linked to the T_CLIENT class (see TM_MIB(5)) by the common key field TA_WSHCLIENTID.

Attribute Table

WS_MIB(5): T_WSH Class Definition Attribute Table

Attribute1

Type

Permissions

Values

Default

TA_CLIENTID(*)

string

R--R--R--

string[1..78]

N/A

TA_WSHCLIENTID(*)

string

R--R--R--

string[1..78]

N/A

TA_SRVGRP(*)

string

R--R--R--

string[1..30]

N/A

TA_SRVID(*)

long

R--R--R--

1 <= num < 30,001

N/A

TA_GRPNO(*)

long

R--R--R--

1 <= num < 30,000

N/A

TA_STATE(k)

string

R-XR-XR--

See T_CLIENT Class in TM_MIB(5)


TA_LMID(*)

string

R--R--R--

LMID

N/A

TA_PID(*)

long

R--R--R--

1 <= num

N/A

TA_NADDR

string

R--R--R--

string[1..78]

N/A

TA_HWCLIENTS

long

R--R--R--

1 <= num < 32,767

N/A

TA_MULTIPLEX

long

R--R--R--

1 <= num < 32,767

N/A

TA_CURCLIENTS

long

R--R--R--

1 <= num < 32,767

N/A

TA_TIMELEFT

long

R--R--R--

0 <= num

N/A

TA_ACTIVE

string

R--R--R--

"{Y | N}"

N/A

TA_TOTACTTIME

long

R--R--R--

0 <= num

N/A

TA_TOTIDLTIME

long

R--R--R--

0 <= num

N/A

TA_CURWORK

long

R--R--R--

0 <= num

N/A

TA_FLOWCNT

long

R--R--R--

0 <= num

N/A

TA_NUMBLOCKQ

long

R--R--R--

0 <= num

N/A

TA_RCVDBYT

long

R--R--R--

0 <= num

N/A

TA_RCVDNUM

long

R--R--R--

0 <= num

N/A

TA_SENTBYT

long

R--R--R--

0 <= num

N/A

TA_SENTNUM

long

R--R--R--

0 <= num

N/A

(k) - GET key field
(*) - GET/SET key, one or more required for SET operations

1All attributes in Class T_WSH are local attributes.

Attribute Semantics

TA_CLIENTID: string[1..78]

Client identifier for this WSH. The data in this field should not be interpreted directly by the end user except for equality comparison.

TA_WSHCLIENTID: string[1..78]

Client identifier for this WSH. The data in this field should not be interpreted directly by the end user except for equality comparison. This field can be used to link the WSH to its associated Workstation client T_CLIENT objects. This field value is always equal to the value for the TA_CLIENTID attribute for this class.

TA_SRVGRP: string[1..30]

Logical name of the server group for the associated WSL.

TA_SRVID: 1 <= num < 30,001

Unique (within the server group) server identification number for the associated WSL.

TA_STATE:

State for the WSH client within the application. Any state defined for the T_CLIENT class in TM_MIB(5) may be returned or set as indicated on that reference page. State changes to the SUSpended state are transitive to all clients associated with this WSH as is the resetting of a SUSpended WSH to ACTive. Additionally, SUSpended WSH clients will not be assigned any additional incoming clients by the WSL. Note that the state of a WSH client may not be set to DEAD when accessing the T_CLIENT class; however, the state transition to DEAD is allowed via the T_WSH class and will result in all connections being handled by the targeted WSH to be dropped abortively.

TA_LMID: LMID

Current logical machine on which the WSH is running.

TA_PID: 1 = num

Native operating system process identifier for the WSH client. Note that this may not be a unique attribute since clients may be located on different machines allowing for duplication of process identifiers.

TA_NADDR: string[1..78]

Network address of workstation handler. Hexadecimal addresses are converted to an ascii format with a leading "0x". TCP/IP addresses are reported in the "//#.#.#.#:port" format.

TA_HWCLIENTS: 1 <= num <32,767

High water number of clients accessing application via this WSH.

TA_MULTIPLEX: 1 <= num <32,767

Maximum number of clients that may access the application via this WSH.

TA_CURCLIENTS: 1 <= num <32,767

Current number of clients accessing application via this WSH.

TA_TIMELEFT: 0 <= num

A non-0 value for this attribute indicates that the WSH has been assigned a newly connecting Workstation client that has the indicated amount of time, in seconds, to complete the initialization process with the WSH.

TA_ACTIVE: {Y | N}

A value of Y indicates that the WSH is currently performing work on behalf of one of its associated Workstation clients. A value of N indicates that the WSH is currently waiting for work to perform on behalf of one of its associated Workstation clients.

TA_TOTACTTIME: 0 <= num

Time, in seconds, that the WSH has been active since it started processing.

TA_TOTIDLTIME: 0 <= num

Time, in seconds, that the WSH has been idle since it started processing.

TA_CURWORK: 0 <= num

Amount of work processed by this WSH since the last WSH assignment by the WSL. This value is used by the WSL to load balance new incoming connections amongst a set of WSH processes.

TA_FLOWCNT: 0 <= num

Number of times flow control has been encountered by this WSH. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_NUMBLOCKQ: 0 <= num

Number of times this WSH has been unable to enqueue a message to a local UNIX System message queue due to queue blocking conditions. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_RCVDBYT: 0 <= num

Number of bytes received from the network by this WSH from all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_RCVDNUM: 0 <= num

Number of BEA Tuxedo system messages received from the network by this WSH from all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_SENTBYT: 0 <= num

Number of bytes sent to the network by this WSH to all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

TA_SENTNUM: 0 <= num

Number of BEA Tuxedo system messages sent to the network by this WSH to all of its present and past Workstation clients. This attribute should be considered only in relation to recent past values as it may wrap around during the lifetime of the WSH.

Limitations

This class represents a specialization of the T_CLIENT class and as such represents certain attributes that are duplicated in the corresponding T_CLIENT objects. Attributes not listed that are included in the T_CLIENT class must be accessed via that class and are not available through the T_WSH class.

The attributes of WSH servers are meaningful only in a run-time environment. Therefore they cannot be changed, in an unbooted environment, by using the tpadmcall(3c) function.

T_WSL Class Definition

Overview

The T_WSL class represents configuration and run-time attributes of WSL server processes configured to manage Workstation groups. These attribute values identify and characterize Workstation specific configuration attributes for WSL T_SERVER objects within the application. This class is linked to the T_WSH class by the common key fields, TA_SRVGRP and TA_SRVID.

Attribute Table

WS_MIB(5): T_WSL Class Definition Attribute Table

Attribute

Type

Permissions

Values

Default

TA_SRVGRP(r)(*)

string

ru-r--r--

string[1. .30]

N/A

TA_SRVID(r)(*)

long

ru-r--r--

1 <= num < 30,001

N/A

TA_GRPNO(k)

long

r--r--r--

1 <= num < 30,001

N/A

TA_STATE(k)

string

rwxr-xr--

See T_SERVER Class in TM_MIB(5)

TA_LMID(k)

string

R--R--R--

LMID

N/A

TA_PID(k)

long

R--R--R--

1 <= num

N/A

TA_DEVICE

string

rw-r--r--

string[0. .78]

N/A

TA_NADDR(r)

string

rw-r--r--

string[1. .78]

N/A

TA_EXT_NADDR

string

rw-r--r--

string[0. .78]

""

TA_WSHNAME

string

rw-r--r--

string[1. .78]

"WSH"

TA_MINHANDLERS

long

rwxr-xr--

0 <= num < 256

0

TA_MAXHANDLERS

long

rw-r--r--

0 <= num < 32,767

See note 1.

TA_MULTIPLEX

long

rw-r--r--

1 <= num < 32,767

10

TA_MINENCRYPTBITS

string

rwxrwx---

{0 | 40 | 56 | 128}
See note 2.

0

TA_MAXENCRYPTBITS

string

rwxrwx---

{0 | 40 | 56 | 128}
See note 2.

128

TA_MINWSHPORT

long

rwxr-xr--

0 <= num < 65,535

2048

TA_MAXWSHPORT

long

rw-r--r--

0 <= num < 65,535

65,535

TA_MAXIDLETIME

long

rwxr-xr--

0 <=num < 35,204,650

35,204,649

TA_MAXINITTIME

long

rwxr-xr--

1 <= num < 32,767

60

TA_CMPLIMIT

string

rwxr-xr--

threshold

MAXLONG

TA_CLOPT

string

rwxr--r--

string[0..128]

"-A"

TA_ENVFILE

string

rwxr--r--

string[0..78]

""

TA_GRACE

long

rwxr--r--

0 <= num

0

TA_KEEPALIVE

string

rwxr-xr--

"{client | handler | both | none}"

"none"

TA_MAXGEN

long

rwxr--r--

0 <= num < 256

1

TA_NETTIMEOUT

long

rwxr-xr--

0 <= num <= MAXLONG

0

TA_RCMD

string

rwxr--r--

string[0..78]

""

TA_RESTART

string

rwxr--r--

"{Y | N}"

"Y"

TA_SEQUENCE(k)

long

rwxr--r--

1 <= num < 10,000

>= 10,000

T_WSL Class: Local Attributes

TA_CURHANDLERS

long

R--R--R--

0 <= num

N/A

TA_HWHANDLERS

long

R--R--R--

0 <= num

N/A

TA_WSPROTO

long

R--R--R--

0 <= num

N/A

TA_SUSPENDED

string

R-XR-XR--

"{NEW | ALL | NONE}"

N/A

TA_VIEWREFRESH

string

--X--X---

"Y"

N/A

(k) - GET key field
(r) - Required field for object creation (SET TA_STATE NEW)
(*) - GET/SET key, one or more required for SET operations

1 If a value for this attribute is not specified at the time the object is created, then a value of 0 will be assigned. A value of 0 for this attribute indicates that the effective value is determined at activation time from the current setting for TA_MAXHANDLERS and the T_MACHINE class setting for TA_MAXWSCLIENTS. Note that a GET operation with the MIB_LOCAL flag set will get the effective value for objects with an activation time default setting.

2 The link-level encryption value of 40 bits is provided for backward compatibility.

Attribute Semantics

TA_SRVGRP: string[1..30]

Logical name of the server group. Server group names cannot contain an asterisk (*), comma, or colon.

TA_SRVID: 1 <= num < 30,001

Unique (within the server group) server identification number.

TA_GRPNO: 1 <= num < 30,001

Group number associated with this servers group.

TA_STATE:

State for the WSL server within the application. Any state defined for the T_SERVER class in TM_MIB(5) may be returned or set as indicated on that reference page.

TA_LMID: LMID

Current logical machine on which the server is running.

TA_PID: 1 = num

Native operating system process identifier for the WSL server. Note that this may not be a unique attribute since servers may be located on different machines allowing for duplication of process identifiers.

TA_DEVICE: string[0..78]

Device name to be used by the WSL process to access the network. This attribute is optional.

TA_NADDR: string[1..78]

Specifies the complete network address to be used by the WSL process as its listening address. The listening address for a WSL is the means by which it is contacted by Workstation client processes participating in the application. If string has the form "0xhex-digits" or "\\xhex-digits", it must contain an even number of valid hex digits. These forms are translated internally into a character array containing TCP/IP addresses. The value of string may also be represented in either of the following forms:

//host.name:port_number

//#.#.#.#:port_number

In the first of these formats, hostname is resolved to a TCP/IP host address at the time the address is bound using the locally configured name resolution facilities accessed via gethostbyname(3c). The string #.#.#.# is the dotted decimal format in which each # represents a decimal number in the range 0 to 255. Port_number is a decimal number in the range 0 to 65535.

Note: Some port numbers may be reserved for the underlying transport protocols (such as TCP/IP) used by your system. Check the documentation for your transport protocols to find out which numbers, if any, are reserved on your system.

TA_EXT_NADDR: string[0..78]

Specifies the complete network address to be used as a well known address template of the WSH process. The address will be combined with a WSH network address to generate a well known network address used by the Workstation client to connect to a WSH process. It has the same format as the TA_NADDR except that it substitutes the port number with same length of character M to indicate the position of the combined network address will be copied from the WSH network address. For example when Address template is 0x0002MMMMdddddddd and WSH network address is 0x00021111ffffffff then the well known network address will be 0x00021111dddddddd. When address template starts with "//" network address type assumes to be IP based and the TCP/IP port number of WSH network address will be copied into the address template to form the combined network address. This feature is useful when Workstation client needs to connect to a WSH through a router which performs Network Address Translation. Empty TA_EXT_NADDR string in a SET operation on an existing T_WSL object will eliminate the -H entry from the TA_CLOPT attribute.

TA_WSHNAME: string[1..78]

The name of the executable providing workstation handler services for this workstation listener. The default for this is WSH which corresponds to the system provided workstation handler. Workstation handlers may be customized using the command buildwsh(). See the Customization section and the buildwsh(1) reference page for more details.

TA_MINHANDLERS: 0 <= num < 256

The minimum number of handlers that should be available in conjunction with this WSL at any given time. The WSL will start this many WSHs immediately upon being activated and will not deplete the supply of WSHs below this number until the administrator issues a shutdown to the WSL. Modifications to this attribute for a running WSL may cause additional handlers to be activated.

TA_MAXHANDLERS: 0 <= num < 32,767

The maximum number of handlers that should be available in conjunction with this WSL at any given time. Handlers are started as necessary to meet the demand of Workstation clients attempting to access the system. This attribute must be greater than or equal to the setting for the minimum number of handlers.

TA_MULTIPLEX: 1 <= num < 32,767

Maximum number of clients that are to be supported by any one handler process concurrently.

TA_MINENCRYPTBITS: {0 | 40 | 56 | 128}

Specifies the minimum level of encryption required when connecting to the BEA Tuxedo system. 0 means no encryption, while 40, 56, and 128 specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment fails. The default is 0.

Note: The link-level encryption value of 40 bits is provided for backward compatibility.

TA_MAXENCRYPTBITS: {0 | 40 | 56 | 128}

Specifies the maximum level of encryption that can be negotiated when connecting to the BEA Tuxedo system. 0 means no encryption, while 40, 56, and 128 specify the encryption length (in bits). The default is 128.

Note: The link-level encryption value of 40 bits is provided for backward compatibility.

TA_MINWSHPORT: 0 <= num < 65,535

The lower end of the range of available port numbers that may be allocated to WSH processes by this listener.

TA_MAXWSHPORT: 0 <= num < 65,535

The upper end of the range of available port numbers that may be allocated to WSH processes by this listener.

TA_MAXIDLETIME: 0 <= num < 35,204,650

Maximum amount of time, in minutes, that a Workstation client is permitted to be idle before it will be abortively disconnected from the application by the handler. A value of 35,204,650 allows clients to be idle as long as they wish without being timed out. A value of 0 indicates clients may be terminated after any period of inactivity greater than 1 second.

TA_MAXINITTIME: 1 <= num < 32,767

The minimum number of seconds that should be allowed for a Workstation client to complete initialization processing through the WSH before being timed out by the WSL.

TA_CMPLIMIT: threshold

Threshold message size at which compression will occur for traffic to and from Workstation clients. >threshold may be either non-negative numeric values of the string "MAXLONG," which is dynamically translated to the maximum long setting for the machine. Limitation: This attribute value is not used for Workstation clients running BEA Tuxedo Workstation Release 6.1 or earlier.

TA_CLOPT: string[0..128]

Command line options to be passed to WSL server when it is activated. See the servopts(5) reference page for details. Limitations: Run-time modifications to this attribute will not affect a running WSL server. Server specific options (that is, those after a double-dash "--") may not be set and will not be returned.

TA_ENVFILE: string[0..78]

WSL server specific environment file. See T_MACHINE:TA_ENVFILE for a complete discussion of how this file is used to modify the environment. Limitation: Run-time modifications to this attribute will not affect a running WSL server.

TA_GRACE: 0 <= num

The period of time, in seconds, over which the T_WSL:TA_MAXGEN limit applies. This attribute is meaningful only for restartable WSL servers, that is, if the T_WSL:TA_RESTART attribute is set to "Y". When a restarting server would exceed the TA_MAXGEN limit but the TA_GRACE period has expired, the system resets the current generation (T_SERVER:TA_GENERATION) to 1 and resets the initial boot time (T_SERVER:TA_TIMESTART) to the current time. A value of 0 for this attribute indicates that the WSL server should always be restarted.

TA_KEEPALIVE: "{client | handler | both | none}"

Here you can turn on the network keep-alive operation for the client, the handler, or both. You may also turn off this operation for both the client and handler by specifying "none".

Changes to the value of this attribute affect only new connections.

TA_MAXGEN: 1 <= num < 256

Number of generations allowed for a restartable WSL server (T_WSL:TA_RESTART == "Y") over the specified grace period (T_WSL:TA_GRACE). The initial activation of the WSL server counts as one generation and each restart also counts as one. Processing after the maximum generations is exceeded is discussed above with respect to TA_GRACE.

TA_NETTIMEOUT: 0 <= num <= MAXLONG

The value of TA_NETTIMEOUT is the minimum number of seconds that a Workstation client is allowed to wait to receive a response from the WSL/WSH. A value of 0 indicates no network timeout.

Changes to the value of this attribute affect only new connections.

TA_RCMD: string[0..78]

Application specified command to be executed in parallel with the system restart of an application server. This command must be an executable file in the native operating system.

TA_RESTART: "{Y | N}"

Restartable ("Y") or non-restartable ("N") WSL server. If server migration is specified for this server group (T_RESOURCE:TA_OPTIONS/MIGRATE T_GROUP:TA_LMID w/ alternate site), then this attribute must be set to "Y".

TA_SEQUENCE: 1 <= num < 10,000

Specifies when this server should be booted (tmboot(1)) or shut down (tmshutdown(1)) relative to other servers. T_WSL objects added without a TA_SEQUENCE attribute specified or with an invalid value will have one generated for them that is 10,000 or more and is higher than any other automatically selected default. Servers are booted by tmboot() in increasing order of sequence number and shutdown by tmshutdown() in decreasing order. Run-time modifications to this attribute affect only tmboot() and tmshutdown() and will affect the order in which running servers may be shutdown by a subsequent invocation of tmshutdown().

TA_CURHANDLERS: 0 <= num

Number of currently active handlers associated with this WSL.

TA_HWHANDLERS: 0 <= num

Maximum number of currently active handlers associated with this WSL at any one time.

TA_WSPROTO: 0 <= num

The BEA Tuxedo Workstation protocol version number for this Workstation group. Note that Workstation clients connecting to this group may themselves have a different protocol version number associated with them.

TA_SUSPENDED: "{NEW | ALL | NONE}"

A value of "NEW" indicates that new incoming clients may not connect through this WSL object. A value of "ALL" indicates that Workstation clients already connected to the application through this WSL have been suspended (see TM_MIB(5)) in addition to disallowing new incoming connections. A value of "NONE" indicates that no suspension characteristics are in effect.

TA_VIEWREFRESH: Y

Setting a value of Y will cause all active WSHs in the Workstation group to refresh their VIEW buffer type cache.

Limitations

This class represents a specialization of the T_SERVER class and as such represents certain attributes that are duplicated in the corresponding T_SERVER objects. Attributes not listed that are included in the T_SERVER class must be accessed via that class and are not available through the T_WSL class.

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.

If, however, the request is successfully routed to a system service capable of satisfying the request and that service determines that there is a problem handling the request, then failure may be returned in the form of an application level service failure. In these cases, tpcall() and tpgetrply() will return an error with tperrno set to TPESVCFAIL and return a reply message containing the original request along with TA_ERROR, TA_STATUS and TA_BADFLD fields further qualifying the error as described below. When a service failure occurs for a request forwarded to the system through the TMQFORWARD(5) server, the failure reply message will be enqueued to the failure queue identified on the original request (assuming the -d option was specified for TMQFORWARD).

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.

[other]

Other error return codes generic to any component MIB are specified in the MIB(5) reference page. These error codes are guaranteed to be mutually exclusive with any WS_MIB(5) specific error codes defined here.

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.

[other]

Other return codes generic to any component MIB are specified in the MIB(5) reference page. These return codes are guaranteed to be mutually exclusive with any WS_MIB(5) specific return codes defined here.

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, then 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

Following is a sequence of code fragments that deactivate a Workstation group in an orderly fashion using a combination of TM_MIB(5) and WS_MIB(5).

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 logoff.

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

tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5), TM_MIB(5)

Setting Up a BEA Tuxedo Application

Administering a BEA Tuxedo Application at Run Time

Programming a BEA Tuxedo Application Using C

Programming a BEA Tuxedo Application Using FML