DOC-2201

Generated by Clearspace on 2011-01-25-06:00

1

Understanding BW engine properties

Note to the reader:For many property declarations discussed in this article, we followed the property withparentheses that enclose a comment for explanation. If you choose to add a property witha comment within parentheses to your property file, you must remove the parentheses andadvance each comment with a comment tag in order to prevent unnecessary syntax errors.

InroductionThe BW engine uses two flavours of properties:

1. java.property.<propname> -- which is loaded by the wrapper(i.e bwengine.exe)2. <propname> -- which is picked by the engine

The wrapper loads its properties from a file specified by --propFile while the engine loads itsproperties from a file specified by -p.

When running the engine in debug mode (i.e. through Designer), the properties can be put ina file, such as "properties.cfg", and loaded when the engine is launched as -p properties.cfg.When you launch the tester engine, go to the Advanced Test Settings tab and specify theproperties file as shown below.

By default, the tester engine in Designer loads the properties file(properties.cfg) to the<TIBCO_HOME>/designer/5.x directory. Some properties of the form 'java.property.*' needsto be specified in the designer.tra file as they are loaded by the wrapper, in which caseDesigner must be restarted for the properties to take effect. In contrast, any changes madeto the engine properties specified with the -p flag should take effect simply by restarting thetester.

http://www.tibcommunity.com/plugins/SupportGuidesArticles/resources/bw/EngineProperties/props.JPG



2

When running the engine from the command line, all properties can be placed in one file(e.g. myengine.tra) using the template "bwengine.tra". In the .tra file, you must edit theproperty tibco.env.APP_ARGS to point to itself. For example, if "myengine.tra" is in C:/temp,then the property would be

tibco.env.APP_ARGS=-p C:/temp/myengine.tra

Start the engine as

>bwengine --propFile myengine.tra <repo>

to load the engine with the properties declared in "myengine.tra".

If deploying the engine to a domain, the properties set in the Admin GUI under the processarchive should be added to the deployed engine's .tra file.

To manage custom properties in the Admin GUI, you must add them to the "bwnegine.xml"file under <TIBCO_HOME>/bw/5.x/lib/com/tibco/deployment before creating

the application archive (EAR) file. For example,

<property>

<name>JDBC Idle timeout</name>

<option>java.property.bw.engine.dbConnection.idleTimeout</option>

<default>5</default>

<description>controls JDBC idle timeout in minutes</description>

</property>

[Note: Properties set in the "bwengine.xml" file will be visible in the Admin GUI formodification.]

Tracing, Logging and Debugging

Log File and Directory PropertiesEngine.Log.Dir=logs (directory to which log files are written)



3

Engine.Dir=./testDir (alternate method to specify the log directory)

Engine.Log.MaxSize=20480000 (setting the maximum size for the log file in bytes)

Engine.Log.MaxNum=5 (specifying the maximum number of log files -- a rollover feature)

Roles

Info

Debug

Warn

Error

userrole (used in 'Write to log' activity)

Sinks

Term (terminal or console)

Log #log file

Publish #RV sink

Tracing

Trace.<role>.Term

Trace.<role>.Log

Trace.<role>.Publish

where

role = Info,Debug,Warn,Error,Role.<userRole>

(note how a user defined role is specified as "Role.<userRole>")

Trace.<role>.Publish.Subject

Trace.<role>.Publish.Service



4

Trace.<role>.Publish.Daemon

Trace.<role>.Publish.Network

Enabling/Disabling the Roles:

Trace.<role>.* (enables/disables the specified system role)

Trace.Role.<userRole> (enables/disables specified user-defined role)

Trace.Role.* (enables/disables all user-defined roles)

Tracing for Different Components of BW:

Trace.Startup (tracing during engine startup)

Trace.Engine (tracing when job enters process flow)

Trace.JC.* (tracing for all process starters)

Trace.JC.<ProcessFlowName> (tracing for a specific process starter)

Trace.JC.ProcessFlows/MyPr1.process=true (example)

Trace.Task.* (tracing for all tasks)

Trace.Task.<ProcessFlowName>.* (variation)

Trace.Task.ProcessFlows/MyPr1.process.*=true (example)

Trace.Task.<ProcessFlowName>.<ActivityName> (variation)

Trace.Task.ProcessFlows/MyPr1.process.RVPub=true

Example

Trace.Task.ProcessFlows/MyPr1.process.<GroupName>/<ActivityName>=true

[Note: when the activity is inside a group, the above example will not work.]

Specifying Rolling Log Files for UserRole:

Trace.Role.<userRole>.Log.Dir (location for the set of rolling log files)



5

Trace.Role.<userRole>.Log.File (file name for the log files)

Trace.Role.<userRole>.Log.MaxSize (sets the maximum size of a log file)

Trace.Role.<userRole>.Log.Maximum (specifies the maximum number of log files to create)

All Activitiesbw.engine.showInput (available from BW 5.3 onwards)

bw.engine.showOutput (available from BW 5.3 onwards)

SOAP Tracingjava.property.com.tibco.plugin.soap.trace.inbound=true

java.property.com.tibco.plugin.soap.trace.outbound=true

java.property.com.tibco.plugin.soap.trace.filename=C:/files/support/soapLogging/ soap.txt

java.property.com.tibco.plugin.soap.trace.pretty=true

java.property.com.tibco.plugin.soap.trace.stdout=true

WS-Security Tracinglog4j.logger.com.tibco.spin=DEBUG, tibco_bw_log

log4j.logger.com.tibco.security.tibcryptx.wss=DEBUG, tibco_bw_log (enables the above inlog4j.properties file in conjunction with t he soap tracing properties above)

RV AdvisoriesTrace.RV.Advisory.Error=true (error advisories are logged by default)

Trace.RV.Advisory.Warn=false

Trace.RV.Advisory.Info=false



6

Engine Properties

Worker ThreadsThe default number of worker threads is 8. On a multi-CPU machine, the number of threadscan be increased. The user should empirically determine the optimal thread value for theirdeployment as too many threads can cause resource contention. The recommended valueis 8 threads per CPU:

Engine.ThreadCount=8

StepCount PropertyThe StepCount property controls the maximum number of execution steps (unless insidea transaction) for a job before an engine thread switch occurs. The default value of thisparameter is 20. Frequent thread switching can cause engine performance degradation.But when a process instance keeps the tread too long, this may cause less concurrencyfor executing process instances and hence inefficient use of CPU.Therefore, it is difficultto determine the correct value for this property. The default value is sufficient for mostsituations. But if your process definitions contain a large number of activities (and especiallyif they contain a large number of activities in iteration loops), you may benefit from settingthis property to a higher value.

Engine.StepCount=20

Flow ControlThose are flow control-related properties. Detailed explanation of those properties can befound in the TIBCO Admin Users Guide, Chapter 8 (Setting deployment options), under thesection titled "Changing TIBCOBW process configuration properties".

MaxJobs.ProcessFlows/PrRVSubscriber.process=5 (0 by default)

FlowLimit.ProcessFlows/PrRVSubscriber.process=10 (0 by default)

ActivationLimit.ProcessFlows/PrRVSubscriber.process=false ("true" by default)

ActivationLimit.ProcessFlows/Pr\ RVSubscriber.process=false ("true by default)



7

Memory Saving Mode - BW Garbage Collection (not Java)Memory saving mode can reduce memory usage by actively running process instances aswell as potentially improving the performance of checkpoints. Note that is a BW ProcessVariable garbage collection and not the Java garbage collection.

EnableMemorySavingMode.*=true (for all process flow)

EnableMemorySavingMode.<processName>=true (for specific process flow)

Both properties above are "false" by default

JobId Block SizeWhen an engine starts up, it reads a job id block size from the DataManager. Each newlycreated job is assigned an id from this block. By default, the value of the JobIdBlockSize is1000:

Engine.JobIdBlockSize=1000

Engine TerminationIf you wish to terminate the engine when the "Process initialization failed" error isencountered during engine startup, set the following property to "true":

Engine.ShutdownOnStartupError=true

The default of the property above is "false".

FT-Related PropertiesEngine.FT.UseFT=true

Engine.FT.Weight=100

Engine.FT.HeartbeatInterval=3000

Engine.FT.ActivationDelay=6000

Engine.FT.ActivationInterval=10000



8

Engine.FT.GroupName=RUDRA.xyz

Engine.FT.Subject=RUDRA.Test.Process (optional, if not used, subject=FT.<GroupName>)

If you wish to perform FT-level debugging, you can listen on the following

subject for FT heartbeats:

tibrvlisten "_RVFT.ACTIVE_HB.<FT subject name>"

FT transport configuration:

To use non-default values for FT transport, set the following properties:

Bus.Default.Service=6532

Bus.Default.Daemon=tcp:6532

Bus.Default.Network=;

In some situations where a database is used as the data manager for process engines, aunique constraint violation is thrown. If such an error is encountered, set the property belowto "false".

Engine.StandAlone

By default, the property above has a value of "true".

DupKeyThe following three process engine properties control duplicate key detection:

• bw.engine.dupKey.enabled

This property controls whether duplicate detection is performed. By default, this property isset to "true".

• bw.engine.dupKey.timeout.minutes

This property specifies how long (in minutes) to keep stored duplicateKey values. Thedefault value of this property is 30 minutes. The value "-1" indicates that the duplicateKeyvalues are deleted when as soon as the job is completed. The value "0" forces the storageof duplicateKey values indefinitely. Positive integers greater than 0 determine the thenumber of minutes to keep stored duplicateKeys.



9

• bw.engine.dupKey.pollPeriod.minutes

This property specifies the number of minutes to wait before polling for expired duplicateKeyvalues.

DataManager/Checkpoint Database PropertiesEngine.UseDatabase=true (the default value is "false", implying file-based data manager)

File-based DataManager - working directory:

If using file-based data manager, you can specify the name/location using the followingproperty:

DataManager.Directory=<dir> (absolute or relative path)

The default value for this property is 'working'

An alternate (and recommended) way to specify the location of the data manager directorycan be accomplished with the following property:

Engine.Dir=C:/MyProject

Note that when using the Engine.Dir property, it will always create a directory named'working' under the specified location. The 'log' directory is also created under the samelocation.

DB-based DataManager:

There are two ways to specify the database connectivity details:

• The simplest way is to use a 'JDBC Connection' resource from the BW project:

Engine.Database.Configuration=/SharedConfig/JDBCOra

• An alternate way is to use the following set of properties:

Engine.Database.Location=jdbc:oracle:thin:@jones:1521:icjones

Engine.Database.Driver=oracle.jdbc.driver.OracleDriver

Engine.Database.User=oratest

Engine.Database.Password=oratest



10

Engine.Database.MaxConnections=10

DB DataManager table names:

The property below sets the Tablename prefix.

Database.Tablename.Prefix=tab

Setting the Tablename prefix is more than sufficient. However, the following properties areoptional:

Database.DataManager.Internal.Table=tab_internal

Database.DataManager.Job.Table=tab_job

Database.DataManager.Job.DupTable=tab_duplicates

Database.WaitNotify.Wait.Table=tab_wait

Database.WaitNotify.Notify.Table=tab_notify

Hawk

Enabling/Disabling HawkHawk.Enabled=true

true - enables both TIBCO Hawk and Engine Command activity usage.

false - disables both TIBCO Hawk and Engine Command activity usage.

local - only enables Engine Command activity (TIBCO Hawk will be disabled).

Hawk TransportHawk.Service=7474 (default udp port is 7474)

Hawk.Daemon=tcp:7474 (default tcp port is 7474)

Hawk.Network=; (default network value is ;)



11

Hawk Display NameHawk.AMI.DisplayName=Test.bwengine #default name is com.tibco.pe.<engineName>

Performance StatisticsSet the following property to collect statistics for various activities in a process flow atruntime:

Instrumentation.*=true

Instrumentation.<processName>=true (for a specific process flow)

[Note: be advised that setting the instrumentation property can cause performancedegradation and memory overhead.]

When you enable instrumentation, it allows you to execute the following Hawk methods:

• Collection of activity statistics using GetActivity micro-agent method• Calls to OnProcessActivity and OnProcessStatusChanged micro-agent methods

The instrumentation property can be set at runtime by calling the TIBCO HawksetInstrumentProperties method. The property value specified in a call tosetInsrumentProperties will take effect immediately.

Other (Non-activity) Specific Properties

Memoryjava.extended.properties -Xms768m -Xmx768m -verbose:gc

Enable Remote Debugging from IntelliJ and Other IDEsjava.extended.properties -Xdebug -Xnoagent -Djava.compiler=NONE

Example:

-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005



12

Global Variable Substitutiontibco.clientVar.<global var>=test

tibco.clientVar.mySubject=test.xyz

Repository Connection - Remote/Localtibco.repourl=C\:/tibco/tra/domain/amxdom/datafiles/RVCMQtester_root

tibco.deployment=RVCMQtester

tibco.domain=Test

tibco.username=admin

designer.tra prop to point to prop filejava.property.testEngine.User.Args -p c:\\tibco\\properties.cfg

Active Enterprise Adapter Activities

Publish to Adapter ActivityTimeout for 'Publish to Adapter' activity when used in a request/reply mode:

bw.plugin.ae.publishReqRepTimeout (specified in milliseconds)

FTP ActivitiesIf you wish to strip the line feed character (\n) when executing FTP PUT command, you mustset the following property to "true":

bw.plugin.ftp.stripLineFeedInPut=false (the default setting is "false")

File activitiesWhen a file is saved on a Windows platform using UTF-8 encoding, the Windows OS addsa Byte Order Mark (BOM) to the beginning of the file. This BOM is not necessary for UTF-8,



13

but it is valid nonetheless. Prior to release 2.0.6, the File Reader activitys output will includethe BOM at the beginning of the data read from the file.

The property below will strip the BOM from the file when encountered. Its default value is"true". Thus, if you wish to retain the BOM, you set this property to "false"

java.property.DiscardUTF8BOM=false

General activities

Wait-NotifyBy default, the Wait-Notify activity will use the following settings for its transports:

Bus.Default.Service

Bus.Default.Network

Bus.Default.Daemon

These are the same settings used by other components of the engine, including FT, RVsink, etc. If you wish to give explicit settings for Wait-Notify transports, use these settingsinstead:

WaitNotify.Service

WaitNotify.Network

WaitNotify.Daemon

External CommandUse the following property to set the thread pool for the External Command activity:

CmdExec.ThreadCount=5

TimerBefore BW release 5.2.0, the Timer process starter used the Java convention (0-11) for thenumber of months in its output; however, the expected convention for the number of months



14

is 1-12. In release 5.2.0, the month is returned as a number between 1 and 12. If you wish tomaintain backward compatibility, set the following property to "true":

bw.plugin.timer.useJavaMonth

HTTP activities

Threads for Incoming HTTP RequestsThe property below sets them minimum and maximum number of threads for incomingHTTP requests. By default, the minimum and maximum thread value is set to 10 and 75,respectively.

bw.plugin.http.server.minProcessors=10

bw.plugin.http.server.maxProcessors=150

bw.plugin.http.server.acceptCount=10

Connection PoolingThe following properties are used to set connection pooling and configure the number ofconnections in the pool:

bw.plugin.http.client.usePersistentConnectionManager (flag to turn on connection pooling)

bw.plugin.http.client.maxConnectionsPerHost (maximum connection to each remote hostwith a default of 20)

bw.plugin.http.client.maxTotalConnections (maximum connection for all HTTP server with adefault of 200)

bw.plugin.http.client.checkForStaleConnections (check for stale connection in the pool)

Request-Response Thread PoolEach HTTP request is executed in a separate thread belonging to a thread pool associatedwith the activity. The number of threads in the pool determines the maximum number ofconcurrent requests a HTTP request/response activity can execute. The following propertysets the number of threads in the pool:



15

bw.plugin.http.client.ResponseThreadPool

The default value of this property is 10.

Default HostSet the following property to specify the name of the default host that must be used whenthe machine has multiple domains or IP addresses, noting that it takes either the host nameor its IP address as its value:

bw.plugin.http.server.defaultHost

Encode QueryStringAs of BW release 5.2.0, the QueryString input element of the Send HTTP Request activityis not automatically URL-encoded. This was not the case in prior releases. Therefore, thischange may cause backward compatibility issues, if you rely on the activity to perform theURL-encoding of the QueryString. If set to "true", the following property will revert to thebehavior of previous BW releases.

bw.plugin.http.client.urlEncodeQueryString

HTTPS/SecurityThis property defers client authentication and outputs the clients security context when theclient connects to the server using HTTPS:

bw.plugin.https.server.deferClientAuthentication

To specify the "entrust" security or "JSSE" vendor, set the following properties:

java.property.TIBCO_SECURITY_VENDOR=entrust61

java.property.TIBCO_SECURITY_VENDOR=j2se

Idle Connection TimeoutBy default, connections in a pool will close after idle timeout period of 5 minutes. If you wishto set a different idle timeout (in minutes), use this property:

java.property.bw.engine.dbConnection.idleTimeout



16

Login TimeoutThe property below refers to time-to-wait (in seconds) for a successful database connection.Only JDBC drivers that support connection timeouts can use this property; otherwise, it isignored. The value of this property overrides any value set for connection timeouts in the"Configuration" tab of the JDBC Connection resource.

Config.JDBC.Connection.SetLoginTimeout

Setting Optional ParametersOptional parameters for a call procedure activity have never been supported, but wasallowed in BW releases prior to 5.2. Thus, when migrating a project from a pre-5.2 release,there will be validation errors for any unspecified input elements for stored procedureparameters. These migrated projects cannot be executed until such errors are resolved. Ifyou wish to migrate a project without resolving this issue, you must set the following propertyto "true"

Config.JDBC.CallProcedure.InputOptional

Set Output NilPrior to BW release 5.1.2, if a value returned from a database table was null, the outputelement corresponding to that table value was not included into the output schema for aJDBC Call Procedure activity if the output element was optional. The element will be placedinto the output schema with "xsi:nil = true" to indicate the element is null. In order to achievethe behavior of previous Pre-5.1.2 releases, you must set the property below to "false".

Config.JDBC.CallProcedure.OutputUseNil

Test StatementWhen a SQL error occurs during statement execution, BW will execute a test SQLstatement to determine if the error is caused by a bad connection. If the error is due toa bad connection, the statement then can be re-executed using a different connectionin the connection pool.The SQL test statement is unmodifiable for Oracle, Sybase, SQLServer, or DB2 databases. However, the property below should allow you to specify SQLtest statement for databases other than those cited above. All you need to do is specify thedatabase name and set the value of the property to a valid SQL statement.

Engine.Database.TestStatement.<name>=<sql statement used to test connection>



17

Recover Startup ErrorWhen a process engine containing JMS process starters attempts to startup while the JMSserver is not running, the initialization of such process flows will fail. Setting the followingproperty to "true" allows the process engine to start and the JMS process starters will waituntil the JMS sever is up and running before starting:

bw.plugin.jms.recoverOnStartupError

ReconnectionThe property below is used in conjunction with FT URL setup in JMS shared connection. Forthis property to take effect, you need EMS client API 4.2 or higher, which means that thisproperty will have no effect for BW releases 5.1.3, 5.2.0, etc. The syntax for the followingproperty is 20 attempts within a span of 5000 milliseconds:

java.property.com.tibco.tibjms.reconnect.attempts 20,5000

Java ActivitiesBy default, the Java Code activity uses the system encoding. It does not use the encodingset in Designer or Administrator. To use a different encoding, for instance UTF-8, use thefollowing property in "designer.tra" or "bwengine.tra":

java.extended.properties=-Dfile.encoding=UTF-8

Mail activitiesThis discission referrs to the Java Mail API properties.

Since we use the SMTP provider from Sun, the following Java properties can be used:

mail.smtp.connectiontimeout(Socket conn timeout(ms),default is infinite timeout)

mail.smtp.timeout(Socket I/O timeout(ms),default is infinite timeout.)

The following are not BW properties; they are standard Java Mail API properties.

java.property.mail.debug=true (throws debug information about mail to stdout)

java.property.mail.smtp.auth=false (sets smtp authentication to "false")



18

A new property to handle discrete media types (RFC2047). It handles four top-level mediatypes (including image/*, application/*, audio/*, video/*), assuming that the message hasonly one binary part. This property has to be set to "true".

bw.plugin.mail.receiverHandleDiscreteTypes

A new property to flatten multiple nested mime sub-parts under any mime part. This propertyhas to be set to "true" as well.

bw.plugin.mail.receiverFlattenNestedAttachments

The following property allows you to specify the number of times the Receive Mail processstarter will attempt to receive the same message. The amount of time allotted for re-trials willbe the value of this property multiplied by the polling interval.

bw.plugin.mail.receiverRetryCount

Mapper ActivitiesThe "Mapping Wizard" was creating empty tags for each optional element, even if theoptional elements did not appear in the input data. To avoid the empty tags in the outputwhen the input did not contain the optional element, the user had to manually create "xsl:if"statement. A new system property "automatic_mapper_if_surround" is added to fix thisproblem.

Set this the following property to "true" in the designer.tra file in order to surround all newoptional-to-optional mappings (including child elements) by an xsl:if statement. If the systemproperty is set to "false" (or entirely absent) , child elements will not be surrounded with thexsl:if statement.

java.property.automatic_mapper_if_surround=true

Parse Data ActivitiesIf the line length is 2000 and the data format length is 100 and where the entire data ison one line, the expectation is that the parser would yield after 200 lines of the structuredefined in the data format. Adding the property below and setting its value to "true" will fixthe problem.

bw.plugin.parseData.enforceLineLength



19

RV transport

RV TransportTo use non-default values for RV transport, set these properties:

Bus.User.Service=7501

Bus.User.Daemon=tcp:7501

Bus.User.Network=

SOAP Activitiesjava.property.com.tibco.plugin.soap.RetrieveResources.IgnoreInputHostForImportLocations=true

java.property.com.tibco.plugin.soap.RetrieveResources.IgnoreInputHostForWsil=tru e

TCP ActivitiesTo Specify Accept Count (i.e. Connection Queue length) for TCP Server, set the followingproperty, noting that 50 is the default setting:

bw.plugin.tcp.server.acceptCount=50

XML Activitiesjava.property.com.tibco.bw.use.old.validator true

java.property.com.tibco.xml.use.old.render.code true

java.property.com.tibco.schema.ae.makeNillable true

java.property.com.tibco.xml.schema.preserve-boolean-lexical-value=true

Set the last property in designer.tra and then run the tester in Designer to enable theproperty. After adding it, you should see that boolean "0" will not be changed to "false".

DOC-2201

Documents

Transcript of DOC-2201