MessageAsString Method (MessageLog2 Interface)

                    

 

The MessageAsString method takes the arguments used to construct a template based message (as used in SendLogMessage) and returns a string formatted as the PI Message Subsystem would format the message.  This allows an application to display the contents of a message it is logging.

Syntax

object.MessageAsString msgID, nvTemplateParams, nvMessageParams

The MessageAsString method syntax has these parts:

Part Description
object An object expression that evaluates to a MessageLog2 interface.
msgID A long integer representing the template identifier from the OSIsoftTemplateMessages.htm file or 0 for a plain text message.
nvTemplateParams

A NamedValues collection of values to be inserted in a template message replacing the template's placeholders.  The NamedValues collection should have its Sorted property set to false and the parameters should be added in the order they appear in the template.  The name portion of each NamedValue contained is not currently needed but for consistency and debugging purposes, you should name the first NamedValue “1”, the second NamedValue “2”, and so on.  For messages sent with a msgID of 0, the first NamedValue in the collection should contain the complete text of the desired message.

nvMessageParams

A NamedValues collection containing additional information about the message being sent.  Only a specific set of message parameters are supported so the names are fixed.  These names are shown in a table below however an easier way to supply this name is to use the IMessageSendNames interface (available as a property of the MessageLog2 object) whose properties are named for the supported parameters and the property returns the official string used to specify the value.  This parameter may be NULL if no message parameters are being provided.

Settings

The possible values in the nvMessageParams argument are:

Name Data Type Meaning
Category String The category message parameter is provided to allow the programmer to specify a text string with a message that can be used to group similar messages.  The value passed can be any string leaving it to the programmer to determine useful categories.
OriginatingHost String

An originating host represents the fully qualified domain name (FQDN) of the machine sending a message as determined by an application.  The SendLogMessage method will automatically add the ProcessHost to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log it is assumed the process host is the same as the host of the PI Message subsystem and this parameter is not logged.  However in some cases, such as an application server, the machine where the application is running (the process host) may not be the machine that the message pertains to.  In this case the application may choose to use the OriginatingHost property of a message to clearly define the source of the message.

OriginatingOSUser String
An originating O/S user represents the user sending a message as determined by an application.  The SendLogMessage method will automatically add the ProcessOSUser to each log message.  However in some cases, such as an application server, the user associated with the application's process may not be the user that the message pertains to.  In this case the application may choose to use the OriginatingOSUser property of a message to clearly define the sender or related user of the message.

OriginatingPIUser String An originating PI user represents the authenticated PI user sending a message as determined by an application.  The SendLogMessage method will automatically add the ProcessPIUser to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log the PI-SDK can not determine the proper PI user so this property is not added automatically though can be explicitly sent by an application.  In some cases, such as an application server, the PI user associated with the application's process may not be the PI user that the message pertains to.  In this case the application may choose to use the OriginatingPIUser property of a message to clearly define the authenticated PI user sending the message or related to the message's contents.
Priority Integer The Priority property of a message is an integer between 1 and 10 (1 being the most important - "highest priority")that is used by an application to define the order in which a message condition should be handled relative to other messages.  Unlike severity, which defines the criticality of a message, priority is intended to indicate ordering of corrective action.  Priority is always an optional part of a message as only an application can determine if it is needed and what its value should be.
ProcessHost String The process host represents the fully qualified domain name of the machine sending a message. SendLogMessage method will automatically add the ProcessHost to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log it is assumed the process host is the same as the host of the PI Message subsystem and this parameter is not automatically logged but can be added by an application.
ProcessOSUser String The ProcessOSUser represents the authenticated user of the application which is logging the message. This parameter is automatically added to all messages sent with MessageLog2.SendLogMessage.  This is typically the intended sender of the messaage however this is not always the case. For applications that do impersonation, the identity of the impersonating thread posting a message may differ from the process identity.  This is because different threads may have different identities and also because the request to log may be invoked on one thread but is executed on the thread where the MessageLog2 object was instantiated (for single threaded apartment objects such as the MessageLog and MessageLog2).  For this reason only the process identity is automatically recorded. The application can override the ProcessOSUser parameter for this case.   Even without impersonation it is also possible that an application is doing work, and logging a message in that regard, on behalf of a different user (application servers behave this way).  For this case the application can specify the OriginatingOSUser field when sending a message to provide a more accurate picture of the message context.
ProcessPIUser String The ProcessPIUser is the authenticated PI user associated with a message being logged. SendLogMessage method will automatically add the ProcessPIUser to any log message sent to a PI server's Message log (remote messages).  When sending messages to the local log the PI-SDK can not determine the proper PI user so this property is not added automatically though can be explicitly sent by an application.  If an application is doing work on behalf of a PI User not associated with the server connection being used to log a message, the OriginatingPIUser message property should instead be sent.
SeverityOverride Integer Template messages have an associated Severity code statically assigned to them.  If the message sender wishes to override the severity of such a message or provide a severity for a message that does not use a template they may add this parameter.  The allowed values are shown below. Either the numeric or the constant from the MsgSeverityConstants enumeration can be sent.
Source1 String Log messages sent with the PI-SDK automatically send the application name with each message.  When a programmer wishes to further identify the cause or contributors to a condition a message is reporting, these extra source fields can be supplied with a string value.  By convention the sources are ordered going from general to specific.  Source1 being the most general, Source2 to being the next level of specificity and so on.  To support this convention, the more general source items must be included if the more specific ones are used (for example you must send Source1 if you send Source2). Not all sources will be hierarchical but more specific information that leads to a resolution of a problem is always desirable.  If there are several peer problem sources they can be sent in these arguments provided the rule above is satisfied (for example to send Source3 you must send Source2 and Source1).
Source2 String See above.
Source3 String See above.

 

Severity Override values are:

Number MsgSeverityConstants Meaning Description
1 mscCritical Critical The message is reporting a critical problem that can impact operations.
2 mscError Error The message is indicating an error condition that should be resolved eventually. 
3 mscWarning Warning
The message indicates an issue that could elevate into a more serious problem or may be only a transient condition.

4 mscInformation Information The message is informational only and does not indicate a problem.
5 mscDebug Debug The message is only provided to aid in debugging.

 

Remarks

The list of delivered template messages that can be used is provided in the file PIMessageDefinitions.htm in the PIPC\Help directory.  The argument description of this routine is identical to MessageLog2.SendLogMessage as the intent is to be able to use the same constructed arguments to both log a message and turn it into a display string.

 

 

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may be returned :

Error Description
pseSUBSYSNOVERSION Unable to obtain the version of the PIMessage subsystem being written to
pseMSGRENDER Unable to render a templated log message.

Enabling Operational Intelligence