Oracle Tuxedo Scripting Tool

This chapter describes the Oracle Tuxedo Scripting Tool (TXST). It explains how you use the TXST command-line scripting interface to configure, manage, and persist change to Tuxedo running instances and monitor and manage server run-time events.

This chapter is organized as follows:

•	Using the Tuxedo Scripting Tool describes how the scripting tool works, its modes of operation, and the basic steps for invoking it.

•	Navigating MBeans describes how to retrieve Tuxedo domain configuration and run-time information, and edit configuration or custom MBeans.

•	Managing the Server Life Cycle describes using TXST to start and stop Tuxedo Server instances and to monitor and manage the server life cycle.

Using the Tuxedo Scripting Tool

What is the Tuxedo Scripting Tool?

The Tuxedo Scripting Tool (TXST) is a command-line scripting environment that you can use to manage, and monitor Tuxedo domains. The TXST scripting environment is based on the Java scripting interpreter, Jython. In addition to supporting standard Jython features such as local variables, conditional variables, and flow control statements, TXST provides a set of scripting functions (commands) that are specific to Tuxedo. See http://www.jython.org.

How Does TXST Work?

You can use the scripting tool online (connected to a running Tuxedo domain or a JMX agent embedded in the tlisten process). For information on TXST commands, see TXST Command and Variable Reference.

Online, TXST provides simplified access to Managed Beans (MBeans), Java objects that provide a management interface for an underlying resource that you can manage through JMX.

When TXST is connected to a Tuxedo domain, the scripting tool lets you navigate and interrogate MBeans, and supply configuration data to the instance. When TXST is connected to a JMX agent, its functionality is limited to commands which MBeans support.

Modes of Operation

TXST is a command-line interpreter that interprets commands either interactively, supplied one-at-a-time from a command prompt, or in batches, supplied in a file (script), or embedded in your Java code. The modes of operation represent methods for issuing TXST commands:

•	Interactively, on the command line—Interactive Mode

•	In a text file—Script Mode

•	Embedded in Java code—Embedded Mode

Interactive Mode

Interactive mode, in which you enter a command and view the response at a command-line prompt, is useful for learning the tool, prototyping command syntax, and verifying configuration options before building a script. Using TXST interactively is particularly useful for getting immediate feedback after making a critical configuration change. The TXST scripting shell maintains a persistent connection with an instance of Tuxedo domain. Because a persistent connection is maintained throughout the user session, you can capture multiple steps that are performed against the instance. For more information, see Recording User Interactions.

Script Mode

Scripts invoke a sequence of TXST commands without requiring your input, much like a shell script. Scripts contain TXST commands in a text file with a .py file extension, for example, filename.py. You use script files with three modes(Invoking TXST with the script, using Jython commands for running scripts and invoking the script with Ant build file). See Running Scripts.

Embedded Mode

In embedded mode, you instantiate an instance of the TXST interpreter in your Java code and use it to run TXST commands and scripts. Except for startRecording() and stopRecording(), all TXST commands and variables that you use in interactive and script mode can be run in embedded mode.

Listing 1 illustrates how to instantiate an instance of the TXST interpreter and use it to connect to a running domain and create a server.

Listing 5‑1 Running TXST From a Java Class

import java.util.*;

import oracle.tuxedo.jmx.tux.jyscript.TXSTInterpreter;

import org.python.util.InteractiveInterpreter;

 

public class EmbeddedTXST {

static InteractiveInterpreter interp = null;

EmbeddedTXST() {

interp = new TXSTInterpreter();

}

private static void connect() {

interp.exec("connect('//localhost:5037', 'simpapp', ‘38075’)");

}

private static void create_server() {

StringBuffer buffer = new StringBuffer();

buffer.append("cd('simple/GROUP1')\n");

buffer.append("srv1= create(‘simpserv’, ‘SERVER’, srvID=40)\n");

buffer.append("print 'Script ran successfully...'\n");

interp.exec(buffer.toString());

}

public static void main(String[] args){

new EmbeddedTXST();

connect();

create_server();

}

}

 

Main Steps for Using TXST

The following sections summarize the steps for setting up and using TXST:

•	Setting Up Your Environment

•	Invoking TXST

•	Requirements for Entering TXST Commands

•	Running Scripts

•	Exiting TXST

•	Getting Help

•	Recording User Interactions

•	Redirecting TXST Output to a File

Setting Up Your Environment

To set up your environment for TXST:

1.	Install and configure the TSAM agent.

2.	Set TUXDIR environment variable as Tuxedo install directory and $TUXDIR/bin to the PATH environment variable.

3.	Include $TUXDIR/jmx/jython-standalone.jar:$TUXDIR/jmx/tmjmx_tux.jar:$TUXDIR/jmx/tmjmx_metadata.jar in the CLASSPATH. Or you can invoke TXST just using txst.sh or txst.cmd which we provided.

Invoking TXST

To invoke TXST, enter the following command: txst.sh

A welcome message and the TXST prompt appears:

txst: /offline>

txst.sh is placed in $TUXDIR/bin. If you invoke TXST with txst.sh, you do not need to set up the CLASSPATH.

If you added the related jar files into CLASSPATH as we mentioned before, you can enter the command: java oracle.tuxedo.TXST. For instance,

#export CLASSPATH=$CLASSPATH:$TUXDIR/jmx/jython-standalone.jar:$TUXDIR/jmx/tmjmx_tux.jar:$TUXDIR/jmx/tmjmx_metadata.jar

# java oracle.tuxedo.TXST

Initializing Tuxedo Scripting Tool (TXST) ...

Note:

If using dmib related commands, you should use the package $TUXDIR/udataobj/tuxj/com.bea.core.jatmi_2.0.0.0.jar

Jython scans all the jar files it can find at first startup. Depending on the system, this process may take a few minutes to complete, and TXST may not return a prompt right away.

Welcome to Tuxedo Administration Scripting Tool

Type help() for help on available commands

txst:/offline>

Requirements for Entering TXST Commands

Follow these rules when entering TXST commands. Also see TXST Command and Variable Reference.

•	Command names and arguments are case sensitive.

•	Enclose arguments in single or double quotes. For example, 'newServer' or "newServer".

•	If you specify a backslash character (\) in a string, for example when specifying a file pathname, you should precede the quoted string by r to instruct TXST to interpret the string in its raw form and ensure that the backslash is taken literally. This format represents standard Jython syntax.

•	Display help information for TXST commands by printing the command’s documentation string. See Getting Help.

Running Scripts

TXST incorporates three ways for running scripts. To run the script examples in this guide, copy and save the commands in a text file with a .py file extension, for example, filename.py. Use the text file with the commands for running scripts that are listed below. There are sample scripts that you can use as a template when creating a script.py file from scratch. If the script will connect TXST to a running Tuxedo domain, start Tuxedo domain before running the script.

You can run the script in three modes:

•	Invoke TXST and run a script:

java oracle.tuxedo.TXST myscript.py

•	run a script from TXST:

execfile(‘myscript.py’)

Listing 5‑2 Running script myscript.py

connect("//localhost:5037", "simpapp", "38075");

cd('simple/GROUP1')

ls('c')

disconnect()

exit()

 

•	Invoke the TXST script from an Ant build file

Scripts invoke a sequence of TXST commands without requiring your input, much like a shell script. Scripts contain TXST commands in a text file with a .py file extension.

TXST provides a custom ant task to invoke the TXST script from an Ant build file. If you want to use the task with your own Ant installation,add the following task definition in your build file:

<taskdef name ="txst" classname="oracle.tuxedo.jmx.tux.jyscript.TXSTTask" />

To run TXST from an Ant script:

a.	Set your environment in a command shell,which include TUXDIR,CLASSPATH,JAVA_HOME,ANT_HOME and so on.

b.	Add a call to the txst Ant task to execute TXST commands. For example:

<target name="GetParameters">

<txst debug="false" failOnError="false"

executeScriptBeforeFile="true" fileName="./test.py">

<script>

connect("//slce04cn03:5067","simpapp","38175")

ls()

print cmo.GetParameters()

</script>

</txst>

</target>

Using the txst Ant task, you can specify TXST commands within a TXST script(.py), using the fileName attribute, or embed TXST script commands inside the build file, within the <script> tags.

c.	Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:

bash-3.2$ ant getParameters

the syntax of the txst Ant task is as follows:

<txst properties="propsFile" filename=”filename” arguments="arglist"

failOnError=”value” executeScriptBeforeFile="value” debug=”value” >

<script>

txst-commands

</script>

The following table defines the Ant task attributes that you can specify as part of the txst Ant task.

 

Attribute	Definition
properties="propsFile"	Optional. Name and location of the properties file that contains name-value pairs that you can reference in your script.
fileName="fileName"	Optional. Name and location of the TXST script file that you would like to execute. If the specified TXST script file does not exist, the txst Ant task fails.
arguments="arglist"	Optional. List of arguments to pass to the script. These arguments are accessible using the sys.argv variable.
failOnError="value"	Optional. Boolean value specifying whether the Ant build script will fail if the txst Ant task fails. This attribute defaults to true.
executeScriptBeforeFile="value"	Optional. Boolean value specifying whether the embedded script is executed before the specified TXST script file. This attribute defaults to true, specifying that the embedded script is executed first.
debug="value"	Optional. Boolean value specifying whether debug statements should be output when the TXST Ant Task is executed. This attribute defaults to false.

In the following example, test.py is the file in which there are TXST commands.You also can add TXST command in the “script” node:

<project default="all" basedir=".">

<taskdef name ="txst"

classname="oracle.tuxedo.jmx.tux.jyscript.TXSTTask" />

<target name="getParameters">

<txst debug="false" failOnError="false"

executeScriptBeforeFile="true" fileName="./test.py">

<script>

connect("//slce04cn03:5067","simpapp","38175")

cmo.GetParameters()

</script>

</txst>

</target>

</project>

TXST does not support Maven in this version.

Exiting TXST

To exit TXST:

txst:simpapp_38075:/>exit()

c:\jython\bin>

Getting Help

To display information about TXST commands, print the command’s documentation string.

For example, to display information about the disconnect command, enter the following command:

txst:/simpapp>help(‘disconnect’)

The command returns the following:

This function is used to disconnect from tuxedo server instance.

Arguments list:

()

txst: /simpapp > disconnect()

Recording User Interactions

To start and stop the recording of all TXST command input, enter:

startRecording(outputFile)

stopRecording()

You must specify the file pathname for storing TXST commands when you enter the startRecording command.

For example, to record TXST commands in the record.py file, enter the following command:

txst:/simpapp> startRecording('record.py')

For more information, see startRecording and stopRecording.

Redirecting TXST Output to a File

To start and stop redirecting TXST output to a file, enter:

redirect(outputFile,[toStdOut])

stopRedirect()

You must specify the pathname of the file to which you want to redirect TXST output. You can also optionally specify whether you want TXST output to be sent to stdout; the toStdOut argument defaults to True.

For example, to redirect TXST output to the logs/txst.log file in the current directory and disable output from being sent to stdout, enter the following command:

txst:/simpapp> redirect('./logs/txst.log', False)

For more information, see redirect and stopRedirect.

Navigating MBeans

Navigating and Interrogating Mbeans

TXST online provides simplified access to MBeans. While JMX APIs require you to use JMX object names to interrogate MBeans, TXST enables you to navigate a hierarchy of MBeans in a similar fashion to navigating a hierarchy of files in a file system.

Tuxedo organizes its MBeans in a hierarchical data model. In the TXST file system, MBean hierarchies correspond to drives; MBean instances are directories; MBean attributes and operations are files. TXST traverses the hierarchical structure of MBeans using commands such as cd, ls, and pwd in a similar way that you would navigate a file system in a UNIX or Windows command shell. After navigating to an MBean instance, you interact with the MBean using TXST commands.

In the hierarchy, the root directory is DomainMBean; each instance of the MBean type is a subdirectory; and MBean attributes and parameters are nodes (like files) under the MBean instance directory.

Domain MBean

Machine MBean

Bridge MBean

Group MBean

Server MBean

ARTBatchSystem Mbean

Changing the Current Management Object

When TXST first connects to an instance of Tuxedo domain, the variable, cmo (Current Management Object), is initialized to the root of all configuration management objects, DomainMBean. When you navigate to an MBean type, the value of cmo reflects the parent MBean. When you navigate to an MBean instance, TXST changes the value of cmo to be the current MBean instance, as shown in Listing 3.

For more information on TXST variables, see TXST Command and Variable Reference.

Listing 5‑3 Changing the Current Management Object

txst:/offline>connect("//slce04cn03:5035", "simpapp", "58103")

txst:simpapp_58103:/>cmo.getMbeanName()

simpapp_58103:type=tuxedo_domain

txst:simpapp_58103:/>cd('L1')

txst:simpapp_58103:/L1>cmo.getMbeanName()

simpapp_58103:type=tuxedo_machine,LMID=L1

 

Navigating and Displaying Configuration MBeans Example

The commands in Listing 4 instruct TXST to connect to a Tuxedo domain instance, navigate, and display MBeans in DomainMBean. If no argument is specified, the ls command lists all the child MBeans and attributes.

Listing 5‑4 Navigating and Displaying Configuration MBeans

txst:/offline>connect("//slce04cn03:5035", "simpapp", "58103")

txst:simpapp_58103:/>ls()

attributes:

State ACTIVE

parameters:

TA_AUTHSVC

TA_AUTOTRAN N

TA_BBLQUERY 30

TA_BLOCKTIME 6

TA_CLASS T_DOMAIN

TA_CMTRET COMPLETE

TA_COMPONENTS

TA_CURDRT 0

TA_CURGROUPS 1

TA_CURINTERFACES 0

TA_CURMACHINES 0

TA_CURQUEUES 2

TA_CURRFT 0

TA_CURRTDATA 0

TA_CURSERVERS 2

TA_CURSERVICES 9

TA_CURSTYPE 1

TA_CURTYPE 12

TA_DBBLFAILOVER 0

TA_DBBLWAIT 2

TA_DOMAINID simpapp

TA_ENCRYPTION_REQUIRED N

TA_ERROR 0

TA_GID 8500

TA_HWDRT 0

TA_HWGROUPS 1

TA_HWINTERFACES 0

TA_HWMACHINES 1

TA_HWQUEUES 2

TA_HWRFT 0

TA_HWRTDATA 0

TA_HWSERVERS 2

TA_HWSERVICES 9

TA_INSTANCE_AFFINITY NONE

TA_IPCKEY 58103

TA_LDBAL N

TA_LICEXPIRE

TA_LICMAXUSERS 10000000

TA_LICSERIAL

TA_MASTER L1

TA_MAXACCESSERS 15

TA_MAXACLGROUPS 16384

TA_MAXBUFSTYPE 32

TA_MAXBUFTYPE 16

TA_MAXCONV 1

TA_MAXDRT 0

TA_MAXGROUPS 100

TA_MAXGTT 100

TA_MAXINTERFACES 150

TA_MAXMACHINES 256

TA_MAXNETGROUPS 8

TA_MAXOBJECTS 1000

TA_MAXQUEUES 20

TA_MAXRFT 0

TA_MAXRTDATA 8

TA_MAXSERVERS 20

TA_MAXSERVICES 50

TA_MAXSPDATA 18504

TA_MAXTRANTIME 0

TA_MIBMASK 0

TA_MODEL SHM

TA_MORE 0

TA_NOTIFY SIGNAL

TA_OCCURS 1

TA_OPTIONS

TA_PERM 384

TA_PREFERENCES

TA_SANITYSCAN 12

TA_SCANUNIT 10

TA_SCANUNIT_EXT 10

TA_SECURITY NONE

TA_SEC_PRINCIPAL_LOCATION

TA_SEC_PRINCIPAL_NAME

TA_SEC_PRINCIPAL_PASSVAR

TA_SGRPFAILOVER 0

TA_SIGNATURE_AHEAD 3600

TA_SIGNATURE_BEHIND 604800

TA_SIGNATURE_REQUIRED N

TA_SSL_RENEGOTIATION 0

TA_STATE ACTIVE

TA_SYSTEM_ACCESS FASTPATH

TA_TRANTIME 30

TA_UID 532

TA_USIGNAL SIGUSR2

childBean:

tuxedo_machine L1

additional info:

 

Browsing Runtime MBeans

Lists all the children beans and/or attributes for the current bean.

You can optionally control the output by specifying an argument. If no argument is specified, the command lists all children beans and attributes in the domain. The output is returned as a string.

Finding MBeans

To locate a particular MBean, you can use the find command. TXST returns the pathname to the specified MBean. You can use the getMBean command to return the MBean specified by the path. For more information, see find and getMBean.

For example:

txst:simpapp_58103:/>find('ser*')

/L1/GROUP1/server_1

txst:simpapp_58103:/>bean = getMBean('/L1/GROUP1/server_1')

txst:simpapp_58103:/>path = getPath(bean)

txst:simpapp_58103:/>print path

/L1/GROUP1/server_1

Managing the Server Life Cycle

During its lifetime, a running instance can transition through a number of operational states, such as shutdown, starting, suspended, resuming, and running. TXST commands such as start, suspend, resume, and shutdown cause specific changes to the state of a server instance.

Using TXST, you can:

•	Start and shutdown a Tuxedo domain, machine, group or server. See Starting and Stopping.

•	Migrate the servers in the specified scope to an alternate location.

•	Suspend and resume a specified target. See Suspending and Resuming.

Starting and Stopping

TXST provides several ways to start and stop a specified object. The method that you choose depends on the target object.

Domain

To start a Tuxedo domain, you should invoke startDomain() command. This command must use while TXST is connecting to JMX agent embedded in the tlisten process. If invoking is success, you can connect to Tuxedo domain. See startDomain.

To stop a Tuxedo domain, you should invoke shutdownDomain() command. If domain is shutdown successfully, TXST will disconnect from domain and go back to connect JMX agent. See shutdownDomain.

Machine, Group, and Server

For machine, group and server, you can invoke start() or shutdown() directly. If your target is server, there are two ways to operate these command. See start and shutdown.

Suspending and Resuming

The following MBeans are supported by suspending and resuming: Machine, Server, Bridge, WSH, JSH. However, the target object is different from the Mbeans. For more details about targets, refer to following table.

 

Mbean	Target
Machine	Client
Server	Service
Bridge	Remote bridge
WSH	WSH
JSH	JSH