VisiTransact Guide : Commands, utilities, arguments, and environment variables

Commands, utilities, arguments, and environment variables
This appendix provides information about arguments for VisiTransact commands and ORB_init() and environment variables used with VisiTransact.
Overview of VisiTransact commands
The commands in the next few sections relate to one another as described in the following table.
“vbconsole”.
This command starts the VisiBroker Console.
“ots”.
This command starts an instance of the VisiTransact Transaction Service.
“vshutdown”.
This command shuts down an instance of the VisiTransact Transaction Service.
“xa_resdir”.
This command starts an instance of the XA Resource Director, part of the Session Manager.
“smconfig_server”.
This command starts an instance of the Session Manager Configuration Server.
“vshutdown”.
This command shuts down an instance of the XA Resource Director or Session Manager Configuration Server.
“smconfigsetup”.
This utility creates the connection profile for use with the Pluggable Resource Interface for creating a customized Session Manager.
vbconsole
This command invokes the VisiBroker Console, and can be run on any node that has the executable for the VisiBroker Console installed. The VisiBroker Console does not have to be local to the VisiTransact Transaction Service or Session Manager Configuration Server instances that it administers. However, to administer these instances, they must be running when the VisiBroker Console is started.
Syntax
prompt>vbconsole
Example
prompt>vbconsole
Arguments
None.
ots
This command starts an instance of the VisiTransact Transaction Service.
Syntax
prompt>ots [-Dvbroker.ots.defaultTimeout=<seconds>]
  [-Dvbroker.ots.defaultMaxTimeout=<seconds>]
  [-Dvbroker.ots.name=<transaction_service_name>]
  [-Dvbroker.ots.logDir=<directory_name>]
  [-Dvbroker.log.enable=<Boolean>]
  [vbroker.ots.logPurgeTransactions=<true|false>]
  [vbroker.ots.logSleep=<milliseconds>]
  [vbroker.ots.logCache=<cache_size_in_kilobytes>]
  [vbroker.ots.logUnit=<transaction_log_size>]
Example
prompt>ots -Dvbroker.ots.defaultTimeout=60 -Dvbroker.ots.defaultMaxTimeout=120
-Dvbroker.ots.name=Sales -Dvbroker.log.enable=true
Arguments
The following arguments can be used with this command.
To see the debug log statements from this service, set this property to true. For the various source names options for debug log filtering, see the Debug Logging properties section of the VisiBroker for C++ Developer's Guide.
smconfig_server
This command is used to start an instance of the Session Manager Configuration Server. You use the Session Manager Configuration Server as the agent to create a connection profile that accesses your database.
Syntax
prompt>smconfig_server [-Dvbroker.sm.pstorePath=<path>]
[-Dvbroker.sm.configName=<name>] [-m{32|64}]
Example
prompt>smconfig_server -Dvbroker.sm.pstorePath=C:\vbroker\adm\its\session_manager -Dvbroker.sm.configName=athena_smcs -m64
Arguments
The following arguments can be used with this command.
vshutdown
This command can be used to shutdown the VisiTransact Transaction Service, XA Resource Director, and the Session Manager Configuration Server.
If it is used to shutdown an instance of the VisiTransact Transaction Service, it defaults to allow the VisiTransact Transaction Service to wait for outstanding transactions to complete before shutting down, but will not accept any new transactions. You can direct the instance of the VisiTransact Transaction Service to shutdown without resolving transactions by using the optional -immediate argument.
Note
You can use this command to shutdown an instance of the VisiTransact Transaction Service that is embedded within an application process provided the -OTSexit_on_shutdown argument was passed to the application's ORB_init() method. For information about shutting down an instance of the VisiTransact Transaction Service that is embedded in an application process, see “Arguments for applications with an embedded VisiTransact Transaction Service instance”.
Syntax
prompt>vshutdown -help
prompt>vshutdown -type <object_type>
 [-name <object_name>]
 [-host <host_name>]
 [-immediate]
 [-noprompt]
Example
prompt>vshutdown -type ots -name myTxnSvc
Arguments
The following arguments can be used with this command.
Use this argument to display the usage information for this command. If you use this argument, vshutdown ignores all other arguments and just gives you usage information.
ots for VisiTransact Transaction Service
rd for XA Resource Director
smcs for Session Manager Configuration Server
If you specify only the type, vshutdown lists all the services of that particular type and prompts you whether to shut them down or not.
The name of the object to be shutdown. By default vshutdown looks up all the objects of the specified type and prompts you whether to shut them down or not.
The host machine where the service resides that you wish to shutdown. By default vshutdown locates all the objects of a particular type and name (if mentioned) on the network and prompts you whether to shut them down or not.
xa_resdir
This command is used to start an instance of the XA Resource Director. You must have already created a connection profile that accesses your database using the VisiBroker Console.
Syntax
prompt>xa-resdir -Dvbroker.sm.profileName=<profile>
[-Dvbroker.sm.pstorePath=<path>]
[-Dvbroker.sm.configName=<name>]
[-Dvbroker.sm.connectionIdleTimeout=<seconds>]
Example
prompt>xa-resdir -Dvbroker.sm.profileName=quickstart
-Dvbroker.sm.pstorePath=C:\vbroker\adm\its\session_manager -Dvbroker.sm.configName=athena_smcs
Arguments
The following arguments can be used with this command.
VisiTransact utilities
smconfigsetup
The smconfigsetup utility allows you to create connection profiles. The following procedure is provided as a guide when using it to create profiles for use with the Session Manager. The bold type indicates entries from the user. The profile is created upon exit from the smconfigsetup utiltiy.
Creating a profile for use with the Session Manager
To create profile for use with the Session Manager:
1
Enter smconfigsetup at the command prompt.
prompt>smconfigsetup
2
Do you wish to
(0) Quit
(1) Add a profile
(2) List all profiles
(3) List attributes of a profile
(4) Copy a profile
(5) Delete a profile
(6) Create metadata files
(7) Add pluggable data resources

Enter the number of your selection:
1
3
2 known Session Manager implementations:
(0) Oracle OCI 9i DirectConnect
(1) Oracle OCI 9i XA

Please enter the database type you are trying to create:
0
4
Please enter the name for the new profile: quickstart
5
Attribute name "database_name"
New value for attribute Database Name (default value ) :
itso9idb
6
Attribute name "userid"
New value for attribute User Name (default value ) :
scott
7
Attribute name "password"
New value for attribute Password (default value ) :
tiger
8
Attribute name "native_handle_type"
New value for attribute Native Handle Type
(default value <ITSoracle9i_handles>) :
ITSoracle9i_handle
9
Do you wish to
(0) Quit
(1) Add a profile
(2) List all profiles
(3) List attributes of a profile
(4) Copy a profile
(5) Delete a profile
(6) Create metadata files
(7) Add pluggable data resources

Enter the number of your selection:
0

Bye!
The profile is created upon exit from the smconfigsetup utiltiy.
Command-line arguments for applications
You can pass arguments to ORB_init() which affect the VisiTransact Transaction Service and your application components. The following sections explain these options.
Passing command-line arguments to ORB_init() using argc and argv
As a component of VisiBroker, command line arguments are passed to VisiTransact components through the VisiBroker ORB initialization call ORB_init(). Therefore, in order for arguments specified on the command line to have effect on the VisiTransact operation in a given application process, applications must pass the original argc and argv arguments to ORB_init() from the main program. For example,
int main(int argc, char * const* argv)
{
try
{
// initialize the ORB
CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);
}
...
}
The ORB_init() function will parse both ORB arguments and VisiTransact arguments, removing them from the argv vector before returning.
Arguments for applications that originate transactions
By default, the first time you start a transaction with Current::begin(), an instance of the VisiTransact Transaction Service is found using the Smart Agent. You can specify an instance of the VisiTransact Transaction Service to use, and the timeout value for transactions, by using the arguments described in this section.
You pass these arguments at the command line when starting your transactional server manually. Your application handles these command-line input arguments using the ORB_init() method as described in “Passing command-line arguments to ORB_init() using argc and argv”.
The following table explains the arguments that can be passed to ORB_init() from the command line for applications that originate transactions.
VisiTransact uses the specified IOR for the requested Transaction Service (CosTransactions::TransactionFactory) to locate the desired instance of the VisiTransact Transaction Service on the network. This argument enables VisiTransact to operate without the use of a Smart Agent (osagent).
For example, to start the billing C++ transactional server that uses the Accounting VisiTransact Transaction Service, you would use the following command:
prompt>billing -Dvbroker.ots.currentName=Accounting
To start the Billing transactional server that uses the Accounting VisiTransact Transaction Service, and has a timeout period of 2400 seconds, you would use this command
prompt>billing -Dvbroker.ots.currentName=Accounting -Dvbroker.ots.currentTimeout=2400
If you specify a combination of -Dvbroker.ots.currentHost and ‑Dvbroker.ots.currentName, the Smart Agent will find the named VisiTransact Transaction Service instance on the named host. If you specify the ‑Dvbroker.ots.currentFactory with either the -Dvbroker.ots.currentHost or ‑Dvbroker.ots.currentName, the Smart Agent will find the VisiTransact Transaction Service instance by IOR only—it ignores the other arguments.
Arguments for applications with an embedded VisiTransact Transaction Service instance
You can specify an instance of the VisiTransact Transaction Service to use with the arguments described in this section. You can also specify whether your application process will be brought down when the embedded instance of the VisiTransact Transaction Service terminates.
You pass these arguments at the command line when starting your transactional server manually. Your application handles these command-line input arguments using the ORB_init() method as described in “Passing command-line arguments to ORB_init() using argc and argv”.
The following table explains the arguments that can be passed to ORB_init() from the command line for applications that embed an instance of the VisiTransact Transaction Service.
 
Arguments for applications that use the Session Manager
By default, the Session Manager Configuration Server for the machine where the Session Manager connection profile was created is used—<host>_smcs. The persistent store classes are located in <VBROKER_ADM>\its\session_manager by default.
You pass these arguments at the command line when starting your transactional server manually. Your application handles these command-line input arguments using the ORB_init() method as described in “Passing command-line arguments to ORB_init() using argc and argv”.
The following table explains the arguments that can be passed to ORB_init() from the command line for applications that use the Session Manager.
The name of the Session Manager Configuration Server (profileset). By default, this value is <host>_smcs where host is the name of the server on which you created the Session Manager profile.
Environment variables
The following environment variable can be set for VisiBroker VisiTransact.