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.

Copy
AddAuditComment
Sub

    Dim key
    Dim myComment
     
    key = "0000000034"
    myComment = "Hello, World!"
     
    AudClient.AddAuditComment key, myComment

End Sub

Back to top

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.

Copy
AddAuditTransactionComment
Sub 

    AudClient.AddAuditTransactionComment 56, "Hello, World!"

End Sub

Back to top

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.

Copy
AssociateFacilityWithTransaction
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

Back to top

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.

Copy
AssociatePointWithTransaction
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

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. 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:

Copy
Connect
Sub AudConnect()

    'Connect to an AUD
    Dim AudClient
    Set AudClient = CreateObject("CxAud.AudClient")
    AudClient.Connect("[5410]CYGDEMO.AUD")

End Sub

Back to top

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.

Copy
CreateAuditTransaction
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

Back to top

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:

Copy
Disconnect
Sub Svc.Disconnect()
 
    <SvcClient>.Disconnect()
    MsgBox "Service has disconnected."
    
    If <SvcClient>.Disconnect <> 0 
    Then
        MsgBox "Failed to disconnect."
    End If

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.

Copy
GetConsoleData
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

Back to top

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:

Copy
GetReferences
Sub GetReferences()
 
    <NameofServiceClientObject>.GetReferences
    MsgBox "Services references retrieved"

End Sub

Back to top

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.

Copy
ReadAuditComments
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

Back to top

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.

Copy
ReadAuditRecords
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

Back to top

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.

Copy
ReadUserFlags
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

Back to top

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.

Copy
UpdateUserFlag
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)

Back to top

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.

Copy
UpdateUserFlags
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)

Back to top