Applications & Tools. Creating Report Templates for the Information Server on the Process Historian Database in the PCS 7 Environment SIMATIC PCS 7

Transcription

1 As Cover Creating Report Templates for the Information Server on the Process Historian Database in the PCS 7 Environment SIMATIC PCS 7 Application Description November 2012 Applications & Tools Answers for industry.

2 Siemens Industry Online Support This document is taken from Siemens Industry Online Support. The following link takes you directly to the download page of this document: For further information on this topic, you may also actively use our Technical Forum in the Siemens Industry Online Support. Share your questions, suggestions or problems and discuss them with our strong forum community: 2 V1.0, Entry ID:

3 s Task 1 Solution 2 Tool for Reporting 3 SIMATIC PCS 7 Application Example Working with the Database 4 Glossary 5 History 6 Attachment: Technical Specifications 7 V1.0, Entry ID:

4 Warranty and Liability Warranty and Liability Note The application examples are not binding and do not claim to be complete regarding configuration, equipment and any eventuality. The application examples do not represent customer-specific solutions. They are only intended to provide support for typical applications. You are responsible for ensuring that the described products are used correctly. These application examples do not relieve you of your responsibility to use sound practices in application, installation, operation and maintenance. When using these application examples, you recognize that we will not be liable for any damage/claims beyond the liability clause described. We reserve the right to make changes to these application examples at any time and without prior notice. If there are any deviations between the recommendations provided in this application example and other Siemens publications e.g. catalogs the contents of the other documents have priority. We do not accept any liability for the information contained in this document. Any claims against us based on whatever legal reason resulting from the use of the examples, information, programs, engineering and performance data etc., described in this Application Example shall be excluded. Such an exclusion shall not apply in the case of mandatory liability, e.g. under the German Product Liability Act ( Produkthaftungsgesetz ), in case of intent, gross negligence, or injury of life, body or health, guarantee for the quality of a product, fraudulent concealment of a deficiency or breach of a condition which goes to the root of the contract ( wesentliche Vertragspflichten ). The damages for a breach of a substantial contractual obligation are, however, limited to the foreseeable damage, typical for the type of contract, except in the event of intent or gross negligence or injury to life, body or health. The above provisions do not imply a change in the burden of proof to your disadvantage. It is not permissible to transfer or copy these application examples or excerpts thereof without express authorization from Siemens Industry Sector. 4 V1.0, Entry ID:

5 Preface Preface Objective of this application This application describes the basics and the principle of operation of the Process Historian (PH) and of the Information Server (IS). It will be explained in detail how you can create individual reports in order to be able to read out data promptly from the Process Historian database. Furthermore, you will learn how to work with the Process Historian database. Core contents of this application example The following document deals with the following key issues: explanation of the basics and of the function principle of the Process Historian description of the Report Builder (tool for creating reports) correct working with the PH database explanation of the Stored Procedures of the Process Historian The ZIP file that is enclosed in the application example includes the following files: File MyMessages.rdl ISBase.rdl Calculation1.rdl Consumption1.rdl udsp_getmessagetable.sql Meaning Test template, described in the "Change icon of the report template" chapter Start template for internally generated report templates, described in the "Use Case1, using GetTagSnapshots in the ISBase.rdl template" chapter Test Template, described in the "Use Case1, using GetTagSnapshots in the ISBase.rdl template" chapter Test template, described in the "Use Case 2, consumption counter" chapter SQL Code of the stored procedure, described in the "Working with internally generated Stored Procedures" chapter Validity The application description has been created with: SIMATIC PCS 7 V8.0 Upd1 Process Historian V8.0 Upd1 Information Server V8.0 Upd1 The application description is in principal transferable to: SIMATIC PCS 7 V8.0 SP1 Process Historian V8.0 SP1 Information Server V8.0 SP1 V1.0, Entry ID:

6 Table of Contents Table of Contents Warranty and Liability... 4 Preface Task Solution Process Historian Overview of the functionalities and benefits Functionality of the process historian Data transmission between OS server and process historian Information Server Reporting with the information server Report templates Correlation when creating report templates Tool for Reporting Report Builder Installation of the report builders via the report manager Report Builder user interface Connecting the Report Builder with the Report Server Processing report template Testing standard report templates with the report builder Downloading report template and changing name Changing icon of the report template Calculations Direct SQL statements in the report builder Date and Time Examples for time functions Conversion of timestamp to local time Use Cases Use Case1: Creating a new report template Use Case 2: Consumption counter Working with the Database OS archive tags IS.VTagBrowsing TLG.VTagValue Designing SQL polls at database level Working with existing standard stored procedures udsp_gettagtable example udsp_gettagtrend example "udsp_gettagaggregetion" example udsp_getmessagesperday example udsp_getmessagesper10minutes example udsp_ getquantitybymessageclass example udsp_ getquantitybymessageclass example Working with self-generated stored procedures Integrating the udsp_getmessagetable stored procedure into the PH database Glossary History V1.0, Entry ID:

7 Table of Contents 7 Attachment: Technical Specifications A Information Server Standard Stored Procedures A.1 System defined Parameters A.2 Alarm Logging A.2.1 [IS].[udf_TextBlock] B Basic PH functions B.1 [IS].[udf_getDatasourceNodes] B.1.1 [IS].[udf_getMessageDefinitions] B.1.2 [IS].[udf_getAlarmDefinitions] C Target System BL C.1 Tag Logging Configuration Data C.1.1 [IS].[VTagBrowsing] C.1.2 [IS].[udsp_getTagConfiguration] C.1.3 [IS].[udsp_getTagConfigurationChain] C.2 Tag Logging Runtime Data C.2.1 [IS].[udsp_getTagSnapshots] C.2.2 [IS].[udsp_getTagAggregation] C.2.3 [IS].[udsp_getTagTrend] C.2.4 [IS].[udsp_getTagTable] C.3 Alarm Logging Configuration Data C.3.1 [IS].[udsp_getAcknowledgeableMessageClasses] C.3.2 [IS].[udsp_getMessageClasses] C.3.3 [IS].[udsp_getPercentageOfPriorityInAlarmSettings] C.4 Alarm Logging Runtime Data C.4.1 [IS].[udsp_getDurationOfAckn] C.4.2 [IS].[udsp_getMessagesPerDay] C.4.3 [IS].[udsp_getPercentageOfPriorityInRTAlarms] C.4.4 [IS].[udsp_getMessagesPer10Minutes] C.4.5 [IS].[udsp_getAlarmsByPriority] C.4.6 [IS].[udsp_getQuantityByMessageClass] C.4.7 [IS].[udsp_getTotalDurationUntilAcknowledgment] C.4.8 [IS].[udsp_getTotalDurationUntilWent] C.4.9 [IS].[udsp_getAlarmsByOrigin] C.4.10 [IS].[udsp_getMessageTable] C.4.11 [IS].[udsp_getAverageDurationOfAckn] C.5 udf_getdatasourcenodes C.6 udf_getmessagedefinitions C.7 Select on VAlgData C.8 Formatting to readable result V1.0, Entry ID:

8 1 Task 1 Task World-wide competition, increasing energy costs, scarce raw materials and high demands to product quality companies from the process industry face many challenges. Specific optimization in view of process excellence and profitability are a must. Historic data from the company is a key to increase productivity. In order to make this enormous amount of data accessible for plant optimization, a powerful archive and report system is required. The following requirements should be fulfilled: availability and security of data aggregation of information that is relevant to process control due to crosscompany production report systems central archiving of process data, tags, alarms and batch data from SIMATIC BATCH in realtime and without requiring additional energy as well as seamless, long-term and reliable data capture identification and memorizing added and modified data as audit trail information task-specific reporting and visualization of data powerful data export to Microsoft Excel flexible creating and adjusting report templates standard reporting systems, in order to be able to use already available expert knowledge The figure below provides an overview of the automation task. Figure 1-1: Overview of the automation task 8 V1.0, Entry ID:

9 2 Solution 2 Solution 2.1 Process Historian The PCS 7 Process Historian (PH) is a long-term archive server for process data. Tags, alarms and SIMATIC BATCH data can be archived on the Process Historian. The Process Historian uses the SQL server as data storage. Microsoft reporting services can be used for the processing of SQL server data. The information server provides the user with PH data via a web interface. The components process historian and information server can also be installed together on one computer. The following figure shows an overview of the functionality of the process historian and the information server in the PCS 7 environment: Figure 2-1: Functional principle of PH and IS V1.0, Entry ID:

10 2 Solution 1. Prompt data storage of the OS single stations and the OS servers on the process historian. 2. SIMATIC BATCH exports its batch data on the PH. 3. Access of the information server client to the information server to create reports. Published reports can be displayed and configured on the computer with the help of the internet explorer. Using MS Excel and an information server plug-in for Excel you can export data on a computer from the PH to Excel, similar as for the Data Monitor System. The data of several PCS 7 projects/multiprojects can be archived on a process historian Overview of the functionalities and benefits The Process Historian (PH) and Information Server (IS) have, among others, the following functionalities and benefits: All OS process data is promptly available in the process historian. Batch archives of SIMATIC BATCH are saved natively in the process historian. PH also supports single stations. PH supports several PCS 7 projects in parallel. Easy access to historic process data via web and office applications. Widely used standard reporting system that is adjusted to PCS 7 reporting incl. standard reporting templates. PH can be easily integrated into existing IT infrastructures and web portals. Large volumes of process data can be prepared and displayed in reports across projects. With WinCC Trend and Alarm Control data from PH can also be displayed on the OS Runtime level. With OPC HDA / "H A&E" PH data can be accessed. Backup/restore function on external data carriers. 10 V1.0, Entry ID:

11 2 Solution Functionality of the process historian All OS server and OS single stations, for which a process historian has been configured in the PCS 7 project, export the alarms to PH at runtime. All occurring alarms are furthermore saved on the OS server/the OS single station in the revolving archive of the OS. The configuration of the local archive is configured via the Alarm Logging of the OS. If a PH is configured in the PCS 7 project, all OS archive tags that have the "longterm archiving" ID, are archived on the PH at runtime (real time). In addition, all archive tags are saved in the local revolving archive of the OS. The configuration of the local archive is configured via the tag logging of the OS. Calculations, postprocessing and reporting functions are executed on the process historian. PH is an open system. The data archived on the PH can be read and written via standard database interfaces. For example, ODBC, OLE DB and ADO.NET are supported. The use of 3 rd party reporting systems, such as, for example business objects and Microsoft reporting services are supported. Added and modified data is marked as such in the PH system. "Audit Trail" information such as user, timestamp, comment, value before and modification are saved in the PH system. The export/import of historic data is supported in the CSV, XML and XLS formats. V1.0, Entry ID:

12 2 Solution Data transmission between OS server and process historian When starting OS runtime the configuration data of the OS server/the OS single station is transferred to the database of the process historian. The alarms occurring on the OS server are promptly transferred to the PH. The locally archived OS tags are also promptly transferred to the archiving cycle in the PH. The following figure shows the communication between the OS server and PH. Figure 2-2:Communication between the OS server and PH The data storage on the PH is always done by the Master OS for a redundant OS server. 12 V1.0, Entry ID:

13 2 Solution 2.2 Information Server Reports are created with the information server, using templates. The report templates can be individually adjusted in order to create user-defined reports. In the reports archived variables, messages or SIMATIC BATCH data can be displayed. Reports can be generated automatically and send to a predefined address. Information Server Client An Internet Explorer, MS Word or a MS Excel application can be an information server client. If language switching is desired, the languages have to be installed on the operating system side. Functionality of the information server The information server is the SIEMENS front end of the process historian. The IS provides the user the data of the process historian database, using the MS Internet Information Service (IIS). Reporting Services and Process Historian The process historian is a system on the basis of the MS SQL server 2008 R2. When purchasing the process historian, the customer also receives the MS reporting services. The MS reporting services can be used by the customer for creating reports. However, using the reporting services assumes the respective Microsoft knowledge. Reporting service knowledge is required if you want to individually create and adjust report templates in the RDL format. However, the use of MS reporting services on the MS SQL server platform is not mandatory. All functionalities of the information server can be used without any knowledge of the Microsoft reporting service. V1.0, Entry ID:

14 2 Solution 2.3 Reporting with the information server With the SIMATIC information server, measuring values and messages can be summarized, evaluated and graphically displayed. A network connection to a process historian is required to access archived data. If an information server is installed on the same PC as the process historian, a network connection is not necessary. Figure 2-3 You can access the information server with internet explorer. Apart from displaying the reports, you also use the web to manage the information server. The contents of the report can be displayed graphically and in a table. The information server is an ASP.Net application. The following table gives you an overview of the information server web application: Table 2-1: Overview of the information server web application Start page Menu Area Usage Providing orientation, office add-ins Dashboard > pages Public Providing public dashboard pages Private Providing private dashboard pages Dashboard > configuration Creating pages Creating and saving Importing pages Deleting pages Creating layout Deleting layout dashboard page with existing layout Importing and saving dashboard page Deleting dashboard page Creating layout for dashboard pages Deleting layout for dashboard pages 14 V1.0, Entry ID:

15 2 Solution Menu Area Usage Reporting Templates Selecting report template for messages, batches and archive tags Reports Preconfigured reports Exports Managing, deleting and moving exported reports Subscriptions Excel templates Overview of the existing subscriptions Managing Excel templates Administration Projects Creating connection with a process historian as data source, accessing a project Role management User administration Scheduler status settings Design Here you can check the status of automatically created reports.- Overview and polling subscriptions. Details to SMTP server for sending reports Changing design of web application V1.0, Entry ID:

16 2 Solution Report templates Report templates are delivered with the information server. The report templates are described in the "Information Server Documentation" manual. Figure 2-4: Information server view You can create reports with the help of report templates. The reports can be saved in PDF, Word or Excel format. 16 V1.0, Entry ID:

17 2 Solution Correlation when creating report templates Report templates are created with the help of the report builder. The data of a dataset is displayed in the report builder. The dataset itself is created with a SQL query. With the data of the dataset you can also make calculations on the report builder level. The data of the OS stations are saved in the SQL server database called "HistorianStorage". Data acquisition is carried out with the help of stored procedures on the PH database. The information server also has a database called "Information Server". The information server DB and the process historian DB work with each other via a "Linked Server Mechanism". For each OS station that exports data on the process historian a database exists on the SQL server. The following figure shows the correlations when creating report templates: Figure 2-5: Creating report templates V1.0, Entry ID:

18 3 Tool for Reporting 3 Tool for Reporting 3.1 Report Builder The Report Builder is a MS tool with which report templates in RDL format can be created and processed. The Report Builder 3.0 is offered for download via the MS Support pages. The Report Builder provides a set of report parts, for example "tables" and "charts" that you can use for the creation of report templates. With the installation of the Report Builder you will also receive detailed help. Note Report builder download: 18 V1.0, Entry ID:

19 3 Tool for Reporting 3.2 Installation of the report builders via the report manager The Report Builder can also be installed via the report manager of the information server. Installing Report Builder To install the Report Builder, please proceed as follows: 1. Start the "Reporting Service Configuration Manager" via the "Start > Configuration Tools > Reporting Service Configuration Manager" menu command. The Reporting Service Configuration Manager is opened. 2. Click the configured URL address. V1.0, Entry ID:

20 3 Tool for Reporting The Report Manager is opened. 3. Click the "Report Generator" to trigger the installation of the Report Builder. 20 V1.0, Entry ID:

21 3 Tool for Reporting 4. Click the "Report Generator" to trigger the installation of the Report Builder. The installation procedure is started. 5. Enter the following installation path: C:\Program Files\Microsoft SQL Server\MSRS10_50.INFSERVER\Reporting Services\ReportServer\ReportBuilder\ReportBuilder_3_0_0_0.application V1.0, Entry ID:

22 3 Tool for Reporting Report Builder user interface In this chapter you will find basic information on the Report Builder. A detailed description of the functions of the Report Builder can be found in the product help. The screenshot below shows the operator displays of the Report Builder: Figure 3-1: Operator display of the Report Builder The operator display of the Report Builder is made up of the following areas: Report Data, here you can find all data that can be used in a report template Report Properties, here you can find the properties of the report templates, such as, for example, the background color. Report Parts, the report parts are objects such as, for example, tables or text fields that can be used for displaying the data in the report template. Grouping, you can group data in columns and rows with the help of the row and column group functionality. Report Test, once you have designed a report template you can test it with the help of the report builder. 22 V1.0, Entry ID:

23 3 Tool for Reporting Note The created report can also be tested with the help of the Report Builder. The tag browsing functionality of the delivered standard templates was triggered by an external function that although known in the Report Builder, can only be used together with an Internet Explorer. Therefore you cannot fully test the SIEMENS standard templates in the Report Builder environment. Once you have created a report template you can test it with the help of the "run" function in the Report Builder environment. Figure 3-2: Test of a report template V1.0, Entry ID:

24 3 Tool for Reporting Connecting the Report Builder with the Report Server Prerequisite for testing a report template in the report builder is that the report builder is connected with the report server. For this purpose you have to detect the URL of the report builder, for example, with the help of the report service configuration manager. You can start it with "Start > Microsoft SQL Server 2008 R2 > Configuration Tools > Reporting Services Configuration Manager". It can be found in the web service URL menu. Figure 3-3: Detecting the URL of the Report Server 24 V1.0, Entry ID:

25 3 Tool for Reporting The detected URL is to be entered in the Report Builder options in the "Settings" menu Figure 3-4: Report Server Settings in the Report Builder When the report builder is connected with the report server, this is visualized with the following icon in RB. Figure 3-5: Connected report server Processing report template Report templates are Report Description Language (RDL) Files. RDL files can be processed, for example, with the MS Report Builder. The RDL files are downloaded into a work directory with the help of the IS web application. Once they have been modified, the RDL files can be uploaded to the IS again. Subsequently, the modified reports are ready to be used in IS. This way it is possible to create individual report templates. V1.0, Entry ID:

26 3 Tool for Reporting Testing standard report templates with the report builder In order to test standard report templates with the report builder, proceed as follows: 1. Start the Report Builder. 2. Open the "Alg_Table_By_Timestamp" template. Note If you change the template, you change the PCS 7 standard. 26 V1.0, Entry ID:

27 3 Tool for Reporting 3. "Start" the report template in the report builder. For this purpose, click the "start" button of the Report Builder. 4. Specify the values of the "Project", "TimeBegin", "TimeEnd" and "user text block" parameters. TimeBegin = start time of the database query, TimeEnd = end time of the database query, user text block = definition of what text blocks of the message of the database query are to be returned. 5. Click the "View Report" button. The report is displayed in the Report Builder. V1.0, Entry ID:

28 3 Tool for Reporting Downloading report template and changing name Downloading report template Report templates are saved in the information server database. In order to process them with the help of the report builder, the report templates have to be loaded to the main memory of the local computer. Procedure 1. Connect with the Internet Explorer on the information server. 2. Select the template that you want to process. 3. Click the "Download" button. 4. Click the green arrow for download 5. The "File Download" dialog appears. Click the "Open" button. 6. The "Connect to Report Server" dialog appears. Click the "Connect" button. Result You have opened the report template in the report builder. And you have connected with the report builder on the report server. 28 V1.0, Entry ID:

29 3 Tool for Reporting Changing the name of the uploaded report template When you download a report template from the information server, change it and subsequently load it back to the IS, it will have the same name on the Runtime interface as on the IS. Procedure Since this may lead to confusions, you should change the name of the template. 1. Expand the Parameter folder. 2. Open the properties of the Localization parameter. 3. Open the Default Values menu. 4. Open the expression with the fx button. V1.0, Entry ID:

30 3 Tool for Reporting 5. Change the first value of the "Name_" + Code.GetString("Alg_Table_by_Timestamp_LocalName",User!Language) string in the Expression dialog to = "Name_" + Code.GetString("MyMessages",User!Language). 6. Save the report template on the local hard drive under the name MyMessages. 7. Click the "Upload" button in the IS client. 8. Use the browser button to select the "MyMessages.rdl" RDL file. 9. Click Upload. Result You have uploaded a report template with the name MyMessages on the IS. 30 V1.0, Entry ID:

31 3 Tool for Reporting Changing icon of the report template The icon of a report template can be changed, if required. Files with PNG format are used as icons. There are already several example icons available on the information server. They can be found in the following directory: C:\Program Files\Siemens\Information Server\Web\Images\Information Server Figure 3-6: Icon selection Procedure You can also create the icons for your report templates yourself (e.g. with a drawing program). In order for the used icons to be displayed when exchanging report templates between the different information servers, they have to be available on all servers and they have to be correctly referenced. The icon is specified in the RDL file with the help of parameter and its default value. Example: "Information Server/dashboard.png". 1. Open the report template in the Report Builder. 2. Expand the Parameter folder. 3. Open the properties of the "@Icon" parameter. 4. Select the "Default Parameter" menu. 5. Enter the Information Server/dashboard.png path as value. V1.0, Entry ID:

32 3 Tool for Reporting Figure Parameter 6. Save the report template on the local hard drive. 7. Open the Internet Explorer and connect with the IS. 8. Create a new folder with the name "xmessages" in the "Reporting" menu and select the folder. 9. Click the Upload button. Result You have uploaded a report template with a changed icon to the IS. 32 V1.0, Entry ID:

33 3 Tool for Reporting Calculations With the help of the report builder you can perform numerous calculations. If, for example, a text field is placed in an existing report template and the expression dialog is opened, many functions can be selected. Procedure 1. Connect with the Internet Explorer on the information server. 2. Mark the Trend report template in the "Reporting" menu in the tag folder. 3. Click the "Download" button. 4. Click the green arrow for download. 5. Click "Save" in the "File Download" dialog. 6. Save the template on your hard drive under the name MyTrend.rdl. 7. Click "Open" in the "Download Complete" dialog. The report template is now opened in the Report Builder. 8. Click "connect" in the "Connect to Report Server" dialog. 9. Open the "Insert" menu in the Report Builder. 10. Add a text box in the report template. 11. Select the text box and open the context menu with the right mouse button. V1.0, Entry ID:

34 3 Tool for Reporting 12. Select the "Expression" menu item. 13. Select Category = Dataset, Item = DataSet1 and double click Value = Sum(ValueFloat). Result 14. Click the OK button. 15. Save the changes and load the report template onto the IS. 16. Test the changed report template. In the changed trend template there is a text box that calculates and displays the sum via all ValueFloat values of Dataset1. 34 V1.0, Entry ID:

35 3 Tool for Reporting Direct SQL statements in the report builder For the creation of individual SQL queries, knowledge in database programming is required. The basics of database programming are not included in the scope of this document. This is why this is only an example here, where not all terms are explained in full detail. In the report builder you can program the process historian database, called HistorianStorage. However, the database query of a report template is displayed via the information server. The information server is linked with the process historian database via a linked server. This has to be considered respectively in the syntax of the SQL query. It is recommended to program these SQL queries against a DB view. Basic procedure 1. Connect with the SQL server management studio on the information server SQL server instance called "INFSERVER" if you have an information server without PH installation. Connect with the SQL server management studio on the process historian SQL server instance called "Historian" if you use a combined PH /IS installation. 2. Navigate to the linked server to the "HistorianStorage" process historian database. V1.0, Entry ID:

36 3 Tool for Reporting Exemplary SQL query 3. Design your individual SQL query. 4. Copy this SQL query and implement it in the report template with the help of the report builder. The following example shows a database query for the current 1000 entries of the "HistorianStorage" database via the "VTagValue" database view. SELECT Top 1000 [TagUID],[TimeStamp],[DataGroupID],[SourceNodeID],[InternalFlags],[Flags],[Quality],[ValueFloat] FROM [LS_Master_Test_PH_MP].[HistorianStorage].[TLG].[VTagValue] 36 V1.0, Entry ID:

37 3 Tool for Reporting 3.3 Date and Time Timestamps are stored in the database in the UTC format. The local time of the called application has to be converted to UTC. Figure 3-8: Principle of conversion from local time into UTC format The conversion of the entered times at runtime is performed in the query parameters of the datasets: Example: <QueryParameter <Value>=Parameters!TimeBegin.Value.ToUniversalTime()</Value> </QueryParameter> The views of the PH database are designed in a way so that they provide the UTC times in the same way as WinCC. In the resultset of the information server the times are then reconverted to the local client time. For the conversion there is a "ToUniversalTime" VB.Net V1.1 method. Note More information on this method can be found in the appropriate VB.Net documentation on the internet. V1.0, Entry ID:

38 3 Tool for Reporting Examples for time functions Now DateAdd In this chapter you can find a description of the time functions that are used in the report templates of the process historian. Returns a value that contains the current data and the current time of the system. = Now() A specified number of time intervals can be added to an input value. The function returns this calculated datetime value. Syntax: DATEADD(datepart, number, date) Arguments: datepart This parameter specifies what date is to be added a number. number The value by which the "datepart" parameter is incremented. This value has to be an integer value that is known when analyzing the expression. date An expression that returns a valid date or a string in date format. Example: = DateAdd("n",-2,Now()) ToUniversalTime Example of how a current time value is converted to the UTC time format in the report builder. = Parameters!TimeBegin.Value.ToUniversalTime() 38 V1.0, Entry ID:

39 3 Tool for Reporting Units and abbreviations The following table lists the date units and abbreviations that will be detected by the expression evaluation. There is no case sensitivity for datepart names. Table 3-1: Units and abbreviations for time functions Year Quarter Month Dayofyear Day week Weekday Hour Minute Second Millisecond Date unit yy, yyyy qq, q mm, m dy, y dd, d wk, ww dw, w Hh mi, n ss, s Ms Abbreviations V1.0, Entry ID:

40 3 Tool for Reporting Conversion of timestamp to local time In this example, it is shown how the UTC time values of the dataset are converted into local time in the report builder. The Trend template of the information server is used as an example. Example =TimeZone.CurrentTimeZone.ToLocalTime(Fields!Timestamp.Value) In the figure below, it is illustrated where the time conversion is configured in the report template. Figure 3-9: Conversion of the timestamps of the trend template TimeBegin default timestamp calculation In this example, it is shown how the default start time of parameter is detected in the report template. The default start time is detected in the local time. The Trend template of the information server is used as an example. Example = DateAdd("n",-2,Now()) In the figure below, it is illustrated where the time conversion is configured in the report template. 40 V1.0, Entry ID:

41 3 Tool for Reporting Figure 3-10: TimeBegin parameter Conversion of the timestamp in the dataset of the report template Example start time which is transferred in the local time as parameter has to be reconverted to the UTC time for the DB query. = Parameters!TimeBegin.Value.ToUniversalTime() In the figure below, it is illustrated where the time conversion is configured in the report template. V1.0, Entry ID:

42 3 Tool for Reporting Figure 3-11: Conversion of the timestamp into UTC 42 V1.0, Entry ID:

43 3 Tool for Reporting 3.4 Use Cases Use Case1: Creating a new report template Stored procedures GetTagSnapshots The following example shows how you can create a new report template on the basis of the ISBase.rdl template and the udsp_gettagsnapshot stored procedure. In this use case two values of the same PH tag are red for different timestamps. With help of this values a substraction will be calculated. A stored procedure is a collection of SQL statements that can be called in a similar way as a function. A stored procedure of the PH provides a dataset as a result that can be displayed in a report template and can be further processed. The GetTagSnapshot stored procedure is a standard PH stored procedure. It detects the values for two timestamps from the PH archive. With these two values calculations can subsequently be made. ISBase RDL In the ISBase.rdl template, required basic report data is already provided in order to create a separate report template. This data is accepted and does not have to be reconfigured. The following figure shows the data of the "ISBase.rdl" template. The existing parameters and datasets are explained below. Figure 3-12: Data of the "ISBase.rdl" template V1.0, Entry ID:

44 3 Tool for Reporting Once the information server has been installed, the Base.rdl report is located in the following directory: Installation drive\program Files(x86)\SIEMENS\Information Server\RDL. Figure 3-13: ISBase.rdl storage Once installed on the hard drive, the "ISBase.rdl" template exists on the IS, however, it is not "uploaded" on the IS. The IS Base.rdl can be uploaded on the IS and is ready to function with the help of the report builder. Note The "ISBase.rdl" template, provided with the PCS 7 V8.0 Upd1 refers to the resource file of version V8.0. The link to the required resource has to be adjusted. For this purpose, the reference string below can be used. Reference String Siemens.Information Server.Common.ExternalResources, Version= , Culture=neutral, PublicKeyToken=10e f60eab The reference string changes if a newer version of the information server is installed. In this case, the reference string has to be adjusted in the self-generated report template. The current reference string can be can be found in a delivered standard template. The reference string is adjusted in the "Properties" of the report template. In the figure below, it is shown where the reference string has to be entered in the report template. 44 V1.0, Entry ID:

45 3 Tool for Reporting Figure 3-14: Report Properties, configuration of the reference string Parameters of the "ISBase.rdl" template All report templates require a data source. The data source of the ISBase.rdl has the name "InfoServer" and represents the connection on the report server. If a report template is opened at runtime, the udsp_getprojects stored procedure is executed in order to fill the Projects dataset with the project data. The project data is the project name and the ProjectGuid. With the help of parameter a project can be uniquely identified. With a project, an OS system is meant here that exports data onto the process historian. The udsp_getprojects SP also detects the users logged in on the IS. For this purpose, the "udsp_getprojects" function contacts the MS Reporting Services, in order to detect the available projects for the logged in users. If a project is selected in the report template at runtime, the are written. Datasets in the report template are created with the help of database queries. The content of the datasets are displayed in the report builder, for example, with the help of tables and A project can be uniquely identified with the help of ProjectGuid. With a project, an OS system is meant here that exports data onto the process historian. A PH usually saves the data of several OS systems. V1.0, Entry ID:

46 3 Tool for The parameter includes the name of the catalog that is used on the IS. For each report template the IS shows an icon on the web interface. The storage location of the icon is specified as relative path via parameter. The parameter is used for the localization of template parameters and the template name. The IS web site recognizes the template parameters and the template name. For each recognized parameter a "default" parameter is added to parameter. The first "default" parameter is reserved for the template name. The following entries reference to visible parameters in the report The "@TestConnection" parameter contains information on the problems that occurred on the information server when executing the template. These error codes are displayed as helpful information on the web interface of the IS. Example The report template parameters "@Icon", "@ProjectGuid" and "@Catalog" have been incorporated into the IDBase.rdl report template, in order to display the values of the parameters at runtime. In the figure below, this report template can be seen at runtime. 46 V1.0, Entry ID:

47 3 Tool for Reporting Figure 3-16: Report template at runtime Standard report template parameter A standard report template is a report template that is available on the web interface after the installation of the information server. Time Procedure Timestamps in the PH database are stored in UTC format. PH database queries are usually executed over a specified period. This period is specified in the standard templates via parameters. The "@TimeBegin" and "@TimeEnd" parameters are converted to the UTC format before the database query. In the resultset of the database query, the timestamp is reconverted to the local computer time. All timestamps in the report are therefore in local computer time. A report parameter of the Date/Time data type has the effect that a DateTime control is displayed on the web interface of the information server. With the help of the DateTime control, you can specify the time period of the database query at runtime. To create a new report template, please proceed as follows: 1. Start the report builder. The report builder has to connect itself successfully on the MS Report Server. The MS Report Server is part of the MS Reporting Services. In the screenshot below, the report builder is displayed with the correct connection to the MS Report Server. Figure 3-17: Report Builder dialog V1.0, Entry ID:

48 3 Tool for Reporting 2. Open the ISBase.rdl report template with the report builder. The ISBase.rdl template can be found under the following path: C:\Program Files(X86)\Siemens\Information Server\RDL\ISBase.rdl 3. Save the ISBase.rdl template under the name Calculation1.rd on your local hard drive. 4. Add the ParamTagIds parameter. For this purpose, right click the Parameter folder. Click the "Add Parameter" menu item. 48 V1.0, Entry ID:

49 3 Tool for Reporting The "ParamTagIds" parameter name is a key word to show the tag browsing dialog on the Runtime interface of the information server. With the help of the tag browsing dialog, you can select archive tags that are displayed in the report. Example of tag browsing dialog of the IS Figure 3-18: Tag browsing dialog of the IS Configure the ParamTagIds parameter in the General menu as follows: Name = ParamTagIds, Datatype = Text, Allow multiple values = true Figure 3-19: Dialog of the Report Parameter Properties V1.0, Entry ID:

50 3 Tool for Reporting 5. Add the parameters "time1" and "time2" and configure them as shown in the figure below. Figure 3-20: Dialog of the Report Parameter Properties 50 V1.0, Entry ID:

51 3 Tool for Reporting Figure 3-21: Dialog of the Report Parameter Properties 6. Add a new dataset named DataSet1. For this purpose, right click the Datasets folder in the report builder. Then click the "Add Dataset" menu item. The Dataset Properties dialog appears. 7. Select Use a dataset embedded in my report in the Dataset Properties dialog. 8. From the Data Source drop-down list select the InfoServer entry. V1.0, Entry ID:

52 3 Tool for Reporting 9. Enter the following query: nvarchar(4000) = ' exec [' + '].[IS].[udsp_getTagSnapshots] ''' + ''', ''' + CONVERT(nvarchar(23),@time1,20)+''', ''' + CONVERT(nvarchar(23),@time1,20)+''', ' exec (@stmt) Click the Refresh Fields button in the Dataset Properties dialog. 52 V1.0, Entry ID:

53 3 Tool for Reporting The Define Query Parameters dialog appears. 10. Click the OK button in the dialog. The parameter names are created in the Parameters menu of the Dataset Properties dialog. V1.0, Entry ID:

54 3 Tool for Reporting 11. Enter as parameter for parameter value with the drop-down menu. Enter all other parameter values in the same way as shown in the screenshot below. 12. Click the fx button of parameter value. Expand the Expression by the "ToUniversalTime()" method. 13. Accept the changes with the "OK" button and expand the expression for the parameter in the same way. 54 V1.0, Entry ID:

55 3 Tool for Reporting Note In the screenshot below, the connection between query parameters and the report template parameters is shown. Figure 3-22: Correlation between query parameters and report template parameters V1.0, Entry ID:

56 3 Tool for Reporting 14. Go to the Fields menu in the Dataset Properties dialog. Click the Add button and subsequently the Query Field menu item. Repeat this procedure for altogether three query fields. 15. Enter = time1, time2 and TagName for the field name. Enter = time1, time2 and TagName for the field sources. 16. Generate a Calculated Field named Consumption in the same way as the query fields. 56 V1.0, Entry ID:

57 3 Tool for Reporting 17. Enter the following expression via the f(x) button for the field source of the Consumption calculated field: Fields!time2.Value-Fields!time1.Value V1.0, Entry ID:

58 3 Tool for Reporting 18. Exit the Dataset Properties dialog with the OK button. 19. Go to the "Insert" menu in the report builder. 20. Click the Insert Table button in the "Tables" menu. 21. Place the table in the report builder. 22. Place the data fields "time1", "time2" and "TagName" via drag & drop into the inserted table. Place the Consumption data field via drag & drop to an empty place in the report template. 58 V1.0, Entry ID:

59 3 Tool for Reporting 23. Save the Calculation1 report template. 24. Open the Internet Explorer and connect with the information server. 25. Open the Reporting menu. 26. Click the create folder button and create a new folder named MyTemplate. 27. Select the MyTemplates folder and click the upload button. 28. Enter the path of the "Calculation1" report template and click the "Upload" button. 29. Enter your project and select an archive tag and enter the time values time1 and time2. V1.0, Entry ID:

60 3 Tool for Reporting 30. Click the "Show Report" button. Note A fully configured Calculation1.rdl report template is included in the scope of this "Application & Tools" document and it can be used for checking the own configuration. 60 V1.0, Entry ID:

61 3 Tool for Reporting Use Case 2: Consumption counter This use case is realized as an example in the Consumption1.rdl template and is included in Application & Tools. A step-by-step instruction is not the aim of the use case 2. The call of the stored procedure and the general setup of the report template is explained in detail in the Use GetTagSnapshots in the ISBase.rdl template use case 1. This is why not all details are explained in this use case. The use case consumption counter is a practical application of the GetTagSnapshots SP. The report template can be uploaded to be tested on the IS just as use case 1. In the example, a tank farm with 5 tanks is used. The flow meters write the integrated flow of each tank continuously into the long-term archive. A layer report is to be created in which the removed material of each tank is displayed. In addition, the total removal of all tanks is to be calculated. The shift starts at 6:00 am and ends at 5:00 pm. Figure 3-23: Display of a tank farm: udsp_gettagsnapshots stored procedure The stored procedure reads values from the archive from a list of tags, for two timestamps each at a time. In the report template it can be calculated with these values. In this example, the following applies: Material withdrawal = measured value(t2) measured value(t1). V1.0, Entry ID:

62 3 Tool for Reporting Call of the IS.udsp_getTagSnapshots stored procedure in the SQL server MMS. Here as an example, with the TagUID of an archive value. This is not a step-bystep instruction on how to call an SP in the SQL server MMS. The screenshot below shows the call of the SP and its The resultset of the SP can also be seen in the screenshot. The resultset fields have the names TagName, time1 and time2. Figure 3-24: Call of udsp_gettagsnapshots Consumption1 dataset SQL statement With the following SQL statement the dataset for the report template is created in the report builder: nvarchar(4000) = ' exec [' + '].[IS].[udsp_getTagSnapshots] ''' + ''', ''' + CONVERT(nvarchar(23),@time1,20)+''', ''' + CONVERT(nvarchar(23),@time2,20) + ''' ' exec (@stmt) 62 V1.0, Entry ID:

63 3 Tool for Reporting Consumption1.rdl In the figure below, you can see the opened Consumption1.rdl in the report builder with its parameters and datasets. Figure 3-25: Consumption1.rdl in the report builder Testing the "Consumption1.rdl" template Once the "Consumption1.rdl template has been loaded onto the information server, the project, the day and the archive tags can be specified. Proceed in the same way as for Use Case1. In the figure below, the report template parameters are displayed at runtime in the information server. Figure 3-26: Information server dialog V1.0, Entry ID:

64 3 Tool for Reporting The report can be created via the "Show report" button. Figure 3-27: Report view 64 V1.0, Entry ID:

65 4 Working with the Database 4 Working with the Database The database includes data of OS servers, OS single stations and SIMATIC BATCH servers. The SIMATIC BATCH database structure is not subject of this documentation. Long-term relevant archive tags and OS messages are stored in the PH database. In the following chapter, an example explains what database views are required for an OS report with archived OS tags and OS messages. We generally recommend using database views and not database tables for the reporting, since the data structure for the tables may change in the course of further development steps. However, it is made sure that the database views remain unchanged. As a result, report templates are still able to function even after a software upgrade. In order not to readjust the internally generated report templates when there is a change of database, it is also not recommended to work with SELECT*, but to explicitly call all database columns. It is furthermore recommended to create datasets with the stored procedures of IS, since they have already been tested and a better performance can be achieved. 4.1 OS archive tags Long-term relevant OS archive tags are saved in the PH database. For this purpose, there is a tag browsing view called IS.VTagBrowsing for each OS server. In this view the tag names are assigned with a unique TagUID key. Tag values can only be identified on the basis of the TagUID key in the TLG.VTagValue view. When the tag values are to be assigned to the tag name, you have to connect the two views via a "Join" IS.VTagBrowsing In the IS.VTagBrowning view, all TagNames are assigned to the unique "TagUID" keys. Figure 4-1: IS.VTagBrowning view: TLG.VTagValue With the TLG.VTagValue view you can read tag values. Prerequisite for this is that the TagUID key is known. Figure 4-2: TLG.VTagValue view: V1.0, Entry ID:

66 4 Working with the Database Designing SQL polls at database level The use of the SQL server management studio is a procedure when developing SQL queries. A graphic query designer which is part of the SQL server MMS, can also be used for this purpose. Example In the figure a join of the VTagBrowsing view is designed with the VTagValue view. The connecting table field is the TagUID key. Figure 4-3: Query designer 66 V1.0, Entry ID:

67 4 Working with the Database For reasons of performance, the database queries are designed as stored procedures for the process historian. All Stored Procedures which belong to the data base scheme IS can be utilized by the user. We recommend the utilization of these tested Stored Procedures. NOTE Since the Table-valued Function IS.udf_GetTagValues in version V8.0 SP1 has been removed we recommend instead to utilize the Stored Procedure IS.udsp_getTagTable or IS.udsp_getTagTableWithoutName for reading PH tags. NOTE How to create database queries with the help of the SQL server management studio can be found out in the appropriate Microsoft documentation. V1.0, Entry ID:

68 4 Working with the Database 4.2 Working with existing standard stored procedures Standard stored procedures here are the SPs that are included in the delivery of the PH. The standard stored procedures are described in chapter 7 Target System BL. Here, it is shown on an example how the stored procedures can be called and the result of the call is displayed udsp_gettagtable example Below, the SQL call of the SP in the SQL server MMS is described. Detailed information can be found in the Basic PH functions chapter. USE [HistorianStorage] GO /****** Object: StoredProcedure [IS].[udsp_getTagTable] Script Date: 06/03/ :20:40 ******/ SET ANSI_NULLS ON GO SET QUOTED_IDENTIFIER OFF GO create procedure [IS].[udsp_getTagTable] ( ) datetime2 Select TagName, Convert(datetime2,TimeStamp,1) as Timestamp, ValueFloat,Quality, Flags from [TLG].[VTagValue] as TV inner join [IS].[VTagBrowsing] on TV.TagUID = [VTagBrowsing].[TagUID] where (TimeStamp AND TimeStamp AND GO TV.[TagUID] IN (@tagids) 68 V1.0, Entry ID:

69 4 Working with the Database Examples for TagUID, Tag Name, Time Stamp You can find the UID tag to a TagName in the VTagBrowsing view. TagUID: 2E7C5D5B-8FBD-4F7C-A30C-9A4ABAAF9040 TagName: Trend/Simul/MEAS.U TimeStamp :00: :00 Example of call with SQL server MMS From the following example, you can see how to always call the SP in the SQL server MMS. USE [HistorianStorage] GO int = = = ' = ' :00:00' SELECT 'Return Value' GO Figure 4-4: Table view V1.0, Entry ID:

70 4 Working with the Database udsp_gettagtrend example Example with SQL server MMS Below, the SQL call of the SP in the SQL server MMS is described. Detailed information can be found in the Basic PH functions chapter. USE [HistorianStorage] GO int = = = ' = ' = 5 SELECT 'Return Value' GO Figure 4-5: Table view 70 V1.0, Entry ID:

71 4 Working with the Database "udsp_gettagaggregetion" example Example with SQL server MMS In this example, the maximum value of an archive tags is calculated = specifies the calculation interval in seconds. There are 3600 seconds this is why you will receive the result in a table with six rows. Note Figure 4-6 USE [HistorianStorage] GO int = = = ' = ' = = 600 SELECT 'Return Value' GO N signifies that the string is specified in UNICODE. Figure 4-7: Table view Note Report parameters such as, for example, "@Proj" or "@Catalog" cannot be used in SQL queries. This is why database queries are executed in the standard report templates as string. This way, the report parameters can be used in SQL queries. V1.0, Entry ID:

72 4 Working with the Database Example: Executing SQL query as string From this SQL query, you can see how a query can be executed as string. nvarchar(4000) nvarchar(36) nvarchar(36) nvarchar(36) nvarchar(36) nvarchar(36) nvarchar(36) = 'DB_PE_MP_71_Prj' = '8DA4A5D A2DA-77E8ED2F81C3' = ' :00:00' = ' :00:00' = 'Max' = '600' = ' exec [' + '].[IS].[udsp_getTagAggregation] '''+@TagID+''', '''+@TimeStart+''', '''+@TimeEnd+''', '''+@Agregation+''', '+@Samples+' ' exec (@stmt) 72 V1.0, Entry ID:

73 4 Working with the Database Example: Creating a hard-coded dataset in the report builder with the help of the udsp_gettagaggragation SP From this example, you can see how you can specify the TagUID, start and end time of the query hard-coded in the report builder, in order to create a dataset. exec [DB_PE_MP_71_Prj].[IS].[udsp_getTagAggregation] '8DA4A5D A2DA-77E8ED2F81C3', ' :00:00', ' :00:00', 'Max', 600 Figure 4-8: Dataset Properties dialog V1.0, Entry ID:

74 4 Working with the Database Test in the report builder In the display below, you can see the display of the datasets at runtime in the report builder. Figure 4-9: Report Builder dialog In the figure below, you can see the display of the datasets at runtime on the IS client. Figure 4-10: Test after loading on the IS Note From a programming point of view, it is easiest to process a dataset with a stored procedure and hard-coded transfer values; however, it offers the least flexibility. 74 V1.0, Entry ID:

75 4 Working with the Database udsp_getmessagesperday example Below, the SQL call of the SP in the SQL server MMS is described. Detailed information can be found in the Basic PH functions chapter. USE [HistorianStorage] GO int = = = = N' = N' = '1,2,3,4,5,6,7,8,9,10,16,17,18' SELECT 'Return Value' GO Figure 4-11: Table view V1.0, Entry ID:

76 4 Working with the Database udsp_getmessagesper10minutes example Below, the SQL call of the SP in the SQL server MMS is described. Detailed information can be found in the Basic PH functions chapter. Example: Call in the SQL server MMS From the following example, you can see how to call the SP in the SQL server MMS. USE [HistorianStorage] GO int = = = N' = N' :00:00' SELECT 'Return Value' GO Figure 4-12: Table view 76 V1.0, Entry ID:

77 4 Working with the Database udsp_ getquantitybymessageclass example Below, the SQL call of the SP in the SQL server MMS is described. Detailed information can be found in the Basic PH functions chapter. Example call in the SQL server MMS From the following example, you can see how to call the SP in the SQL server MMS. USE [HistorianStorage] GO int = = = = N' = N' :00:00' SELECT 'Return Value' GO Figure 4-13: Table view V1.0, Entry ID:

78 4 Working with the Database udsp_ getquantitybymessageclass example Below, the SQL call of the SP in the SQL server MMS is described. Detailed information can be found in the Basic PH functions chapter. Example call in the SQL server MMS From the following example, you can see how to always call the SP in the SQL server MMS. USE [HistorianStorage] GO int = = = = N' = N' :00:00' SELECT 'Return Value' GO Figure 4-14: Table view 78 V1.0, Entry ID:

79 4 Working with the Database 4.3 Working with self-generated stored procedures For special report requirements that cannot be covered with the standard stored procedures, it may be necessary to program separate SPs. This chapter explains a procedure based on the udsp_getmessagetable SP. The stored procedure is available as udsp_getmessagetable.sql demo file Integrating the udsp_getmessagetable stored procedure into the PH database 1. Open the SQL Server Management Studio. 2. Open the "udsp_getmessagetable.sql" file via the File > Open > File menu. 3. Select the entire SQL code and execute it with the Execute button. V1.0, Entry ID:

80 4 Working with the Database The code must be executed without errors. 4. Close the SQL server MMS. 5. Open the SQL server MMS. Result In the Programmability folder of the HistorianStorage database the udsp_getmessagetable stored procedure is available. Figure 4-15: udsp_getmessagetable stored procedure 80 V1.0, Entry ID:

81 4 Working with the Database Example call of udsp_getmessagetable With the following call, you can use the udsp_getmessagetable stored procedure in the SQL server MMS. USE [HistorianStorage] GO /* Parameter name Datatype Uniqueidentifier Project Int Language Datetimeoffset(7) Begin Datetimeoffset(7) End nvarchar(max) */ int = = = = N' :00:00 = N' :00:00 = N'Order By Timestamp' SELECT 'Return Value' GO Result Table As a consequence of the SP call, you will receive this table as return value. Figure 4-16 Result Table udsp_getmessagetable V1.0, Entry ID:

82 4 Working with the Database Integrating udsp_getmessagetable in ISBase.rdl stored procedure 1. Start the report builder and open the "ISBase.rdl" template. 2. Add dataset. 3. Configure the "Dataset Properties". Example of dataset properties in the report template: Query example USE [HistorianStorage] int = [IS].[udsp_getMessageTable] '40c15ada-df7f-49bc-968b-b3779ea46150', 1031, ' :00:00', ' :00:00', 'Order By Timestamp' SELECT 'Return Value' 82 V1.0, Entry ID:

83 4 Working with the Database Note The report have to be adjusted individually. 4. Click the Refresh Fields button. Figure 4-17: Dataset 5. Display messages in the table via drag & drop 6. Save the report template under the name "udspgetmessagetable.rdl" and load it onto the information server. 7. Test the report template. V1.0, Entry ID:

84 4 Working with the Database Result In this screenshot you can see the messages. The messages were read with the help of the udsp_getmessagetable SP from the HistorianStorage database. Figure 4-18: Readout messages 84 V1.0, Entry ID: