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
.
1If 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]
TA_SRVID
: 1 = num 30,001
TA_GRPNO
: 1 = num 30,000
TA_STATE
:
T_SERVER
class in TM_MIB
(5) may be returned or set as indicated on that reference page.
TA_LMID
: LMID
TA_PID
: 1 = num
TA_DEVICE
: string[0..78]
TA_NADDR
: string[1..78]
"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]
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]
buildwsh
(1). See the Customization section and the buildwsh
(1) reference page for more details.
TA_MINHANDLERS
: 0 = num 256
TA_MAXHANDLERS
: 0 = num 32,767
TA_MULTIPLEX
: 1 = num 32,767
TA_MINENCRYPTBITS
={0|40|128}
TA_ MAXENCRYPTBITS
={0|40|128}
TA_MINWSHPORT
: 0 = num 65,535
TA_MAXWSHPORT
: 0 = num 65,535
TA_MAXIDLETIME
: 0 = num 35,204,650
TA_MAXINITTIME
: 1 = num 32,767
TA_CMPLIMIT
: threshold
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 system Workstation Release 6.1 or earlier.
TA_CLOPT
: string[0..128]
TA_ENVFILE
: string[0..78]
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
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_KEEPALIVE:{client | handler | both | none}
none
.
Changes to the value of this attribute affect only new connections.
TA_MAXGEN
: 1 = num 256
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
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 time-out.
Changes to the value of this attribute affect only new connections.
TA_RCMD
: string[0..78]
TA_RESTART
: {Y|N
}
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
tmboot
(1)) or shutdown
( 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
(1) in increasing order of sequence number and shutdown by tmshutdown
(1) in decreasing order. Run-time 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
TA_HWHANDLERS
: 0 = num
TA_WSPROTO
: 0 = num
TA_SUSPENDED
: {NEW|ALL|NONE
}
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
Y
will cause all active WSHs in the Workstation group to refresh their VIEW
buffer type cache.
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.
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
(3), tpgetrply
(3) and tpdequeue
(3)) 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
(3) and tpgetrply
(3) 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
]
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
]
MIB
(5) reference page. These return codes are guaranteed to be mutually exclusive with any WS_MIB
(5) specific return codes defined here.
The header files and field tables defined in this reference page are available on BEA TUXEDO system 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.
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.
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).
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
The following header files are included.
#include <atmi.h>
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));
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);
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--;
}
}
}
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);
}
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);
}
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);
}
${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm
tpacall
(3c), tpalloc
(3c), tpcall
(3c), tpdequeue
(3c), tpenqueue
(3c), tpgetrply
(3c), tprealloc
(3c), Fadd32
(3fml), Fchg32
(3fml), Ffind32
(3fml), Fintro
(3fml), MIB
(5), TM_MIB
(5), Administering the BEA TUXEDO System, BEA TUXEDO Programmer's Guide