List Method (MessageLog object)

                

 

The List method returns a LogMessages collection from the object’s associated logging system, (local or remote), containing LogMessage objects that meet the criteria passed in the argument list. Addition search constraints may be specified by using the List2 method for PI Message subsystems that support the additional message attributes.

Syntax

object.List StartDate, EndDate, Count, ProgramNameMask, msgStringMask, msgID, [AsynchStatus], [lLang], [localeID]

The List method syntax has these parts:

Part Description

object

An object expression that evaluates to a MessageLog object.

StartDate

A DATE 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.

EndDate

A DATE 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.

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.

AsynchStatus

[Optional] A reference to a PIAsynchStatus object. Used to execute asynchronous calls to retrieve messages.
Not implemented in Version 1.

lLang

[Optional] A long 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 Version 1.

localeID

[Optional] A localeID to be used to format the message for the display. In Visual Basic this argument will be provided automatically.
Not used in Version1.

 

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.

When using .Net, the Start and End times are treated as System.DateTime objects by the OSIsoft.PISDK interop.  To specify that  a date argument is to be ignored (-1 in VB) use code similar to the following:
 

            Dim dtEnd As Date

            Dim dblDate As Double
            dblDate = -1
            dtEnd = DateTime.FromOADate(dblDate)
 

 

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