spilon

30 lines of code: get started with Web Services in PI ACE 2.x

Blog Post created by spilon on Jan 20, 2009

 

 

One feature I think might be unknown or underestimated is the support for WebServices in PI ACE 2.x, which I'd like to cover here in a brief paper. Depending on the feedback you'll give me and how people like it, I might enhance it and turn it into a Tutorial destined for the vCampus Library. Happy reading and coding!

 

 

 

The What and the Why

 

On one hand we have web services, which are gaining popularity as they allow for very simple client-side applications that can work over the Internet (i.e. across firewalls) and that are interoperable across platforms, applications, and programming languages (because they use standards such as HTTP, SOAP and XML).

 

On the other hand we have PI Advanced Computing Engine (ACE), which allows people (developers and non-developers) to create simple or complex calculations that can be make use of PI data. In PI ACE 2.x, these calculations can be streamed on demand by invoking the exposed web services. This means a very easy (1 simple procedure for all ACE calculations) and efficient (calculations are done on the server) way to extend what yourself or somebody has done in PI ACE already.

 

Part 1 below is also outlined in the PI ACE User Guide, available on the vCampus Library (under Chapter 6: ACE 2.x Features, see Exposing Calculations via Web Service). That's why I'll focus a little more on Part 2 and 3, which explain how to "consume", how to use those web services.

 

Also, if you are not familiar with the installation, configuration or usage of PI ACE, please consult the PI ACE User Guide in the Library and don't hesitate to post in the PI ACE Development discussion forum.

 

 

 

Part 1 - Setting up the PI ACE web services

 

The first few steps consist of activating the streaming of PI ACE calculations via web services:

  1. Install and configure Internet Information Services (IIS) as per Microsoft's instructions.
  2. Install PI ACE 2.x – at least the Scheduler part.
  3. Create a directory in the wwwroot directory (such as PIACEWebService) and copy the file \PIPC\ACE\PIACEWebService.asmx to the directory.
  4. Create a subdirectory called bin and copy the file \PIPC\ACE\PIACEWebService.dll to it.
  5. Open the Microsoft IIS management console.
  6. Select the web service directory created in Step 1 (i.e. PIACEWebService), right-click it, and select Properties.
  7. Click Create and set appropriate security settings.

At this point the ACE web services are ready to be accessed and perform on-demand streaming of the ACE calculation results.

 

2 web services are exposed by PI ACE 2.x:

  1. GetACEContexts: retrieves all available ACE Contexts available for execution.
  2. Calculate: executes a given calculation (i.e. Context) with the specified Start Time, End Time and Interval.

The Calculate web service returns 3 pieces of information:

  1. Timestamp (in UTC Seconds)
  2. Value
  3. Type (this value gives precision on the type of the Value field: -2 is for text string, -1 is for numeric and a value of 0 and higher represents the code of a corresponding PI digital state)

 

 

Part 2 – Add a reference to the PI ACE Web Services
(example using Visual Studio 2008)

 

Using web services is very similar to using methods contained in regular assemblies that reside on your computer: you 'add a reference' to it in your project, you instantiate them and then use their methods. The only difference is that those are 'web references' or 'service references' as opposed to regular ones.

  1. Open Microsoft Visual Studio 2008
  2. Create a new "Windows Forms Application" Project (I called mine 'ACEWebServiceExample')
  3. In the Solution Explorer, right-click on the project and click Add Service Reference:
    (note the option is called Add Web Reference in Visual Studio 2005)
  4. 090119.01_2D00_AddServiceReference1.png

  5. On the Add Service Reference window, click Advanced:
  6. 090119.02_2D00_AddServiceReference2.png

  7. On the Service Reference Settings window, click Add Web Reference:
  8. 090119.03_2D00_AddServiceReference3.png

  9. On the Add Web Reference window:
    1. Navigate to the web service virtual directory (i.e. http://YourWebServer/PIACEWebService/PIACEWebService.asmx)
    2. Choose a name for your reference (i.e. myACEWebSrv)
    3. Click Add Reference
    4. 090119.04_2D00_AddServiceReference4.png

  10. You should now see the reference (with the name you gave in the last step) appear under Web References in the Solution Explorer:

090119.05_2D00_AddServiceReference5.png

 

Now is time to use this reference.

 

 

 

Part 3 – Consuming/Using the PI ACE Web Services
(example using VB.NET under Visual Studio 2008)

  1. Make the form bigger and place the following objects on it:
  2. 090119.06_2D00_ACEWebServiceForm.png

  3. Go in the code behind this form – use the View Code tool at the top of the Solution Explorer: 090119.07_2D00_ViewCode.jpg


  4. At the class level, declare and instantiate a variable that will hold and execute the ACE web services:

Private ws As New myACEWebSrv.PIACEWebService

  1. Get in the btnListContexts button's Click event and add the appropriate code to:
    1. declare the appropriate variables (a single string and a 1-dimension array of string)
    2. invoke the GetACEContexts method of the web service (and fill the array of string)
    3. clear the content of the drop-down list
    4. loop through the retrieved contexts (with the help of the single string variable and a For..Each structure)
    5. add these contexts to the drop-down list

Dim strContext, strContexts() As String
strContexts = ws.GetACEContexts()

cmbContexts.Items.Clear()
For Each strContext In strContexts
    cmbContexts.Items.Add(strContext)
Next

  1. Get in the btnCalculate button's Click event and add the appropriate code to declare the following variables:
    1. A 1-dimension array of myACEWebSrv.PIACETagValues objects
      (this is the top-level object that will be used to retrieve the values)
    2. A single myACEWebSrv.PIACETagValues variable
      (to help looping through the array)
    3. A date initialized to January 1st, 1970
      (remember timestamps in PI are expressed in seconds since January 1st1970)

Dim ACEValues, arrayACEValues() As myACEWebSrv.PIACETagValues
Dim ACEEvent As myACEWebSrv.PIACEEvent
Dim date1970 As New Date(1970, 1, 1)

  1. Still in the btnCalculate button's Click event, we then we execute the Calculate method from the web service, and we:
    1. pass the values from the various fields on the form
    2. fill the 1-dimension array of PIACETagValues objects

arrayACEValues = ws.Calculate( _
    cmbContexts.Text, txtStartTime.Text, _
    txtEndTime.Text, Double.Parse(txtInterval.Text))

  1. Then we loop through the results and add them to the ListBox element:
    1. use a For..Each structure to loop through the series of values
      (there might be more than 1 output tag for the executed ACE Context)
    2. use a For..Each structure to loop through the values of a given series
    3. add these values to the list
      (note the .AddSeconds().ToLocalTime construction, where we add the retrieved timestamp – a number of seconds since 1970 – to our reference date, and we then transform it into local time  - as opposed to UTC)

For Each ACEValues In arrayACEValues
    lstResults.Items.Add("Values for tag: " & ACEValues.TagName)
    For Each ACEEvent In ACEValues.PIACEEvents

        lstResults.Items.Add( _
            date1970.AddSeconds(ACEEvent.TimeStamp).ToLocalTime.ToString() _
            & " - " & _
            ACEEvent.Value.ToString())

    Next
Next

 

 

Voila! You now have a good idea of how you can make use of some of the methods and objects exposed by the PI ACE 2.x web services.

 

 

 

Conclusion

 

Only a few minutes and 30 lines of code later, you enabled and exercised the consumption of PI data over web services in a cross-language, cross-platform, very lean and efficient environment.

 

Also important to note, is the fact that the PIACETagValues object is based on XML and is serializable; this means one can use it in controls such as the DataGridView (set its .DataMember property) and manipulate it in many different ways. Who knows, maybe that'll be in 'Part 2' :)

 

Let me know what you think!

Outcomes