This chapter describes the Business Transaction Management utilities. You use these utilities to connect to and manage a database, to manage system service deployment log files, and to display information about the Business Transaction Management product. This chapter includes the following sections:
Business Transaction Management includes a set of command line utilities that allow you to perform certain tasks from the command line.
For Java platforms, the utilities are located in: [install_dir]/tools
On Windows platforms, utilities use the JRE bundled with Business Transaction Management.
On Unix-like systems, you must specify a JRE to use by doing one of the following:
set the JAVA_HOME environment variable and remove the directory
BTM_install_dir/server/jre directory
replace BTM_install_dir/server/jre with a link to a valid JRE directory
The following table lists Business Transaction Management utilities.
| Name | Description |
|---|---|
| datastoreUtil | Allows you to connect to a database. Once connected, you can do the following:
|
| logMerger | Merges Business Transaction Management system service deployment log files (logdir) to consolidate analysis or archiving. |
| showProductInfo | Outputs information about the Business Transaction Management product. |
The most common use of the datastoreUtil utility is to assist in the installation of the Business Transaction Management product. During configuration, the system automatically creates the appropriate database tables for database users for the sphere, performance, and transaction databases unless you choose to create them beforehand with the datastoreUtil utility.
By using the generateSchema command, you can create DDL for the targeted database environment. The output of the generateSchema command can be used as input (with the appropriate database utility) to create the necessary tables and views for the Business Transaction Management product.
Use the datastoreUtil utility to connect to a database. Once connected, you can do the following:
generate the DDL of the specified schema definition within the connected database
check the status of the specified schema within the connected database
create the specified schema within the connected database
upgrade the specified schema within the connected database
drop the entire specified schema from the connected database
save the database connection information into a file for easy reconnection to the database at a later time
display the owner of the database instance (service name and UUID)
reset ownership of the database instance by removing knowledge of its current owner
dump the definition of the connected database to a text file containing SQL dml statements in the given database format
enter the database explore mode (commands to search and display data)
Invoking the datastoreUtil Utility
To invoke the datastoreUtil utility, navigate to the tools directory and use the following from the command line:
Windows:datastoreUtil.bat
Unix: datastoreUtil.sh
After starting the utility, you can call the commands described in the next subsection. For commands that have multiple arguments, you must call the arguments in the order described.
Use the exit command to exit the utility.
datastoreUtil commands include the following:
| Command | Command | Command |
|---|---|---|
| help | generateSchema | checkOwner |
| connect | createSchema | resetOwner |
| saveConnection | checkSchema | dumpDataBase |
| close | upgradeSchema | -- |
| exit | dropSchema | -- |
Use the following syntax to get help:
help | help command
Use the help command to view help for all commands, or enter a command name to receive help for a single command
Connect to a database using the user-specified connection information
connect databaseType|filename
databaseType - specify oracle. This is the only supported value.
filename - name of a file as specified by the saveConnection command
Use the connect command to enter database connection information and connect to the database. You must have the following information for the database to which you want to connect:
driver name
username
password
URL connection string
Once connected, you might issue the saveConnection command to save the connection information within a file. The next time you want to connect to the same database, you can provide the file name with the connect command. If you provide the database type, the utility automatically selects the corresponding default driver.
Close a connection previously opened with the connect command. This command takes no parameters.
Generate the DDL of the specified schema definition. You do not have to be connected to a database to call this command.
Alternatively, you can use generate for this command.
generateSchema schemaType databaseType [[directory] targetSchema] -partition|-nopartition generate schemaType databaseType [[directory] targetSchema] -partition|-nopartition
schemaType - one of the known schema types:
sphere - schema for the sphere database (the sphereDB user)
exm - schema for the transaction database (the transactionDB user)
performance - schema for the performance database (the measurementDB user)
monitorgroup - schema for a monitor group
msglog - schema for the system message log
databaseType - one of the supported database types:
oracle
directory - location to generate the DDL file (defaults to the local directory)
targetSchema -target the generated schema for a specific user, for example sphereDB, transactionDB, or measurementDB.
For example, you have a high-level administrative permissions on the database, but you want to create the schema for someone with much lower-level permissions. You would use something like the following example:
generateSchema sphere oracle \temp sphereUser
-partition | -nopartition
This flag is required if your specified schemaType is performance or monitorgroup. If your specified schemaType is any other value, this flag is not required and is ignored if you use it.
If you are using Oracle Enterprise Edition, you can create a performance or monitorgroup schema that takes advantage of Oracle's partitioning feature by specifying the -partition flag. If you do not want to take advantage of this feature or if your Oracle edition does not provide the partitioning feature, you must specify -nopartition (if you are creating a performance or monitorgroup schema).
Check the status of the specified schema within the connected database
Alternatively, you can use check for this command as the syntax diagram shows.
checkSchema schemaType check schemaType
schemaType - one of the known schema types:
sphere - schema for the sphere database (the sphereDB user)
exm - schema for the transaction database (the transactionDB user)
performance - schema for the performance database (the measurementDB user)
monitorgroup - schema for a monitor group
msglog - schema for the system message log
Use the checkSchema command to check for the specified schema type within a connected database. You must successfully execute the connect command before executing the checkSchema command. The checkSchema command displays the status of the schema as found in the database. If the status of the database schema is not up-to-date, this command displays the differences found, and the DDL you must apply to upgrade the database schema.
This command does not change the database schema. If you wish to automatically upgrade the database schema from this command line utility, use the command upgradeSchema.
Create the specified schema within the connected database. You must successfully execute the connect command before executing the createSchema command.
Alternatively, you can use create for this command.
createSchema schemaType -partition | -nopartition create schemaType -partition | -nopartition
schemaType - one of the known schema types:
sphere - schema for the sphere database (the sphereDB user)
exm - schema for the transaction database (the transactionDB user)
performance - schema for the performance database (the measurementDB user)
monitorgroup - schema for a monitor group
msglog - schema for the system message log
-partition | -nopartition
This flag is required if your specified schemaType is performance or monitorgroup. If your specified schemaType is any other value, this flag is not required and is ignored if you use it.
If you are using Oracle Enterprise Edition, you can create a performance or monitorgroup schema that takes advantage of Oracle's partitioning feature by specifying the -partition flag. If you do not want to take advantage of this feature or if your Oracle edition does not provide the partitioning feature, you must specify -nopartition (if you are creating a performance or monitorgroup schema).
You may want to use the commands checkSchema and upgradeSchema before or instead of the createSchema command.
upgrade the specified schema within the connected database
Alternatively, you can use upgrade for this command.
upgradeSchema schemaType
upgrade schemaType
schemaType - one of the known schema types:
sphere - schema for the sphere database (the sphereDB user)
exm - schema for the transaction database (the transactionDB user)
performance - schema for the performance database (the measurementDB user)
monitorgroup - schema for a monitor group
msglog - schema for the system message log
Use the upgradeSchema command to upgrade the specified schema of the connected database. You must successfully execute the connect command before executing the upgradeSchema command. The upgradeSchema command will add any missing table, column, or index to the database.
You may want to execute the checkSchema command before executing the upgradeSchema command.
Note that the upgradeSchema command only adds missing elements; it does not remove anything. You cannot roll back the upgradeSchema command.
Drop the entire specified schema from the connected database
Alternatively, you can use drop for this command.
dropSchema schemaType drop schemaType
schemaType - one of the known schema types:
sphere - schema for the sphere database (the sphereDB user)
exm - schema for the transaction database (the transactionDB user)
performance - schema for the performance database (the measurementDB user)
monitorgroup - schema for a monitor group
msglog - schema for the system message log
Use the dropSchema command to drop the entire schema from the connected database. You must successfully execute the connect command before executing the dropSchema command.
Warning: the dropSchema command removes all tables and any data stored within these tables. If you have any unsaved data you want to keep from the connected database, export or save the data before executing this command. You cannot roll back the dropSchema command.
Save the database connection information to a file
Alternatively, you can use save for this command.
saveConnection filename save filename
filename - name of the file where you want to save user, password, url, and driver values.
Use the saveConnection command to save user, password, url, and driver values to a file.
Once connected to a database, you might issue the saveConnection command to save the connection information to a file. You can later reconnect to the same database by providing the file name with the connect command. Make sure to remove any unused files as they contain connection information.
Displays the owner of the database instance (service name and UUID)
Alternatively, you can use owner for this command.
checkOwner owner
Once connected to a database, you might issue the checkOwner command to display the service UUID and name that owns the database instance. Only a service owner can connect to a specific database instance. To reset ownership, use the resetOwner command.
Reset ownership of the database instance by removing knowledge of its current owner
Alternatively, you can use reset for this command.
resetOwner reset
Use the resetOwner command to remove the service ownership information associated with a specific database. You must successfully execute the connect command before executing the resetOwner command. Once reset, the next service that accesses the database takes ownership of the database instance.
Export the contents of the given database to a text file containing SQL dml statements in the given database format
Alternatively, you can use dump for this command.
A command to connect must have been successfully executed before this command can be issued.
dumpDatabase schemaType databaseType [directory] dump schemaType databaseType [directory]
Use the dumpDatabase command to export the data contained in the specified schema to a text file containing SQL dml statements that you can use to import into another database. You specify the database type and the text file is formatted into SQL statements supported by that database type.
Note: If your database contains clob fields, they are truncated to 4000 characters in the resulting text file.
schemaType - one of the known schema types:
sphere - schema for the sphere database (the sphereDB user)
exm - schema for the transaction database (the transactionDB user)
performance - schema for the performance database (the measurementDB user)
monitorgroup - schema for a monitor group
msglog - schema for the system message log
databaseType - one of the supported database types:
oracle
directory - where the SQL file is generated. The default location is the local directory.
Use the following command to exit the datastoreUtil utility.
exit
Use the logMerger utility to merge Business Transaction Management system service log files (logdir) for analysis or archiving. You can use the -config flag to load the utility options from a named log merger configuration file. Command line options will override options defined in a configuration file.
The log merger configuration file is described after the discussion of the logMerger utility.
logMerger -config config_file_name |-dir directory|-url url [-username username -password password] [-output output_file_name] [-overwrite true|false] [-format format_pattern] [[-from start_time -to end_time]|[-last number_of_hours]] [-loggerName logger_name] [-loggerLevel level|level+] [-className class_name] [-methodName method_name] [-userName user_name] [-V]
| Name | Description |
|---|---|
| -config | Load options from the named configuration file. Command line options override options defined in the configuration file. For an example of a logMerger configuration file, see Section 11.3.1, "logMerger Configuration File." |
| -dir | Directory that contains Business Transaction Management logdir directory you want to merge. The logMerger utility searches all subdirectories of the specified directory for logdir directories. You can provide multiple -dir directory options. Each directory must be a separate entry. |
| -url | URL of the running Business Transaction Management service whose logdir you want to merge, with the inclusion of the user credentials required to access the service. The logMerger utility will communicate with the service on this URL using the Business Transaction Management user credentials specified by the -username and -password options. You can provide multiple -url service URL options, but all services must have the same username and password credentials. Each URL must be a separate entry.
Note: If you want to merge logging from multiple service URLs that require different username and password credentials for access to each service, you must use a logMerger configuration file. |
| -username | The username credential for access to the Business Transaction Management service associated with the url option.
Note: The -username flag is different from the -userName flag described below; the two flag names are case-sensitive. |
| -password | The password credential for access to the Business Transaction Management service associated with the url option. |
| -output | Specifies where to save the merged result. The logMerger utility will exit without overwriting if the output file already exists, unless the -overwrite option has a value of "true".
If no output option is specified, the resulting output file with be written to the directory from which the logMerger utility was called, with a default value of "logmerger_<date>_<time>.log". |
| -overwrite | Specify true to overwrite existing output file. Default is false. |
| -format | Specify the output format of each log entry in the merged result. Possible format tokens include log entry properties:
and four more special tokens:
Each format token is separated by a plus sign '+'. There is always an End of Line character after each log entry is output. Default format pattern is: |
| -from | Merge log entries with timestamp later than start_time.
Absence of this option means no start time limit unless -last option is specified. Use time format of "MM/dd/yy HH:mm:ss". For example: "10/05/06 00:00:01" |
| -to | Merge log entries with timestamp earlier than end_time.
Absence of this option means no end time limit. Use time format of "MM/dd/yy HH:mm:ss". For example: "10/05/06 17:21:57" |
| -last | Merge log entries from last number of hours.
This option is ignored if -from or -to is specified. |
| -loggerName | Merge only log entries generated by the logger with logger_name. |
| -loggerLevel | If only level is specified, then merge log entries with the specified logger level.
If the level+ is specified, then merge log entries with any level equal to or higher than the specified level. The following SEVERE WARNING INFO CONFIG FINE FINER FINEST |
| -className | Merge only log entries generated by the class with class_name. |
| -methodName | Merge only log entries generated by the method with method_name. |
| -userName | Merge only log entries generated by the user with user_name.
Note: The |
| -V | Display version information for the utility and exit. |
The following example collects log entries under the server \BTM_INSTALL_DIR\btmstorage directory (and all sub-directories below it), sends them to an output file named BTMLoggingOutputTo10_05_06, the overwrite option is set to true, all entries with a loggerLevel of INFO or higher (WARNING, SEVERE) will be collected, with multiple format options, and a date and time range over two-and-one-half days:
logMerger -dir "C:\BTM_INSTALL_DIR\btmstorage"
-output BTMloggingOutputTo10_05_06 -overwrite true
-loggerLevel INFO+ -format time+loggerName+userName+message+eol
-from "10/03/06 00:00:01" -to "10/05/06 12:00:00"
The following example collects log entries under the local machine's directories \BTM_INSTALL_DIR\btmstorage\btmui and BTM_INSTALL_DIR\btmstorage\btmtransaction, sends the entries to an output file named BTMuiNtransactionLoggingOutLast24, the overwrite option is set to true, all entries with a loggerLevel of INFO will be collected, with multiple format options, the utility collects all logging entries generated by the action of a user with the name SalesOpsManager that have occurred over the last 24 hours.
logMerger -dir "C:\BTM_INSTALL_DIR\btmstorage\btmui" -dir "C:\BTM_INSTALL_DIR\btmstorage\btmtransaction" -output BTMuiNtransactionLoggingOutLast24 -overwrite true -loggerLevel INFO -format time+userName+messgae -userName SalesOpsManager -last 24
The following example collects log entries from three URLs:
http://remoteServer1:8080/btmcentral/sphere http://remoteServer1:8080/btmcentral/sphere http://remoteServer1:8080/btmcentral/sphere
The user and password credentials to access these service URLs is the same (otherwise, you must use a configuration file). The log entries are sent to an output file named remoteServiceOutputFrom10_13_06, all entries with a loggerLevel of INFO or higher (WARNING,SEVERE) are collected, with multiple format options, and a date range from one second after midnight on 10/13/06.
logMerger -url "http://remoteServer1:8080/btmcentral/sphere"
-url "http://remoteServer2:8080/btmcentral/container"
-url "http://remoteServer1:8080/btmcentral/agent"
-username BTMAdminUser -password BTMAdminUserPwd
-output remoteServiceOutputFrom10_13_06
-loggerLevel INFO+ -format time+message+eol -from "00:00:01 10/13/06"
The following example uses settings from within a user-defined LogMerger configuration file named myLogMergerConfigFile.xml. Use this option when you frequently use logMerger to collect the same type of information. You can add options to the command line to overwrite the options defined in the configuration file.
logMerger -config myLogMergerConfigFile.xml
The following text contains the formatting and content for a sample log merger configuration file. Options specified in the file will be overridden by command line options.
If you want to encrypt the passwords for accessing remote service URLs via the configuration file, you can use the encryptPassword command.
The attributes defined in the configuration file, which are described in the following subsections, are enclosed in the following:
<ap:logmerger xmlns:ap="http://namespace.amberpoint.com/amf" debug="false"> . . . </ap:logmerger>
Sources Attribute Example and Discussion
<ap:sources>
<ap:source dir="C:/Program Files/AmberPoint/SOAManagementSystem/
server/amberpoint"/>
<ap:source url="http://remoteServerHost1:7001/apcentral/sphere"
username="SMSUser1" password="SMSUserPwd1"/>
<ap:source url="http://remoteServerHost2:7001/apcontainer/container"
username="SMSUser2" password="SMSUserPwd2"/>
<ap:source url="http://remoteServerHost3:7001/eProxy/agent/agent"
username="SMSUser3" password="SMSUserPwd3"/>
<ap:source url="http://remoteServerHost1:8080/apcentral/sphere"
username="ALSMUser1" password="ALSMUserPwd1"/>
</ap:sources>
You can provide multiple source dir entries. Each source directory must be a separate entry.
dir: Directory that contains the Business Transaction Management logdir directory you want to merge. The logMerger utility searches all subdirectories of the specified directory for logdir directories.
You can provide multiple source URL entries. Each source URL must be a separate entry.
url: URL of running Business Transaction Management service. This utility will communicate with the service on this URL using the user credentials specified by the -username and -password options.
username: username to access the Business Transaction Management service
password: password to access the Business Transaction Management service
Filter Attribute Example and Discussion
<ap:filter from="10/02/06 09:00:00" to="10/02/06 11:59:00" last="24" loggerName="com.amberpoint.services.lifecycle.initialize" loggerLevel="INFO+" className="com.amberpoint.util.soa.services.urservice.UrServiceImpl" methodName="createServices" userName="BTMdministrator"
The filter attributes are used to query the log history for messages that contain an exact match of all attributes.
For example, filter attributes of last="24" loggerLevel="INFO" will merge INFO messages logged within the last 24 hours.
If no filter options are specified, then all log messages will be included.
from: log entries with a timestamp later than "from" will be included. Absence of this attribute means no start time limit unless "last" attribute is specified.
Use time format of "MM/dd/yy HH:mm:ss". E.g. from="12/25/05 10:34:25"
to: log entries with a timestamp earlier than "to" will be included. Absence of this attribute means no end time limit.
Use time format of "MM/dd/yy HH:mm:ss". E.g. to="12/25/05 10:34:25"
last: last number of hours of log entries will be included. this attribute is ignored if "from" or "to" is specified.
loggerName: only log entries generated by the named logger attribute will be included.
loggerLevel: this attribute accepts values in two formats: level or level+.
If level is specified, only log entries with the specified logger level will be included.
If level+ is specified, log entries with a level equal to or higher than the specified level will be included.
The following loggerLevel attribute values are listed in order from highest to lowest:
SEVERE
WARNING
INFO
CONFIG
FINE
FINER
FINEST
className: only log entries generated by the specified class will be included.
methodName: only log entries generated by the specified method will be included.
userName: only log entries generated by the specified user will be included.
-->
Output File Example and Discussion
<
<ap:output file="c:\temp\testmerger.log" overwrite="true"
format="time+logName+loggerName+eol+loggerLevel+message"/>
file: where the merged log file will be saved.
The LogMerger utility will stop processing if the output file already exists, unless the overwrite attribute has a value of "true".
Absence of the file attribute will save the merged log file to a new file named logmerger_<date>_<time>.log.
overwrite: allows the utility to overwrite the file specified by the "file" attribute if it already exists. The default value of overwrite is "false".
format: defines the output format of each log entry in the merged result.
Possible format tokens include all log entry properties (attributes on logEntry node in log file).
Examples of log entry properties with values are below:
<logEntry
entryId="1127753975442:0"
time="Mon Sep 26 09:59:35 PDT 2005"
entryType="1"
dataSize="102"
loggerName="com.amberpoint.agent.backplane.servlet.ServletDriver"
loggerLevel="INFO"
methodName="findOldStorageDirectory"
className="com.amberpoint.agent.backplane.servlet.ServletDriver">
There are four additional special tokens:
message: the actual log message
logName: name of the log file that is stored in <logHeader>. The logHeader is used to identify the service that generates the log message.
eol: end of line character to separate text
tab: tab character to separate text
Each format token must be separated by a plus sign.
The LogMerger utility inserts an End of Line character after each log entry that is written to the output file.
Use the showProductInfo utility to collect information about the Business Transaction Management release you have installed on each machine. You should also check this information and report it when dispatching support requests.
The showProductInfo utility reports the following information about the installed product:
release number, build number, and build date associated with the installed product
location of the uninstaller for the installed product
URL for Business Transaction Management support
URL for the product documentation
URL to main Business Transaction Management web site