List2 Method (MessageLog2 Interface)

                     

 

The List2 method returns a LogMessagesEx collection from the object’s associated logging system, (local or remote), containing LogMessage2 objects that meet the criteria passed in the argument list.  While this method offers an argument for severity which is only supported on Server versions 3.4.380 and greater, the method can still be called against older servers where the argument is ignored.  The returned collection, LogMessagesEx, contains LogMessage2 message objects, which support a rich array of message properties.  Against a 3.4.380 or higher server, these properties are supported and those being used by a particular message (some are optional) are filled in.  Against older servers the properties will contain initialized values such as a blank string or a -1.  The method SendLogMessage of the MessageLog2 object supports sending the new message properties.  When sending to an older server, the PI-SDK detects the target message subsystem version and if these properties are not supported, it turns them into text and adds them to the text of the message.  When this is done, methods like List2 and its predecessor, List, return longer strings in the message body. 

 

Syntax

object.List2 object.List2 StartDate, EndDate, Count, ProgramNameMask, msgStringMask, msgID, severity, nvsFilter, [AsynchStatus], [lLang], [localeID]

The List method syntax has these parts:

Part Description
object An object expression that evaluates to a MessageLog object.
StartDate A Variant containing the beginning of the period over which messages are to be retrieved. Setting the date to –1.0 indicates the StartDate is to be ignored (EndDate and Count must be specified). The date must be later than Jan 1, 1970.  The Variant can contain any of the types shown in the table below.
EndDate A Variant containing the end of the period for which messages are to be retrieved. Setting the date to –1.0 indicates the EndDate is to be ignored (StartDate and Count must be specified). The Variant can contain any of the types shown in the table below.
Count The maximum number of messages to be retrieved by the call. Setting the count to -1 indicates the count is to be ignored (StartDate and EndDate must be specified).
ProgramNameMask A string containing a mask to filter the returned messages according to the program that sent them. Masks may contain wildcard characters. A mask of “*” will allow messages logged by any program to be returned, subject to the other criteria.
msgStringMask A string containing a mask to filter the returned messages according to the message content. Masks may contain wildcard characters. A mask of “*” will allow all messages to be returned subject to the other criteria.
msgID A message ID number filter. Only messages that match this ID are returned. Passing an ID of –1 will act as a wildcard allowing messages of any ID to be returned subject to the other criteria. Message IDs indicate messages that are based on a template where standard text is represented by the ID and only supplemental text needs to be provided with the ID.  An HTML file listing the supported template messages, PIMessageDefinitions.htm is provided in the PIPC\help directory for reference.
severity A severity from the pisdkSeverityLevel enumeration (see below).  All messages of this severity or lower are returned.  Specify mscNoSeverity to indicate messages with any severity are to be returned.
nvsFilter A NamedValues collection of filter names and values to be used when retrieving messages.  The collection contains named message fields and desired values.  The names of allowed fields should be retrieved from the IMessageFilterNames interface obtained from a MessageLog2.MessageFilterNames property.  For string values, a wildcard ("*") may be used.  For numeric values (e.g. IMessageFilterNames.ProcessID_Filter) an exact match is required if specified. For IMessageFilterNames.Priority_Filter  (a numeric from 1-10) the value specified includes all lower numbers (e.g. priority 7 includes priortiies 1-7).
AsynchStatus A reference to a PIAsynchStatus object. Used to execute asynchronous calls to retrieve messages. Not implemented in current version.[Optional]
lLang A long integer representing a language specific resource to be used to format this message for display. A single msgID can be present in several resources, to support different languages. Use 0 (the default) in this argument to indicate default formatting. Must be 0 in current version. [Optional]
localeID A localeID to be used to format the message for the display. In Visual Basic this argument will be provided automatically. Not used in current version. [Optional]

 

Remarks

The List method returns a LogMessages collection or raises an error. When no messages are found to match the passed criteria, an error of pseNOMESSAGESFOUND is raised and no collection is returned.

Currently the log messages returned are converted from their storage in ASCII to UNICODE using the default code-page.

If StartDate, EndDate and Count are all specified, the returned LogMessages collection will contain messages from the StartDate up to the EndDate or until the Count is reached, whichever comes first. If EndDate is set to –1.0 and StartDate and Count are valid, Count messages are returned from the StartDate going forward. If StartDate is set to –1.0 and EndDate and Count are valid, Count messages are returned ending with the EndDate. Messages are always returned in chronological order.

 

The possible values in the variant for StartTime and EndTime are:

 

Trappable Errors

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

Error

Description

pseNOMESSAGESFOUND No messages were found which matched the passed criteria.
pseDATETOEARLY The passed date was earlier than January 1, 1970 or the EndDate is earlier than the StartDate.
pseDATETOTIMESTAMP Problem converting passed DATE to an internal time stamp.
pseMESSAGERETRIEVAL Problem retrieving messages from the server or local message log. See the returned error description for more information.
pseMSGLOGPARENT The MessageLog object did not have its parent set correctly internally.
pseMESSAGEUSER Unable to create an internal message user object.
pseMESSSAGEFILEOPEN Unable to open the local or server’s message file.
pseREGLOAD An error was encountered attempting to initialize the Servers collection from the registry.
pseVARIANTNOTDATE Problem converting passed DATE to an internal time stamp.
pseNOGENSERVER Unable to obtain an internal generic server object.

 

Enabling Operational Intelligence