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.
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 |
||||||||||||
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 When specifying values for attributes for |
||||||||||||
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:
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.
Attribute |
Type |
Description |
||||||||||||
name |
string |
REQUIRED. Name for the microagent. |
||||||||||||
help |
string |
IMPLIED. Help text describing the microagent. Each |
||||||||||||
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 When specifying values for attributes for |
||||||||||||
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.
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.
Attribute |
Type |
Description |
||||||||||||||||||
name |
string |
REQUIRED. The method name. |
||||||||||||||||||
help |
string |
IMPLIED. Help text describing the method. Each |
||||||||||||||||||
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 |
||||||||||||||||||
timeout |
string |
IMPLIED. The Note that the thread executing the RPC is blocked while waiting for the reply. If a microagent expects multiple simultaneous RPC calls, the |
||||||||||||||||||
heartbeatInterval |
string |
IMPLIED The |
||||||||||||||||||
handlerType |
enumeration |
REQUIRED. One of: P, SU, RPC, DS, T or S Specifies how a method should be handled:
For subscriber and RPC methods (with For publisher methods (with |
||||||||||||||||||
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
|
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.
Attribute |
Type |
Description |
name |
string |
REQUIRED. Name for the input parameter. |
help |
string |
IMPLIED. Help text describing the input parameter. Each |
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 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 For example, a pattern Note that only the first argument placeholder (that is, |
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
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.
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.
Attribute |
Type |
Description |
name |
string |
REQUIRED. Name for the constant parameter. |
help |
string |
IMPLIED. Help text describing the input parameter. Each |
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 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.
Attribute |
Type |
Description |
name |
string |
REQUIRED. Name for the output parameter. |
help |
string |
IMPLIED. Help text describing the input parameter. Each |
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 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 For example, a pattern Note that only the first argument placeholder (that is, |