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/2023 16:03:38.431")
strXml = ElsClient.SetRecordXMLAttribute(strXml, "userflag01", "true")
MsgBox strXml
Dim strDbKey
strDbKey = ElsClient.AddEventRecord(strXml)
MsgBox strDbKey
End Sub
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. The domain is optional. The service must be a valid one. |
Remarks
Returns 0 if successful and a non-zero value if the connection failed.
Example
The following example connects the Client object to the CYGDEMO.<SVC> on domain 5410:
Sub ElsConnect()
'Connect to an ELS
Dim ElsClient
Set ElsClient = CreateObject("CxEls.ElsClient")
ElsClient.Connect("[5410]CYGDEMO.ELS")
End Sub
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 (DbKey) 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
Disconnect
The Disconnect method disconnects from the connected service.
Syntax
Disconnect() As Integer
Remarks
The Disconnect method returns 0 if successful and a non-zero value if the disconnect failed.
Example
The following example disconnects the Client object from the connected service, and pops a message box if it is unsuccessful:
Sub Svc.Disconnect()
<SvcClient>.Disconnect()
MsgBox "Service has disconnected."
If <SvcClient>.Disconnect <> 0
Then
MsgBox "Failed to disconnect."
End If
End Sub
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 = <NameofServiceClientObject>.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
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/2023 16:03:38.431")
strXml = ElsClient.SetRecordXMLAttribute(strXml, "userflag01", "true")
MsgBox strXml
Dim strDbKey
strDbKey = ElsClient.AddEventRecord(strXml)
MsgBox strDbKey
End Sub
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:
|
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
GetReferences
The GetReferences method refreshes the list of services referenced by the connected service.
Syntax
GetReferences() As Integer
Return Values
This method returns all references for the connected service.
Example
The following example refreshes the connected services:
Sub GetReferences()
<NameofServiceClientObject>.GetReferences
MsgBox "Services references retrieved"
End Sub
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 |
The database key (DbKey) - valid Level 2 key |
Example
The following example gets the comment from a database key (DbKey).
Sub readComments()
Dim key
Dim comment
key = "0000000034"
comment = ElsClient.ReadEventComment(key)
MsgBox comment
End Sub
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 database keys (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
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 database keys (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
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 |
The database key (DbKey) - valid Level 1 key 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
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:
|
|
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/2023 16:03:38.431")
strXml = ElsClient.SetRecordXMLAttribute(strXml, "userflag01", "true")
MsgBox strXml
Dim strDbKey
strDbKey = ElsClient.AddEventRecord(strXml)
MsgBox strDbKey
End Sub
UpdateEventComment
The UpdateEventComment method adds a comment to a record.
Syntax
UpdateEventComment(DbKey As String, Comment As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
DbKey |
Yes |
The database key (DbKey) -valid Level 2 key. |
|
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
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 database key (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 |
The database key (DbKey) - valid Level 1 key 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)
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 database key (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 |
The database key (DbKey) - valid Level 1 key 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)
