PIErrors/PIError Example

 

 

This example demonstrates how to work with a PIErrors collection.  Various PI-SDK methods can return an error collection in order to report one or more problems encountered during method execution.   These methods may themselves return/raise an error indicating a problem occurred or you may be required to check the count of the returned PIErrors collection to determine if all operations performed by the method were successful.  Consult the individual method documentation for details. 

 

In this example, an error situation is contrived so that errors are reported.  To operate the program click on the buttons in order from left to right and top to bottom.  First you add a server to the Known Servers Table (you should provide the name of a server not already in your Known Servers Table or remove an existing server before running this code  - you can use PISDKUtility for this).  Next you add a module to the server's Module Database.  Clicking on Persist generates and displays a persistence string for this module.  Following this, click on "Remove Server" so the server is no longer in the Known Servers Table and attempts to restore items from that server will generate errors.  Finally click on RestoreServers to generate the PIErrors collection and display its contents.  

 

Note the Form_Unload code of this example readds the Server, removes the PIModule and then removes the Server again to restore the Server and Known Servers Table to its starting state.  

Build the PIErrors example as follows:

1. Create a new project and add a reference to the PISDK library.

2. Add the visual elements as shown in the picture. The code names the elements as follows:

Control Type Control Caption Control Name
CommandButton Add Server Command5
CommandButton Add Module Command1
CommandButton Persist  Command2
CommandButton Remove Server Command6
CommandButton Restore Servers Command3
TextBox Server Name Text2
TextBox Persistence String Text1
ListBox Errors: List1

3. Cut and paste the code below into the project.

Option Explicit
Dim srvNew As Server
Dim cnxn As New Connections
Dim md1 As PIModule
Dim strPersist As String

Private Sub Command1_Click()
On Error GoTo eh
   ' Add a module
   If Not srvNew.Connected Then
      MsgBox "Please add a new server first"
      Exit Sub
   End If
   Dim mdb As PIModuleDB
   Set mdb = srvNew.PIModuleDB
   Dim vtEffectiveDate As Variant
   Dim ptEffective As New PITime
   ptEffective.LocalDate = CDate("01/01/90 2:00 PM")
   vtEffectiveDate = ptEffective
   Set md1 = mdb.PIModules.Add("DeleteMeErrorsTest1", vtEffectiveDate)
Exit Sub
eh:
   MsgBox Err.Description + " " + CStr(Hex(Err.Number)) + " " + "PIErrors Example"
End Sub

Private Sub Command2_Click()
On Error GoTo eh
   'Persist a module
   If md1 Is Nothing Then
      MsgBox "Please add a server and a Module before attempting to persist"
      Exit Sub
   End If
   Dim ipersist As IPIPersist
   Set ipersist = md1
   strPersist = ipersist.Persist
   Text1.Text = strPersist
Exit Sub
eh:
   MsgBox Err.Description + CStr(Hex(Err.Number)), "PIErrors Example"
End Sub

Private Sub Command3_Click()
' Attempt to restore the server
On Error GoTo eh
   List1.Clear
   Dim globalRestorer As IPIGlobalRestorer
   ' Obtain the restorer interface from the main sdk object
   Set globalRestorer = PISDK.PISDK
   Dim piErrs As PIErrors
   Dim nvs As NamedValues
   On Error Resume Next
   Set nvs = globalRestorer.Restorer.RestoreServers(strPersist, piErrs)
   If piErrs.Count > 0 Then
      On Error GoTo eh
      ' Show the PIErrors
      Dim piErr As PIError
      List1.AddItem "PIErrors Collection"
      List1.AddItem "=================================================="
      List1.AddItem "Number : Cause : Source : Description"
      List1.AddItem "=================================================="
      For Each piErr In piErrs
         List1.AddItem CStr(piErr.Number) + " : " + CStr(piErr.Cause) _
         + " : " + piErr.Source + " : " + piErr.Description
      Next
   Else
      On Error GoTo eh
      List1.AddItem "Restored Servers"
      List1.AddItem "=================================================="
      Dim nv As NamedValue
      For Each nv In nvs
         List1.AddItem nv.Name + " : " + nv.Value.Path
      Next
   End If

Exit Sub
eh:
   MsgBox Err.Description + CStr(Hex(Err.Number)), "PIErrors Example"
End Sub

Private Sub Command5_Click()
' Add the specified server
On Error GoTo eh
   If Text2.Text = "" Then
      MsgBox "Please enter the name of a PI3 server to add to the Known Servers Table"
      Exit Sub
   End If
   On Error Resume Next
   Set srvNew = Servers.Add(Text2.Text, "port=5450;uid=piadmin", "PI3", True)
   If Err.Number = pseREGISTRYADDSERVER Or Err.Number = 0 Then
      Set srvNew = Servers(Text2.Text)
   ' Open the server
      On Error GoTo eh
      cnxn.Login srvNew, "piadmin", "", True, False
   End If
Exit Sub
eh:
   MsgBox Err.Description + CStr(Hex(Err.Number)) + "PIErrors Example"
End Sub

Private Sub Command6_Click()
' Remove the new server
On Error Resume Next
   If Not srvNew Is Nothing Then
      srvNew.Close
      Servers.Remove srvNew.Name
      Set srvNew = Nothing
   End If
   ' Release the module
   Set md1 = Nothing
End Sub

Private Sub Cleanup()
On Error Resume Next
   ' Delete the module - must add server first
   If srvNew Is Nothing Then
      Command5_Click
   End If
   ' Remove the module
   srvNew.PIModuleDB.PIModules.Remove "DeleteMeErrorsTest1"
   ' Delete the server again
   Servers.Remove srvNew.Name
End Sub

Private Sub Form_Unload(Cancel As Integer)
   Cleanup
End Sub

   
Enabling Operational Intelligence