Configuration File Elements and Attributes

The msghma.dtd file defines the grammar for all the constructs used in an microagent XML configuration file. With this file included, the XML configuration file can be syntax checked using any validating XML parser.

The following tables describe the attributes that can be set in an XML configuration file:

TIBHAWK_AMI Element Attributes
microagent Element Attributes
method Element Attributes
inputParameter Element Attributes
valueChoices Element Attribute
legalValueChoices Element Attribute
constantParameter Element Attributes
outputParameter Element Attributes

The top level element, TIBHAWK_AMI describes transport parameters and tracing attributes that can be applied to all microagents. Some of the attributes can be redefined for an individual method in the method element.

You can specify different transport parameters for each method as attributes of the method element. The attributes of the method element take precedence over those specified by the microagent or TIBHAWK_AMI elements.

TIBHAWK_AMI Element Attributes

Attribute

Type

Description

dtd_type

enumeration

REQUIRED. (MSGHMA).

dtd_version

enumeration

REQUIRED. (1.0).

xml_file_version

string

IMPLIED. Can be used to identify the version of this XML file. It must be in the form of <major>.<minor>.<update>, for example, 1.1.0.

ami_rvd_service ami_rvd_network ami_rvd_daemon

string

IMPLIED. These attributes together configure the TIBCO Rendezvous parameters for creating an TIBCO Rendezvous transport for the communication with the TIBCO Hawk agent.

These attributes are maintained for backward compatibility only and is not used.

rvService

rvNetwork

rvDaemon

string

IMPLIED. These attributes together configure the TIBCO Rendezvous parameters for creating a TIBCO Rendezvous transport.

ems_url

ems_uid

ems_pw

string

These attributes together configure the TIBCO EMS parameters for creating a TIBCO EMS transport.

ssl_trace

ssl_debug_trace

ssl_vendor

ssl_trusted

ssl_expected_hostname

ssl_identity

ssl_identity_encoding

ssl_password

ssl_verify_hostname

ssl_verify_host

ssl_cipher

string

These attributes are used when using SSL to connect to the EMS server.

When specifying values for attributes ssl_verify_hostname and ssl_verify_host, valid values are enabled and disabled.

When specifying values for attributes for ssl_trace and ssl_debug_trace, valid values are true and false.

cmName

cmLedgerName

string

IMPLIED. These attributes together form an RVCM (TIBCO Rendezvous Certified Message) transport. All methods in this microagent that use RVCM use this RVCM transport.

cmName is the RVCM reusable name which represents a persistent correspondent.

If cmLedgerName is specified, it must be a valid file name. The cmLedgerName attribute is ignored if cmName is not specified.

rvAdvisoryTraceLevel

enumeration

IMPLIED. One of: ERROR, WARN or INFO. Specifies the lowest level of TIBCO Rendezvous advisory messages to be tracked by the microagent.

For example, if WARN is specified, then all WARN or ERROR advisory messages are tracked by this microagent.

The default value WARN. If an advisory message not tracked by the microagent is received, it is sent to the microagent standard output if of class WARN or ERROR and discarded if of class INFO.

rvAdvisoryForward

string

IMPLIED. Either true or false. Specifies whether a tracked advisory message must be sent to the TIBCO HAWK Agent as an unsolicited message.

The default is false, which means tracked advisory messages are logged to the adapter's log file.

ftGroupName

string

IMPLIED. Specifies the name of the TIBCO Rendezvous fault tolerance group.

This attribute is maintained for backward compatibility only and is not used.

ftWeight

ftActiveGoal

ftHeartbeatInterval

ftPrepInterval

ftActiveInterval

string

IMPLIED. These attributes together define TIBCO Rendezvous fault tolerance parameters. The default values are:

ftWeight 100.
ftActiveGoal 1
ftHeartbeatInterval 30 seconds
ftPrepInterval 60 seconds

These attributes are used only if the ftGroupName is specified.

These attributes are maintained for backward compatibility only and are not used.

traceFile

traceFileMaxSize

traceFileMaxNumber

traceLevel

string

IMPLIED. These attributes together specify the tracing parameters. If not defined, tracing is sent to stdout.

traceFile. Absolute pathname of the trace file.

traceFileMaxSize. Maximum size (in KB) the trace file is allowed to grow.

traceFileMaxNumber. Maximum number of roll over trace files to be maintained.

traceLevel. Starting trace level.

At least one method must be defined for the microagent.

microagent Element Attributes

Attribute

Type

Description

name

string

REQUIRED. Name for the microagent.

help

string

IMPLIED. Help text describing the microagent. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

displayName

string

IMPLIED. Name that is displayed in the TIBCO Hawk Display.

rvService,

rvNetwork, and

rvDaemon

or

ems_url

ems_uid

ems_pw

ssl_trace

ssl_debug_trace

ssl_vendor

ssl_trusted

ssl_expected_hostname

ssl_identity

ssl_private_key

ssl_password

ssl_verify_hostname

ssl_verify_host

ssl_cipher

string

IMPLIED. These attributes together configure the transport parameters for the microagent.

If any of the attributes are specified differently from those specified for the TIBHAWK_AMI element, a new rvd transport is created and all the methods that belong to this microagent use the new transport.

If the attributes are not specified, the values specified for the corresponding attributes associated with the TIBHAWK_AMI element are used.

When specifying values for attributes ssl_verify_hostname and ssl_verify_host, valid values are enabled and disabled.

When specifying values for attributes for ssl_trace and ssl_debug_trace, valid values are true and false.

cmName

cmLedgerName

string

IMPLIED. These attributes together form an RVCM (TIBCO Rendezvous Certified Message) transport. All methods in this microagent that use RVCM use the RVCM transport.

cmName is the RVCM reusable name which represents a persistent correspondent.

If cmLedgerName is specified, it must be a valid file name. The cmLedgerName attribute is ignored if not specified.

maxThreads

string

IMPLIED. Defines the maximum number of threads a microagent can have to perform method invocations in parallel. The default value is 1.

This attribute is maintained for backward compatibility only and is not used.

traceFile

traceFileMaxSize

traceFileMaxNumber

traceLevel

string

IMPLIED. These attributes together specify the tracing parameters for this microagent. If not defined, tracing is sent to stdout. The attributes override the corresponding attributes associated with the TIBHAWK_AMI element.

traceFile. Absolute pathname of the trace file.
traceFileMaxSize. Maximum size (in KB) the trace file is allowed to grow.
traceFileMaxNumber. Maximum number of roll over trace files to be maintained.
traceLevel. Starting trace level.

These attributes are maintained for backward compatibility only and are not used.

If a method has parameters, the method must have at least one input or constant parameter. If a method has a return value, it must have at least one output parameter.

method Element Attributes

Attribute

Type

Description

name

string

REQUIRED. The method name.

help

string

IMPLIED. Help text describing the method. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

index

string

IMPLIED. If a method returns more than one row of information, the index attribute must be specified with the name of the output parameter which can uniquely identify each row.

If multiple output parameters are required to uniquely identify a row (that is, a composite index), the index attribute must be specified with parameter names separated by commas.

subject

string

IMPLIED. Specifies the subject to subscribe or to publish. For a subscription subject, the subject name segments may contain "*", and the last segment may be ">".

The attribute is required if the first input parameter is not named Subject or if the method publishes RVCM messages.

timeout

string

IMPLIED. The timeout attribute is meaningful (and required) only for RPC methods. If the timeout interval expires and no reply is received, the first return timeout parameter is set to true.

Note that the thread executing the RPC is blocked while waiting for the reply. If a microagent expects multiple simultaneous RPC calls, the maxThreads attribute for the microagent must be adjusted higher accordingly.

heartbeatInterval

string

IMPLIED The heartbeatInterval attribute (in seconds) is meaningful only for publisher methods. If this heartbeatInterval attribute exists, in additional to the normal behavior, at every heartbeat interval, a message is published. Note that this kind of method cannot have inputParameters; only constant Parameters can be used.

handlerType

enumeration

REQUIRED. One of: P, SU, RPC, DS, T or S

Specifies how a method should be handled:

P. Publishers sending messages.
SU. Subscribers receiving messages.
RPC. RPC client sending messages, then waiting for the reply.
DS. Used for the factory provided methods tibrvlisten, tibrvecho and dynamicSubscribe.
T. Used for the factory provided method timeoutTest only.
S. Used for factory provided system methods, which include reviewLedger and shutdown.

For subscriber and RPC methods (with handlerType SU and RPC respectively) the specified fields must have a one to one correspondence with the method’s return (output) parameters.

For publisher methods (with handlerType P and RPC respectively), the message publish subject and all fields must be specified in the message.

useCM

string

IMPLIED. If set to true, the method is an RVCM publisher or subscriber. If not specified, RVCM is not used.

cmListenerList

string

IMPLIED. Only meaningful if the useCM attribute is set to true and the method handlerType value is P (is a publisher method). The cmListenerList attribute specifies a list of cmName names in the form:

<name1>, <name2>, <name3>, ...

For methods with handlerType SU, P, or RPC, if the first inputParameter is named Subject, it is used as the subject for subscription or publish. (Note: In this case, the subject attribute for the method should not be defined.) This allows subjects to be specified at runtime.

For each parameter, you can define either one or more acceptable choices in a valueChoices element, or one or more legal choices in a legalValueChoices element. If one of these elements is included in the parameter definition, users can select method argument values from a dropdown list in TIBCO Hawk Display. If neither is included, the corresponding method argument is represented by an editable field.

inputParameter Element Attributes

Attribute

Type

Description

name

string

REQUIRED. Name for the input parameter.

help

string

IMPLIED. Help text describing the input parameter. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

type

enumeration

REQUIRED. The supported datatypes are:

BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32, STRING, XML

fieldName

string

IMPLIED. Must be in the form of F1[.F2[...[.FN]]] where F1 - FN are the message field names in each nested level.

If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.

See Specifying Field Names in Parameters for details.

pattern

string

IMPLIED. Specifies a pattern to convert string data to a desired form. The pattern syntax is based on the java.text.MessageFormat class specification.

For example, a pattern {0, number} KB could be used to convert a string 123 KB to a number 123 (not a string). If the pattern in the example is {0} KB, a string of 123 is extracted.

Note that only the first argument placeholder (that is, {0..} ) is used to extract the value for the parameter and others are ignored.

An input parameter may have an optional element, valueChoices or legalValueChoices but not both.

The valueChoices element defines some acceptable values for an inputParameter element. These values are included in the dropdown list for method arguments in TIBCO Hawk Display. Users can also type a value not in the list. This element is optional, and can only be used if the legalValueChoices element is not specified

valueChoices Element Attribute

Attribute

Type

Description

value

string

IMPLIED. Defines suggested values. The values are separated by comma characters. For example: 0, 30, 45, 60, 90

The legalValueChoices element defines the only possible values that can be specified in an inputParameter method. This element is optional, and can only be used if valueChoices is not specified. Use this element to limit users to specific values, which are included in the dropdown list for method arguments in TIBCO Hawk Display. Users can only specify values included in the list.

legalValueChoices Element Attribute

Attribute

Type

Description

value

string

IMPLIED. Defines legal values only. The values are separated by comma characters. For example: 0, 30, 45, 60, 90

Constant parameters are not exposed to the TIBCO Hawk Agent or TIBCO Hawk Display. Constant parameter values are passed to the msghma method internally. This type of parameters are used when some fixed constant values need to be passed to msghma methods.

Constant parameters are used to fill in constant value fields in the message.

constantParameter Element Attributes

Attribute

Type

Description

name

string

REQUIRED. Name for the constant parameter.

help

string

IMPLIED. Help text describing the input parameter. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

type

enumeration

REQUIRED. The supported datatypes are:

BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32, STRING, XML

fieldName

string

IMPLIED. Must be in the form of F1[.F2[...[.FN]]] where F1 - FN are the message field names in each nested level.

If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.

See Specifying Field Names in Parameters for details.

For subscriber methods (with method handlerType SU or DS), there are three special outputParameter names:

Subscription Subject. Returns the subject used in the subscription. It can contain wild card characters.
Message Subject. Returns the actual subject used by the publisher to publish the received message.
Reply Subject. Returns the reply subject of the received message. The reply subject is blank if the sender does not specify a reply subject

For RPC methods (with method handlerType RPC), there is a special outputParameter with the name Timeout and type BOOL. It is required and must be the first outputParameter. It is used to indicate whether a timeout has occurred while waiting for the reply.

outputParameter Element Attributes

Attribute

Type

Description

name

string

REQUIRED. Name for the output parameter.

help

string

IMPLIED. Help text describing the input parameter. Each help attribute is paired with a name attribute. If not defined, the name attribute value is used as the help text.

type

enumeration

REQUIRED. The datatypes follow the TIBCO Rendezvous 6.x datatypes convention:

BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32, STRING

fieldName

string

IMPLIED. Must be in the form of F1[.F2[...[.FN]]] where F1 - FN are the message field names in each nested level.

If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.

See Specifying Field Names in Parameters for details.

pattern

string

IMPLIED. Specifies a pattern to convert string data to a desired form. The pattern syntax is based on the java.text.MessageFormat class specification.

For example, a pattern {0, number} KB could be used to convert a string 123 KB to a number 123 (not a string). If the pattern in the example is {0} KB, a string of 123 is extracted.

Note that only the first argument placeholder (that is, {0..} ) is used to extract the value for the parameter and others are ignored.