Tutorial
Introduction
The purpose of this document is to provide you with a tutorial for using the CAMX API. By using the CAMX API, you don't have to write low level code to implement CAMX functionality. Instead, you can simply call API functions to accomplish the following CAMX tasks:
- Publish messages to a CAMX message broker
- Obtain messages from a broker
- Acknowledge messages received from a broker
- Obtain the CAMX Domain Configuration
- Determine which messages to publish
- Send a message directly to a client
- Obtain error information about the last function called
Additional information about CAMX can be found on the IPC Web Site.
Requirements
In order to exchange messages in a CAMX enterprise, you’ll need an CAMX message broker. You can either write your own broker, or obtain one from a third party. The message broker interface is defined and documented through the IPC-2501.
The CAMX API consists of a Microsoft COM object delivered as a DLL (Dynamic Link Library). In order to use the API, your programming environment must be cable of calling functions contained in a COM object. The API has been successfully used with Microsoft Visual Basic version 6.0, Microsoft C++ version 6.0, Microsoft Visual Basic .NET and Microsoft C# .NET.
Preparing the Environment
Prior to using the API, you'll need to configure your environment to access the DLL. Specific instructions for configuring your environment can be found here:
- Microsoft Visual Basic version 6.0
- Microsoft C++ version 6.0
- Microsoft Visual Basic .NET
- Microsoft C# .NET
Once you’ve configured your environment to use the DLL, you’re ready to begin building your application.
Calling an API Function
The API consists of over 200 functions which allow you to accomplish various CAMX tasks. A list of the API functions and links to supporting information can be found here. The conventions used to define the functions can be found here.
All the functions in the API have a similar structure. They accept attributes and return an error level indicating the success or failure of calling the function. Four functions (GetFirstSubscribedMessage, GetLastError, GetMessage, GetNextSubscribedMessage) also return information beyond the error level. An example of calling a CAMX API function is as follows:
Where, an error level of 0, 1, 2, or 3 is returned. An error level of 0 means the function completed successfully. Return values of 1, 2 or 3 means the function encountered a problem during execution. Expanded information about the error level received from a function can be obtained by calling the GetLastError function. The GetLastError function returns the error level, error code and error message associated with the last function called. The values of these parameters can be used to diagnosis problems and accomplish corrective actions.
Every CAMX message contains a dateTime attribute to timestamp the data contained in the message. The dateTime attribute is set through the DateAndTime attribute of the API function used to construct the message. If the DateAndTime attribute is set to a W3C date and time string the string will be used in the CAMX message. If the DateAndTime attribute is set to an empty string or null, the API will automatically generate the message dateTime value.
The API automatically sets the dateTime value contained in the MessageInfo element of the CAMX transmission.
Configuring the API
The first step in using the API is to set the configuration parameters through the SetConfiguration function. The parameter names and their descriptions can be found here. An example of calling the SetConfiguration function is as follows:
Where, Publish.Client, Company.Broker, http://127.0.0.1/Broker, and Test.Domain relate to the configuration and location of the CAMX message broker being used.
The last attribute, ValidateMessages, indicates if messages should be validated by the API prior to being published. If the message is found to be invalid, the message will not be published and an error level of 2 will be returned. Calling the GetLastError function will provide specific information about the invalidity of the message structure. Once you’ve debugged your code, it is recommended that ValidateMessages be set to false since validating messages slows message transfer.
Obtaining Messages from a Broker
To obtain messages from a CAMX message broker, the GetMessage function is used. Here’s an example of calling the GetMessage function:
If a message is returned by the broker, it will be contained in the “Message” attribute return value. The data from the MessageInfo element of the CAMX transmission will be available through the MessageInfoDateAndTime, MessageInfoSender, MessageInfoDestination, MessageInfoMessageId and the MessageInfoMessageSchema attributes. If a message is not returned by the broker, the return values will contain empty strings.
Acknowledging a Message
The transfer of messages between entities in a CAMX environment is acknowledged to guarantee their delivery. As a result, all messages received by a client through the GetMessage function must be acknowledged through the Acknowledge function. Here’s an example of calling the Acknowledge function:
Where, “Message101” is the MessageId of the last message received. The MessageId is obtained from the MessageInfoMessageId return value of the GetMessage function. If the message received from the broker is not acknowledged, the broker will continue to deliver the same message to the client until the message is acknowledged.
Publishing Messages
Publishing messages to the broker consists of calling one or more functions. A single function is used to publish a single element message, and multiple functions are used to publish multiple element messages. A list of the CAMX messages that can be published with the API (and the corresponding functions used to publish them) can be found here.
Publishing a Single Element CAMX Message
The function used to publish a single element message consists of the word ‘Publish” prefixed to the message name. Here’s an example of publishing a single element message:
By calling this function, a CAMX EquipmentWarning message will be published to the message broker.
Publishing a Multi-Element CAMX Message
If the message to be published contains multiple elements, then three or more functions must be called to publish the message. The first function called consists of the word ‘New’ prefixed to the message name (i.e. NewEquipmentAlarmExtended). Then, one or more ‘Append’ functions (i.e. AppendEquipmentOutOfItem) are called. Finally the ‘Publish’ function is called. When publishing a multi-element message, please note the following:
- You should review the schema of the message you're attempting to publish to determine the correct message structure.
- ‘Append’ parent element functions must be called prior to calling ‘Append’ child element functions. For example, AppendEquipmentOutOfItem must be called prior to calling AppendItem since the ‘EquipmentOutOfItem’ element is the parent of the ‘Item’ element.
- ‘Append’ functions can be called in any order as long as the parent element has been appended before the child element is appended.
- Not all the ‘Append’ functions associated with a message will be used to publish a message since only one branch of a message may be populated. For example, if the ProcessDataReport branch of the EquipmentInformationExtended message is to be populated, then only the AppendProcessDataReport and AppendParameter functions would be used.
- The location attribute of an ‘Append’ function indicates where the data should be appended in the messages structure. The value of the attribute should be a valid XPATH expression (i.e. “/EquipmentAlarm/EquipmentOutOfItem” should be used if data is to be added to the EquipmentOutOfItemElement of the EquipmentAlarmExtended message).
- The 'Publish' function contains an extensions attribute which can be used to extend a message.
- The 'New' function is always called first.
- The 'Publish' function is always called last.
Publishing a Nonstandard XML Message
If you desire to publish a nonstandard CAMX message, the PublishMessage function can be used. The PublishMessage function receives the xml message to publish and the URL of the message as input attributes. An example of using the PublishMessage function is as follows:
Obtaining the Domain Configuration
The CAMX Domain Configuration defines how the message broker is currently configured and how messages are to be exchanged among the clients participating in a CAMX domain. To obtain the Domain Configuration from the message broker, simply issue the GetDomainConfiguration function. Here’s an example:
Where, the Domain Configuration is returned through the last attribute.
Determining which Messages to Publish
CAMX clients should only publish messages which are subscribed to be other clients. If a client publishes a message that has not been subscribed to, the message broker will respond with an Unnecessary Publishing error code. The messages which a client should publish can be determined by parsing and processing the Domain Configuration or by using the GetFirstSubscribedMessage and the GetNextSubscribedMessage functions. Calling the GetFirstSubscribedMessage function returns the first message in the list of messages that your client should publish. Calling the GetNextSubscribedMessage function recursively will return the remaining messages in the list. When the GetNextSubscribedMessage returns a null value, the end of the list has been reached.
Sending a Message Directly to a Client
In addition to publish-and-subscribe communications, the CAMX API can also be used for point-to-point communication. To send a message directly to another client, the SendMessage function can be used. An example of sending a message directly to another client is as follows:
Where, Consume.Client is the receiving client.