Scripting > CxEls > ElsClient Object > ElsClient Methods

ElsClient Methods

The ElsClient object contains the following methods:

AddEventRecord

The AddEventRecord method adds an event to the ELS.

Syntax

AddEventRecord(RecordXml as String) As String

Parameters

Parameter Required Description

RecordXml

Yes

An XML representation of the record to add to the ELS.

Remarks

The RecordXml parameter of this method can be built using the methods GetEmptyRecordXml and SetRecordXMLAttribute.

Example

The following example builds a record XML and adds it to the ELS.

Sub

Dim strXml

 

strXml = ElsClient.GetEmptyRecordXml

 

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "description", "My Description")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "details", "My Details")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "comments", "My Comments")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "eventtimelocal", "3/10/2011 16:03:39.431")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "userflag01", "true")

 

MsgBox strXml

 

Dim strDbKey

strDbKey = ElsClient.AddEventRecord(strXml)

 

MsgBox strDbKey

End Sub
Back to top

Connect

The Connect method connects the object to a service.

Syntax

Connect(DomainSiteService As String)

Parameters

Parameter Required Description

DomainSiteService

Yes

The [Domain]Site.Service to which to connect.  A domain is optional. The service must be a valid ELS.

Remarks

Returns 0 if successful and a non-zero value if the connection failed.

Example

The following example connects the ElsClient object to the CYGDEMO.ELS on domain 5410:

Sub ElsConnect()

'Connect to an ELS

Dim ElsClient

Set ElsClient = CreateObject("CxEls.ElsClient")

ElsClient.Connect("[5410]CYGDEMO.ELS")

End Sub
Back to top

DeleteEventRecord

The DeleteEventRecord method deletes an event from the ELS.

Syntax

DeleteEventRecord(DbKey as String) As Boolean

Parameters

Parameter Required Description

DbKey

Yes

The database key of the record to delete.

Remarks

This method returns false if the record was successfully deleted.

Example

The following example deletes record 0000022430 from the ELS.

Sub

Dim bRet

bRet = ElsClient.DeleteEventRecord("0000022430")

 

If Not(bRet) Then

MsgBox "Event record deleted"

Else

MsgBox "Event record not deleted"

End If

End Sub
Back to top

Disconnect

The Disconnect method disconnects from the service.

Syntax

Disconnect()

Example

The following example disconnects the client from the connected service.

Sub ElsDisconnect()

ElsClient.Disconnect()

MsgBox "ElsClient has disconnected"

End Sub
Back to top

GetConsoleData

The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.

Syntax

GetConsoleData(ByRef pText, ByRef pAttr) As Integer

Parameters

Parameter Required Description

pText

Yes

A two-dimensional 25x80 array of console text attributes returned by this method.

pAttr

Yes

A two-dimensional 25x80 array of console display attributes returned by this method.

Remarks

This method returns 0 if successful.

Example

The following example writes the console text and display attributes to a CSV file.

Sub

Dim aryText, aryAttr, nRet

nRet = ElsClient.GetConsoleData(aryText, aryAttr)

 

' Write text attributes to CSV file

Dim i, j, strMsg

For i = 0 To UBound(aryText, 1)

For j = 0 To UBound(aryText, 2)

strMsg = strMsg + CStr(aryText(i, j)) + ","

Next

strMsg = strMsg + vbCr

Next

 

dim fso, file

Set fso = CreateObject("Scripting.FileSystemObject")

Set file = fso.OpenTextFile("c:\console_text_attrs.csv", 2, True)

file.WriteLine(strMsg)

file.Close

 

strMsg = ""

 

' Write display attributes to CSV file

For i = 0 To UBound(aryAttr, 1)

For j = 0 To UBound(aryAttr, 2)

strMsg = strMsg + CStr(aryAttr(i, j)) + ","

Next

strMsg = strMsg + vbCr

Next

 

Set file = fso.OpenTextFile("c:\console_disp_attrs.csv", 2, True)

file.WriteLine(strMsg)

file.Close

 

MsgBox nRet

End Sub
Back to top

GetEmptyRecordXml

The GetEmptyRecordXml method returns an empty ELS header record.

Syntax

GetEmptyRecordXml() As String

Example

The following example builds a record XML and adds it to the ELS.

Sub

Dim strXml

 

strXml = ElsClient.GetEmptyRecordXml

 

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "description", "My Description")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "details", "My Details")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "comments", "My Comments")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "eventtimelocal", "3/10/2011 16:03:39.431")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "userflag01", "true")

 

MsgBox strXml

 

Dim strDbKey

strDbKey = ElsClient.AddEventRecord(strXml)

 

MsgBox strDbKey

End Sub
Back to top

GetRecordXMLAttribute

The GetRecordXMLAttribute method returns the value of a specified attribute in the specified record XML.

Syntax

GetRecordXMLAttribute(RecordXml as String, RecordAttribute as String) As String

Parameters

Parameter Required Description

RecordXml

Yes

An XML representation of the record from which to retrieve an attribute.

RecordAttribute

Yes

The attribute to retrieve from the record.  This parameter can be one of the following values:

  • "lock_user" — Lock User
  • "lock_time" — Lock Time
  • "key" — Lock Key
  • "eventtype" — Event Type
  • "source" — Source
  • "category" — Category
  • "description" — Description
  • "details" — Details
  • "comments" — Comments
  • "eventtime" — Event Time
  • "eventtimelocal" — Event Time (local)
  • "userflag01" — User Flag 01
  • "userflag02" — User Flag 02
  • "userflag03" — User Flag 03
  • "userflag04" — User Flag 04
  • "userflag05" — User Flag 05
  • "userflag06" — User Flag 06
  • "userflag07" — User Flag 07
  • "userflag08" — User Flag 08
  • "userflag09" — User Flag 09

Example

The following example displays the value of the "eventtimelocal" attribute for record 0000022430.

Sub

Dim aryDbKeys, aryXml, strAttr

ReDim aryDbKeys(0)

 

aryDbKeys(0) = "0000022430"

 

aryXml = ElsClient.ReadEventRecordsXmlArray(aryDbKeys)

 

strAttr = ElsClient.GetRecordXMLAttribute(aryXml(0), "eventtimelocal")

 

MsgBox strAttr

End Sub
Back to top

GetReferences

The GetReferences method refreshes the list of services referenced by the connected service.

Syntax

GetReferences()

Example

The following example refreshes the connected services.

Sub getElsReferences()

ElsClient.GetReferences()

MsgBox "Services referenced retrieved"

End Sub
Back to top

ReadEventComment

The ReadEventComment method returns the comment for a record as an XML formatted string.

Syntax

ReadEventComment(Key As String) As String

Parameters

Parameter Required Description

Key

Yes

A valid Level 2 DbKey.

Example

The following example gets the comment from a DbKey.

Sub readComments()

Dim key

Dim comment

key = "0000000034"

 

comment = ElsClient.ReadEventComment(key)

MsgBox comment

End Sub
Back to top

ReadEventRecords

The ReadEventRecords method returns the header record fields as an XML string.

Syntax

ReadEventRecords(DbKeys As Array) As String

Parameters

Parameter Required Description

DbKeys

Yes

An array of valid Level 2 DbKeys.

Example

The following example gets header records from two DbKeys and stores them in an XML document.

Sub readRecords()

Dim Keys(1)

Dim headersXml

 

Keys(0) = "0000000034"

Keys(1) = "0000000036"

 

headersXml = ElsClient.ReadEventRecords(Keys)

 

'Save header records as XML

Set xmlDoc = CreateObject("Msxml2.DOMDocument.5.0")

xmlDoc.loadXML(headersXml)

xmlDoc.save("C:\HeaderRecords.xml")

End Sub
Back to top

ReadEventRecordsXmlArray

The ReadEventRecords method returns the header record fields as an array of XML strings.

Syntax

ReadEventRecordsXmlArray(DbKeys As Array) As Variant

Parameters

Parameter Required Description

DbKeys

Yes

An array of valid Level 2 DbKeys.

Example

The following example gets header records from two DbKeys. It then displays the first record in a list box and saves the second record to the hard drive.

Sub readRecordArray()

Dim Keys(1)

Dim arrHeaders

 

Keys(0) = "0000000034"

Keys(1) = "0000000036"

 

arrHeaders = ElsClient.ReadEventRecordsXmlArray(Keys)

 

'Display the first record

lboList.AddString(arrHeaders(0))

 

'Save the second record to the hard drive

Set xmlDoc = CreateObject("Msxml2.DOMDocument.5.0")

xmlDoc.loadXML(arrHeaders(1))

xmlDoc.save("C:\HeaderRecordXml.xml")

End Sub
Back to top

ReadUserFlags

The ReadUserFlags method takes a valid Event Logging Service database key and returns an array of the user flag values.

Syntax

ReadUserFlags(DbKey As String)

Parameters

Parameter Required Description

DbKey

Yes

A valid Level 1 DBKey for the record to update in a string form.

Remarks

Return Value:  An array of the current user flag values. Each Entry in the array represents a single flag. The value of each entry is True if the flag is set, False if the flag is not set. The array index is zero based, so index 0 is UserFlag01 and index 9 is UserFlag10, or one less than the name.

Example

The following example gets the user flag values for DbKey 0000000282 and displays a message box with UserFlag07’s state.

Dim ElsClient

Dim arrFlags

 

'Create the Els Client Object

ElsClient = CreateObject("CxEls.ElsClient" )

 

'Connect to the appropriate ELS

ElsClient.Connect "MYSITE.ELS"

 

'Read the current user flags on DbKey 0000000282

arrFlags = m_ElsClient.ReadUserFlags( "0000000282")

 

'Now show the current flag value for UserFlag07

If arrFlags(6) Then

MsgBox "UserFlag07 is Set"

Else

MsgBox "UserFlag07 is not Set"

End If
Back to top

SetRecordXMLAttribute

The SetRecordXMLAttribute method sets the value of a specified attribute in the specified record XML.

Syntax

SetRecordXMLAttribute(RecordXml as String, RecordAttribute as String, AttributeValue as String) As String

Parameters

Parameter Required Description

RecordXml

Yes

An XML representation of the record for which to set an attribute.

RecordAttribute

Yes

The attribute to set in the record.  This parameter can be one of the following values:

  • "eventtype" — Event Type
  • "source" — Source
  • "category" — Category
  • "description" — Description
  • "details" — Details
  • "comments" — Comments
  • "eventtimelocal" — Event Time (local)
  • "userflag01" — User Flag 01
  • "userflag02" — User Flag 02
  • "userflag03" — User Flag 03
  • "userflag04" — User Flag 04
  • "userflag05" — User Flag 05
  • "userflag06" — User Flag 06
  • "userflag07" — User Flag 07
  • "userflag08" — User Flag 08
  • "userflag09" — User Flag 09

AttributeValue

Yes

The value of the attribute to set.

Remarks

Return Value:  A string containing the new record XML with the updated attribute.

Example

The following example builds a record XML and adds it to the ELS.

Sub

Dim strXml

 

strXml = ElsClient.GetEmptyRecordXml

 

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "description", "My Description")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "details", "My Details")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "comments", "My Comments")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "eventtimelocal", "3/10/2011 16:03:39.431")

strXml = ElsClient.SetRecordXMLAttribute(_

strXml, "userflag01", "true")

 

MsgBox strXml

 

Dim strDbKey

strDbKey = ElsClient.AddEventRecord(strXml)

 

MsgBox strDbKey

End Sub
Back to top

UpdateEventComment

The UpdateEventComment method adds a comment to a record.

Syntax

UpdateEventComment(DbKey As String, Comment As String)

Parameters

Parameter Required Description

DbKey

Yes

A valid Level 2 DbKey.

Comment

Yes

A string comment to add to the record.

Example

The following example adds a comment to a ELS record.

Sub updateElsComment()

Dim key

Dim myComment

 

key = "0000000034"

myComment = "Hello, World!"

 

ElsClient.UpdateEventComment key, myComment

End Sub
Back to top

UpdateUserFlag

The UpdateUserFlag method takes a valid Event Logging Service database key and will set the specific User Flag on the corresponding record. If setting more than one flag on a given DbKey, using the UpdateUserFlags is more efficient. Set to True to enable, False to disable. Valid Flag values are 1-10

Syntax

UpdateUserFlag(DbKey As String, Flag As Integer, Setting As Boolean)

Parameters

Parameter Required Description

DbKey

Yes

A valid Level 1 DBKey for the record to update in a string form.

Flag

Yes

The flag to change. This is a numeric value of 1 to 10 corresponding to UserFlag01 though UserFlag10.

Setting

Yes

A Boolean value of True to set the user flag or False to clear the user flag.

Remarks

Return Value:  None. An error is generated if the Update to the user flag does not succeed.

Example

The following example clears the first user flag on DbKey 0000000282 and sets the fifth user flag on DbKey 0000000283.

Dim ElsClient

 

'Create the Els Client Object

 

ElsClient = CreateObject("CxEls.ElsClient" )

 

'Connect to the appropriate ELS

ElsClient.Connect "MYSITE.ELS"

 

'Clear UserFlag01 on DbKey 0000000282

m_ElsClient.UpdateUserFlag( "0000000282", 1, False)

...

...

'Set UserFlag05 0000000283

m_ElsClient.UpdateUserFlag( "0000000283", 1, True)
Back to top

UpdateUserFlags

The UpdateUserFlags method takes a valid Event Logging Service database key and will set the specific User Flag on the corresponding record. If setting more than one flag on a given DbKey, using the UpdateUserFlags is more efficient. True means set the flag, False means clear the flag, Empty or Null means leave existing value.

Syntax

UpdateUserFlags(DbKey As String, ArrFlags)

Parameters

Parameter Required Description

DbKey

Yes

A valid Level 1 DBKey for the record to update in a string form.

arrFlags

Yes

An array of the flags to change. Each Entry in the array maybe represents a single flag. The value of each entry is True to set the flag, False to clear the Flag or Empty or Null to retain the current value of the flag. The array index is zero based, so index 0 is UserFlag01 and index 9 is UserFlag10.

Remarks

Return Value:  None. An error is generated if the Update to the user flags does not succeed.

Example

The following example clears UserFlag01 and sets UserFlag05 on DbKey 0000000282. Then, it clears all the flags on DbKey 0000000283 except for UserFlag07.

Dim ElsClient

Dim arrFlags

Dim iIndex

 

'Create the Els Client Object

 

ElsClient = CreateObject("CxEls.ElsClient" )

 

'Connect to the appropriate ELS

ElsClient.Connect "MYSITE.ELS"

 

'allocate the array, Redim is the upperbound based so subtract 1

'from the number of flags.

 

Redim arrFlags(ElsClient.UserFlagCount - 1)

 

'Clear UserFlag01, set UserFlag05, and leave all the rest alone

arrFlags(0) = False

arrFlags(4) = True

 

'Update the flags on dbkey 0000000282

m_ElsClient.UpdateUserFlags( "0000000282, arrFlags)

...

...

'Now Clear all the flags on 0000000283 except UserFlag07

'Clear all the flags

For iIndex = LBound(arrFlags) to UBound(arrFlags )

arrFlags(iIndex) = False

Next

 

'Retain the value for UserFlag07

arrFlags(6) = Empty

 

'Now update the flags

m_ElsClient.UpdateUserFlag( "0000000283", arrFlags)
Back to top

Let us know how we can improve this topic.

CygNet at weatherford.com

© 2020 Weatherford. All rights reserved.