Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 5 Using the TIBCO Hawk Messaging Microagent : Configuration File Elements and Attributes

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:
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.
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.
At least one method must be defined for the microagent.
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.
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.
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.
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.
The attribute is required if the first input parameter is not named Subject or if the method publishes RVCM messages.
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.
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.
DS. Used for the factory provided methods tibrvlisten, tibrvecho and dynamicSubscribe.
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.
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:
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.
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.
If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.
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
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.
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.
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.
If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.
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.
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.
If the fieldName attribute is not specified, it is assumed to be the same as the name attribute.
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.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved