AudClient Methods
The AudClient object contains the following methods:
AddAuditComment
The AddAuditComment method adds a comment to an audit transaction record.
Syntax
AddAuditComment(Key As String, Comment As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Key |
Yes |
A valid level 2 AUD database key. |
|
Comment |
Yes |
A string comment to add to the record. |
Example
The following example adds a comment to a AUD record.
Sub
Dim key
Dim myComment
key = "0000000034"
myComment = "Hello, World!"
AudClient.AddAuditComment key, myComment
End Sub
AddAuditTransactionComment
The AddAuditTransactionComment method adds a comment to an audit transaction record given a transaction ID.
Syntax
AddAuditTransactionComment(dwAuditTransactionId As Long, TransactionComment As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
| dwAuditTransactionId | Yes | The transaction ID (Audit ID column) of the record to which to add a comment. |
| TransactioComment | Yes | The comment to add to the record. |
Example
The following example adds a comment to an AUD record.
AssociateFacilityWithTransaction
The AssociateFacilityWithTransaction method adds a facility entry to an audit transaction record.
Syntax
AssociateFacilityWithTransaction(dwAuditTransactionId As Long, FacilityTag As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
dwAuditTransactionId |
Yes |
The transaction ID (Audit ID column) of the record to which to add a facility entry. |
|
FacilityTag |
Yes |
The tag of the facility to add to the record. |
Remarks
This method returns the database key of the facility entry in the audit transaction record. Note that only user-created audit transaction records may contain an associated facility.
Example
The following example adds facility CYGDEMO.UIS::20230303 to a newly-created record.
Sub
Dim strTransactionId
strTransactionId = AudClient.CreateAuditTransaction("MY_OPERATION", "My operation description", "My comment")
Dim strDbKey
strDbKey = AudClient.AssociateFacilityWithTransaction(strTransactionId, "CYGDEMO.UIS::20230303")
MsgBox strDbKey
strDbKey = AudClient.AssociatePointWithTransaction(strTransactionId, "CYGDEMO.SVCMON.00000294")
MsgBox strDbKey
End Sub
AssociatePointWithTransaction
The AssociatePointWithTransaction method adds a point entry to an audit transaction record.
Syntax
AssociatePointWithTransaction(dwAuditTransactionId As Long, ShortPointTag As String) As String
Parameters
| Parameter | Required | Description |
|---|---|---|
|
dwAuditTransactionId |
Yes |
The transaction ID (Audit ID column) of the record to which to add a facility entry. |
|
ShortPointTag |
Yes |
The tag of the point to add to the record. This parameter must be in the form "SITE.SERVICE.POINTID" (without the quotes). |
Remarks
This method returns the database key of the point entry in the audit transaction record. Note that only user-created audit transaction records may contain an associated point.
Example
The following example adds point CYGDEMO.SVCMON.00000294 to a newly-created record.
Sub
Dim strTransactionId
strTransactionId = AudClient.CreateAuditTransaction("MY_OPERATION", "My operation description", "My comment")
Dim strDbKey
strDbKey = AudClient.AssociateFacilityWithTransaction(strTransactionId, "CYGDEMO.UIS::20230303")
MsgBox strDbKey
strDbKey = AudClient.AssociatePointWithTransaction(strTransactionId, "CYGDEMO.SVCMON.00000294")
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 AudConnect()
'Connect to an AUD
Dim AudClient
Set AudClient = CreateObject("CxAud.AudClient")
AudClient.Connect("[5410]CYGDEMO.AUD")
End Sub
CreateAuditTransaction
The CreateAuditTransaction method creates an audit transaction record.
Syntax
CreateAuditTransaction(OperationId As String, OperationDescription As String, TransactionComment As String) As Long
Parameters
| Parameter | Required | Description |
|---|---|---|
|
OperationId |
Yes |
The chosen ID of the operation (Audit Operation Id column in CygNet Explorer). |
|
OperationDescription |
Yes |
The chosen operation description. |
|
TransactionComment |
No |
An optional comment to add to the record. If this parameter is not specified, no comment will be added to the record. |
Remarks
This method returns the audit transaction ID of the newly-created record.
Example
The following example creates a new record and adds an associated facility and point.
Sub
Dim strTransactionId
strTransactionId = AudClient.CreateAuditTransaction("MY_OPERATION", "My operation description", "My comment")
Dim strDbKey
strDbKey = AudClient.AssociateFacilityWithTransaction(strTransactionId, "CYGDEMO.UIS::20230303")
MsgBox strDbKey
strDbKey = AudClient.AssociatePointWithTransaction(strTransactionId, "CYGDEMO.SVCMON.00000294")
MsgBox strDbKey
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
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
ReadAuditComments
The ReadAuditComments method returns the comments for a record as an XML formatted string.
Syntax
ReadAuditComments(Key As String)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Key |
Yes |
A valid level 2 AUD database key. |
Example
The following example gets the comments from a database key and stores them in an XML document.
Sub readComments()
Dim key
Dim commentsXml
key = "0000000034"
commentsXml = AudClient.ReadAuditComments(key)
'Save header records as XML
Set xmlDoc = CreateObject("Msxml2.DOMDocument.5.0")
xmlDoc.loadXML(commentsXml)
xmlDoc.save("C:\AudComments.xml")
End Sub
ReadAuditRecords
The ReadAuditRecords method returns the header record fields as an XML string.
Syntax
ReadAuditRecords(Keys As Array)
Parameters
| Parameter | Required | Description |
|---|---|---|
|
Keys |
Yes |
An array of valid Level 2 database keys (DbKey). |
Example
The following example gets header records from two database keys and stores them in an XML document.
Sub readRecords()
Dim Keys(1)
Dim headersXml
Keys(0) = "0000000034"
Keys(1) = "0000000036"
headersXml = AudClient.ReadAuditRecords(Keys)
'Save header records as XML
Set xmlDoc = CreateObject("Msxml2.DOMDocument.5.0")
xmlDoc.loadXML(headersXml)
xmlDoc.save("C:\HeaderRecords.xml")
End Sub
ReadUserFlags
The ReadUserFlags method takes a valid Audit 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 AUD 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 AudClient
Dim arrFlags
'Create the Aud Client Object
AudClient = CreateObject("CxAud.AudClient" )
'Connect to the appropriate AUD
AudClient.Connect "MYSITE.AUD"
'Read the current user flags on DbKey 0000000282
arrFlags = m_AudClient.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
End Sub
UpdateUserFlag
The UpdateUserFlag method takes a valid Audit 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 AUD 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 through 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 AudClient
'Create the Aud Client Object
AudClient = CreateObject("CxAud.AudClient" )
'Connect to the appropriate Aud
AudClient.Connect "MYSITE.AUD"
'Clear UserFlag01 on DbKey 0000000282
m_AudClient.UpdateUserFlag( "0000000282", 1, False)
...
...
'Set UserFlag05 0000000283
m_AudClient.UpdateUserFlag( "0000000283", 1, True)
UpdateUserFlags
The UpdateUserFlags method takes a valid Audit 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 AUD 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, or one less than the name. If a flag index is skipped, no changes will be made to its value. |
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 AudClient
Dim arrFlags
Dim iIndex
'Create the Aud Client Object
AudClient = CreateObject("CxAud.AudClient" )
'Connect to the appropriate Aud
AudClient.Connect "MYSITE.AUD"
'allocate the array, Redim is the upperbound based so subtract 1
'from the number of flags.
Redim arrFlags(AudClient.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_AudClient.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_AudClient.UpdateUserFlag( "0000000283", arrFlags)


