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 /WS 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_GRPNO: 1 <= num < 30,000

Group number associated with this servers group.

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 manual 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 targetted 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 TUXEDO System/T 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 TUXEDO System/T 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.

T_WSL Class Definition

Overview

The T_WSL class represents configuration and runtime attributes of WSL server processes configured to manage /WS groups. These attribute values identify and characterize /WS 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

( k ) - GET key field

( r ) - Required field for object creation (SET TA_STATE NEW)

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

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

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

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 manual 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 is a required value for access to a network via a TLI-based TUXEDO System/T binary. This attribute is not needed for sockets-based TUXEDO System/T binaries.

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 may also be in either of the following two 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 "#.#.#.#" is the dotted decimal format where each # represents a decimal number in the range 0 to 255. Port_number is a decimal number in the range 0 to 65535. the hexadecimal representations of the string specified.

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_KEEPALIVE: {client|handler|both|none}

This option directs the /WS client, WSH process, or both, to activate the network provider's KEEPALIVE option. This option improves the speed and reliability of network failure detection, by actively testing an idle connection's state at the protocol stack level. The availability and timeout thresholds for this feature are determined by operating system tunable parameters.

A value of client will configure this option for the /WS client, a value of handler will configure this option for the WSH, and a value of both will configure both sides of the connection. The default value is none, in which case neither side has the KEEPALIVE option configured.

Note that the KEEPALIVE interval is an operating system parameter, so changing the value will affect any other applications that enable KEEPALIVE. Many platforms have a two hour default value that may be longer than desired.

This option is not available on all platforms. A userlog warning message will be generated if the KEEPALIVE option is specified but not available on the WSH's machine. If KEEPALIVE is requested but not available on a /WS client's machine, the setting will be silently ignored.

TA_NETTIMEOUT: 0 <== num <= MAXLONG

The network-timeout option will establish a wait period, in seconds, for any TUXEDO operation by the /WS client that receives data from the network. If the period is exceeded, the operation will fail and the client will be disconnected from the application. A value of 0 (zero) indicates no time-out; this is the default. Note: setting this value too low may cause an unacceptably high number of disconnects.

TA_WSHNAME: string[1..78]

The name of the executable providing workstation handler services for this workstation listener. The default value for this is WSH which corresponds to the system provided workstation handler. Workstation handlers may be customized using the command buildwsh(1). See the Customization section and the buildwsh(1) man 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 minumum number of handlers.

TA_MULTIPLEX: 1 <= num < 32,767

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

MINENCRYPTBITS={0|40|128}

When connecting to TUXEDO, require at least this minimum level of encryption. "0" means no encryption, while "40" and "128" specify the encryption key length (in bits). If this minimum level of encryption cannot be met, link establishment will fail. The default value is "0".

MAXENCRYPTBITS={0|40|128}

When connecting to TUXEDO, negotiate encryption up to this level. "0" means no encryption, while "40" and "128" specify the encryption length (in bits). The default value is "128"

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 TUXEDO System /WS 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) manual page for details.

Limitations: Runtime modifications to this attribute will not affect a running WSL server. Server specific options (i.e., 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: Runtime 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, i.e., 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_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_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 shutdown ( tmshutdown(1)) relative to other servers. If two servers are given the same sequence number, it is possible for tmboot(1) to boot them in parallel and for tmshutdown(1) to shut them down in parallel. 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 value. Servers are booted by tmboot(1) in increasing order of sequence number and shutdown by tmshutdown(1) in decreasing order. Runtime modifications to this attribute affect only tmboot(1) and tmshutdown(1) and will affect the order in which running servers may be shutdown by a subsequent invocation of tmshutdown(1).

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 TUXEDO System/T /WS protocol version number for this /WS group. Note that /WS 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 /WS 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(3c), tpgetrply(3c) and tpdequeue(3c)) used to retrieve responses to administrative requests may return any error defined for them. These errors should be interpreted as described on the appropriate manual 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(3c) and tpgetrply(3c) 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) manual 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) manual 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 manual page are available on TUXEDO System/T 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 TUXEDO System/T 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 manual 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 manual 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 TUXEDO System MIBs, as well as the header file and field table defined in this manual page, are available on all supported native and workstation platforms.

EXAMPLE

Following is a sequence of code fragments that deactivate a /WS 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

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

/* 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\n", 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\n",
            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));

/* 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);

/* 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--;
        }
    }
}

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); } 

	/* 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); } 

	/* 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);