Professional Services. Plant Applications SDK Guidelines GE FANUC AUTOMATION. Prepared by. Donna Lui Professional Services

GE FANUC AUTOMATION Professional Services Plant Applications SDK Guidelines Prepared by Donna Lui Professional Services GE Fanuc Automation SDK Guidelines Page 1 of 22

All rights reserved. No part of this publication may be reproduced in any form or by any electronic or mechanical means, including photocopying and recording, without permission in writing from GE Fanuc Automation. Disclaimer of Warranties and Liability The information contained in this manual is believed to be accurate and reliable. However, GE Fanuc Automation assumes no responsibilities for any errors, omissions or inaccuracies whatsoever. Without limiting the foregoing, GE Fanuc Automation disclaims any and all warranties, expressed or implied, including the warranty of merchantability and fitness for a particular purpose, with respect to the information contained in this manual and the equipment or software described herein. The entire risk as to the quality and performance of such information, equipment and software, is upon the buyer or user. GE Fanuc Automation shall not be liable for any damages, including special or consequential damages, arising out of the user of such information, equipment and software, even if GE Fanuc Automation has been advised in advance of the possibility of such damages. The user of the information contained in the manual and the software described herein is subject to the GE Fanuc Automation standard license agreement, which must be executed by the buyer or user before the use of such information, equipment or software. Notice GE Fanuc Automation reserves the right to make improvements to the products described in this publication at any time and without notice. 2007 GE Fanuc Automation. All rights reserved. Microsoft is a registered trademark of Microsoft Corporation. Any other trademarks herein are used solely for purposes of identifying compatibility with the products of GE Fanuc Automation. Proficy is a trademark of GE Fanuc Automation. GE Fanuc Automation SDK Guidelines Page 2 of 22

Table of Contents 1.0 Introduction...4 1.1 Purpose...4 1.2 Terminology...4 1.3 Contact...4 2.0 SDK...5 3.0 SDK Functions...6 3.1 Connection Function...6 3.2 Query Function...6 3.3 Publish Function...6 3.4 Subscribe Function...8 3.5 Database Execute Function...8 3.5.01 ExecuteCommand...8 3.5.02 ExecuteSQL...9 4.0 Multiple Record Sets...10 5.0 Troubleshooting...11 5.1 LastError Property...11 5.2 SDK Log File...11 5.3 SQL Profiler...11 6.0 SDK in.net...12 6.1 Subscribe Function in.net...12 7.0 Proficy ActiveX Controls...14 7.1 AutoLog...14 7.1.01 ExecuteCommand...15 7.1.02 ScrollTo...16 7.1.03 Time Format...16 7.2 TrendSheet...16 7.3 Schedule View...17 7.3.01 ExecuteCommand...19 8.0 References...21 9.0 Revision History...22 GE Fanuc Automation SDK Guidelines Page 3 of 22

1.0 Introduction 1.1 Purpose This document is to provide a guideline for commonly used functions in Plant Applications Software Development Kit (SDK). The contents of this document are for informational reference only and are not supported by GE Fanuc. GE Fanuc reserves the right to change the contents of this document at any time. 1.2 Terminology Term MES PA SDK Definition Manufacturing Execution System Plant Applications Software Development Kit 1.3 Contact Any questions, comments or desired additions to this document should be forwarded to: Donna Lui Project Engineer GE Fanuc (604) 629-4526 Donna.Lui@gefanuc.com GE Fanuc Automation SDK Guidelines Page 4 of 22

2.0 SDK The SDK may be used under any Win32 platform using a development language that supports Microsoft COM/DCOM. The SDK relies on the runtime version of the Plant Applications Client Server SDK (CSS). The Plant Applications CSS must be installed prior to the installation of the SDK on any client wishing to access the Plant Applications System through the SDK. The PA SDK is not prepared for usage with ASP and.net. The new ISI package should support this combination of the development tools. The Plant Applications SDK is a COM DLL that must be instantiated prior to use. Each instance of the SDK connects and converses with a single Plant Applications Server. Multiple instances of the SDK may be created, however it is up to the developer to maintain this collection and respond to events from the appropriate instance. Some general information is provided below regarding the SDK naming and dependencies. SDK DLL: ProfSDK.dll Class Name: Proficy_SDK.Server GE Fanuc Automation SDK Guidelines Page 5 of 22

3.1 Connection Function 3.0 SDK Functions Startup function is used to open a connection to Plant Applications. The Plant Application server name, user name and user password are required when using the Startup Function. Here is the sample code for Startup function is, Public WithEvents ProfSDK As Proficy_SDK.Server Set ProfSDK = New Proficy_SDK.Server ProfSDK.Startup(ServerName, UserName, UserPassword) To disconnect from Plant Application server, Shutdown function can be used, and here is the script, ProfSDK.Shutdown() 3.2 Query Function SDK developed an extensive set of Query functions for client to retrieve Plant Application data. In order to use the function, record type returned from the query function must be first declared. Following is the VB sample code for declaring production unit record type and execute the production unit query function, Dim MyUnits As Proficy_SDK.ProductionUnits Set MyUnits = ProfSDK.QueryProductionUnits( MyLine, * ) Each query function requires different set of input parameters. The parameters supplied can greatly affect the performance of the query. It is advised to pass in as much parameters as possible to limit the amount of records returned, and try to avoid return all records from database. It is also recommended to use a SQL statement or stored procedure instead of query functions if a customized SQL statement is more efficient. This can be done using the ExecuteCommand or ExecuteSQL functions described below. 3.3 Publish Function Publish function is used to send message back to the Message Bus in Plant Application system. Message must be first initialized using the InitializeMessage function. For example, if publishing a production event message, the code in VB is Dim MyEvent As Proficy_SDK.ProductionEvent Set MyEvent =ProfSDK.InitializeMessage(sdkRTProductionEvent) The message then needs to be populated based on the message type. Each message type has its own set of properties, but they all have one property in common, and it is the Transaction Type. Each message GE Fanuc Automation SDK Guidelines Page 6 of 22

needs to define the Transaction Type, and the most commonly used transaction type is sdkttadd, sdkttdelete, or sdkttupdate. If the message is related to adding a new record to Plant Application clients, then sdkttadd is used. If it is related to delete an existing record, then sdkttdelete is used. Finally, if an existing record needs to be updated, then sdkttupdate is used. Following is an example of populating a new production event message in VB code, With MyEvent.TransactionType = sdkttadd.linename = My Line.UnitName = My Unit.EventName = Event001.EndTime = Now().EventStatus = Complete End With The last step is to publish the message, and here is the code for publishing the above initialized production event message and taking default values for rest of the input parameters. ProfSDK.Publish(MyEvent) The first parameter, as stated above, is the initialized message. The next couple of parameters are the WriteDirect and ClientUpdateOnly. The WriteDirect is defaulted to False, which means a message is generated to request a database update through Database Manager. If WriteDirect sets to True, the message bypasses the Message Bus and updates the database by executing system stored procedures directly. As for the ClientUpdateOnly, the default value is False, which means a pre-message is published. Pre-message is to request Database manager to update the database. If the value is set to True, only post-message is published. Post-message indicates that the database has been updated and other services must be notified of the update. SDK Gateway ClientUpdateOnly = 1 Other Services WriteDirect = 0 Message Bus ClientUpdateOnly = 0 WriteDirect = 1 Database Manager Plant Apps GE Fanuc Automation SDK Guidelines Page 7 of 22

Figure 1. SDK Publish Function WriteDirect and ClientUpdateOnly Message Diagram The next few parameters are related to the SignOffUser and ApproveUser. These paramters are used for security validation. However, only a few message types have these parameters fully implemented, and they are tied to the last parameter TransNum. 3.4 Subscribe Function Subscribe function is used if the client wants to receive real time message from the message bus. There are two main parts in the subscribe function. The first part is to subscribe for the message with a defined message type and required parameters, and the second part is to receive the message. Here is a subscribe sample for production event, Proficy_SDK.Subscribe(Proficy_SDK.sdkRealtimeDataType.sdkRTProductionEvent, Line, Unit, Nothing) If there is a message in message bus related to above subscribe message type with the defined line and unit, the following MessageReceived function will get the message, Private Sub MessageReceived(ByRef Message As Object) Dim MyProductionPlanMessage As Proficy_SDK.ProductionPlan Select Case Message.RecordType Case Proficy_SDK.sdkRealtimeDataType.sdkRTProductionPlan MyProductionPlanMessage = Message End Select To unsubscribe a message, simply use the following Unsubscribe function, passing in the same parameters that used in the subscribe function. For example, to unsubscribe the above message, the VB code is Proficy_SDK.UnSubscribe(Proficy_SDK.sdkRealtimeDataType.sdkRTProductionEvent, Line, Unit, Nothing) 3.5 Database Execute Function There are two execute functions available under the database object, and they are ExecuteCommand, which is used for store procedure, and ExecuteSQL for SQL statement. 3.5.01 ExecuteCommand ExecuteCommand function is used to execute a SQL store procedure. The store procedure definition must be entered in client_sp_prototypes table. Following is an example of creating a record in table client_sp_prototypes, INSERT INTO client_sp_prototypes(server_cursor,input,command_text,sp_name) VALUES(0,2,'spLocal_SP1','spLocal_SP1') GE Fanuc Automation SDK Guidelines Page 8 of 22

Server_Cursor controls whether the SDK uses an implicit server-side cursor or a client-side cursor for returning the recordset back to the calling application. SQL server allocates space in tempdb to facilitate the server-side cursor, and there is a tempdb leaks in SDK that grows over time. It is recommended to set Server_cursor to 0 such that client-side cursor is used. There are four parameters in ExecuteCommand function. The first parameter is the store procedure name, which must be defined in client_sp_prototypes. The second parameter is the result set, which is the record set returned from the store procedure. The next parameter is the return code, which is value returned from store procedure, and usually used to indicate weather the executions inside the store procedure has been successful. ExecuteCommand could only return either the result set or return code, and cannot be both. The last parameter is the param array, which is used for input parameters. Following is an example of the ExecuteCommand function with two input parameters, Dim recordset As New ADODB.Recordset Dim returncode As Integer ProfSDK.Database.ExecuteCommand( StoreProcedure1, recordset, returncode, Input1, Input2 ) 3.5.02 ExecuteSQL ExecuteSQL is a simplified version of ExecuteCommand, and it executes a SQL statement. There are only two parameters in ExecuteCommand function, and they are the command and result set. The command is the SQL statement, while the result set is the returned record. Here is an example in VB code, Dim strcommandstring As string Dim recordset As New ADODB.Recordset strcommandstring = SELECT * FROM Prod_Units ProfSDK.Database.ExecuteSQL(strCommandString, recordset) GE Fanuc Automation SDK Guidelines Page 9 of 22

4.0 Multiple Record Sets When executing a custom designed store procedure, it is very often to have multiple record sets returned. In VB code, a recordset array has to be first defined for storing multiple record sets. The syntax for parsing 2 record sets in VB code is as follows, Dim ProfSDK As Proficy_SDK.Server Dim recordset(2) As ADODB.Recordset Dim returncode As Integer ProfSDK.Database.ExecuteCommand( StoreProcedure1, recordset(0), returncode, Input1, Input2 ) While Not recordset(0).eof <Parsing first record set> rs(0).movenext() End While recordset(1) = recordset(0).nextrecordset While Not recordset(1).eof <Parsing second record set> End While rs(0).close() rs(1).close() GE Fanuc Automation SDK Guidelines Page 10 of 22

5.1 LastError Property 5.0 Troubleshooting The best way to troubleshoot SDK is to create your own logs when using any SDK function. There is a LastError property, which stores the last error information for SDK. The syntax for getting the last error message in VB is, Dim ProfSDK As Proficy_SDK.Server ProfSDK.LastError.Message 5.2 SDK Log File There is also a common log file for SDK, which is ProficySDKErrors.Log. The log file is usually located under the \CommonFiles\Proficy\PlantApplications\ folder. 5.3 SQL Profiler SQL Profiler is used to trace all activities in the database. This can be used to troubleshoot SDK by tracing the database events after certain SDK functions are called. For example, you created a SDK application in.net framework, and you would like to know the database events after the application is executed. You can open a trace file in Profiler, and set the criteria for Application Name to be Microsoft (R).NET Framework. Then you run your application, and you will get details like which store procedures are called and what parameters are used. GE Fanuc Automation SDK Guidelines Page 11 of 22

6.0 SDK in.net The PA SDK is not prepared for usage with ASP and.net. The new ISI package should support this combination of the development tools. As mentioned before, SDK may be used under any Win32 platform using a development language that supports Microsoft COM/DCOM. Therefore, SDK can still be used in.net but not all functionalities are fully supported, and Subscribe function is one of them. Following shows an example on how you can make SDK Subscribe function works in.net. Please keep in mind that each subscribes function only works for one instance of server. If you have two screens that use the same subscribe function, even though passing different parameters, in the same instance, only one message will return to the instance, and the screen waiting for the message might not get the message. There are different workarounds for this behavior, one of them is to create two separate instances of Server (in Memory) but this solution has to be tested. The other workaround is to create a separate project for each form. 6.1 Subscribe Function in.net Since Subscribe function is not fully supported in.net environment, some client-side programming is needed when using Subscribe function in.net. Before showing the syntax, it is best to explain a few terms and how web page is generated in.net. VB.NET is our sample programming language for writing code in ASP.NET. ASP.NET is a server-side technology for creating dynamic web pages. SDK functions are called and executed in ASP.NET using VB.NET programming languages. There are six steps involved when generating a web page using ASP.NET. 1. A developer writes a set of instructions in VB.NET for creating HTML, and saves these instructions within a file on web server. 2. A user types a page request into their browser, and the request is passed from the client browser to the web server. 3. The web server locates the file created in step 1. 4. The web server follows the file instructions and creates a stream of HTML. 5. The web server sends the newly created HTML stream back across the network to the client browser. 6. The browser processes the HTML and displays the page. Once the HTML is created and sent off to the browser, it has no connection to the file instructions in VB.NET programming. Since SDK Message Received function is part of the instructions, the client GE Fanuc Automation SDK Guidelines Page 12 of 22

HTML page is unable to receive the messages as all messages are returned to the file located on the web server. In order to get the message to the client page, the message received has to first store in a place on web server, such as a pre-defined application or session variable. The client then has to call the instruction file on the webserver to get the stored message from the variable and return the message in HTML format. The client has to call the file periodically in order to get the most updated message. Following is a sample javascript for client to call the instruction file using XMLHTTP function every 20 seconds: function DoCallback(url) { var pageurl = url + "?callback=true"; var xmlrequest = new ActiveXObject("Microsoft.XMLHTTP"); xmlrequest.open("post", pageurl, false); xmlrequest.setrequestheader("content-type", "application/x-www-form-urlencoded"); xmlrequest.send(null); return xmlrequest; } function HandleCallBack() { var xmlrequest = DoCallback("WebForm.aspx"); var xmlobj = xmlrequest.responsexml; <Process return message xmlobj > settimeout("handlecallback()", 20000); } Here is the VB.NET programming code for returning a stored message in application variable, RetMessage, when the above client script calls the server file: If Not (Request.QueryString("callback") = "") Then Response.ContentType = "text/xml" Message = Application("RetMessage") Response.Write(Message) Response.Flush() Response.End() End If GE Fanuc Automation SDK Guidelines Page 13 of 22

7.0 Proficy ActiveX Controls Proficy ActiveX controls can become available to any Microsoft Visual Studio project by adding the COM Components to the toolbox. Following is an example of adding a Proficy AutoLog ActiveX control: 7.1 AutoLog After adding Proficy_ALC.AutoLog control to the toolbox, drag-and-drop the control to the form, using the following VB codes to configure the AutoLog sheet: 1. Connect to the server by using the Startup function. AxAutoLog1.Startup(servername, username, password) 2. Set the SheetName. The autolog sheet has to be created in Plant Application ahead of time, and put the exact sheet name inside the bracket below. AxAutoLog1.set_SheetName(AutologSheetName) To disconnect or shutdown the AutoLog control, use the following code: GE Fanuc Automation SDK Guidelines Page 14 of 22

AxAutoLog1.Shutdown 7.1.01 ExecuteCommand The ExecuteCommand function allows the user to control the behavior of the ActiveX control. It accepts the following commands: Command Parameters Notes Print FindTimeDialog FindEventDialog GotoLastRunDialog ViewCalculation ViewCellInformation ViewProductChange AddTrend SPCTrend ViewDisplayOptions ViewHeaderOptions InsertColumn DeleteColumn AlignColumn EditEvent EventDefects IndividualData ShowHelp ViewTestHistory ViewArrayData PrintLabel ThumbChart ViewEventDetails ViewStatisticalAnalysis ViewTimeLine ExceptionAnalysis ViewTestComment ViewVariableComment ViewProductComment ViewSpecComment ViewEventComment Signoff Approve AddComment The following is an example of how to call the ExecuteCommand function: If AxAutoLog1.ExecuteCommand("ViewArrayData", Nothing) = False Then MsgBox(AxAutoLog1.LastError) End If GE Fanuc Automation SDK Guidelines Page 15 of 22

7.1.01.1 FindEventDialog This ExecuteCommand is used to call the search event pop-up box that functions the same as in an Autolog display. Once the event is selected, the autolog control will go to the selected event. If user would like the autolog control scroll to a specific event without the use of the pop-up box command, ScrollTo function is used. Please refer to Section 7.1.02. Following is an example of how to call the search event pop-up box: AxAutoLog1.ExecuteCommand("FindEventDialog", Nothing) 7.1.02 ScrollTo This function is used to scroll to a specific event or batch in an autolog display without the use of a pop-up search box. There are two input parameters for this function, and they are TargetTime in date format and ExactTime in boolean. Function ScrollTo(ByRef TargetTime As Date, ByVal ExactTime As Boolean) As Boolean TargetTime is the event or batch timestamp. ExactTime is whether the event or batch has to match exactly to the timestamp that specified at TargetTime, while True as being to match exactly, and False as being to find the closest greater than the time that specified. Following is an example of how to call the ScrollTo function: AxAutoLog1.ScrollTo(#11/16/2006 10:00:00 PM#, False) Timestamp of 11/16/2006 10:00:00PM is passed as an input parameter in above example, and when using this function in the code, TargetTime can be a date variable that passed from other object. 7.1.03 Time Format In order for a time column to be display it is necessary to specify the time format that will show the data, otherwise the format is set by default to 0 and no data will be shown. The following is an example on how to set the time format. Waste1.DateTimeFormat(1) = "HH:MM:SS" 7.2 TrendSheet Here are the VB codes to set up a TrendSheet ActiveX Control: 1. Add Proficy_TRD.Trendsheet control to the toolbox, drag-and-drop the control to the form. GE Fanuc Automation SDK Guidelines Page 16 of 22

2. Connect to the server by using the Startup function. AxTrendSheet1.Startup(servername, username, password) 3. Set the SheetName. The trend sheet has to be created in Plant Application ahead of time. AxTrendSheet1.SheetName = TrendSheetName To disconnect or shutdown the Trendsheet control, use the following code: AxTrendSheet1.Shutdown 7.3 Schedule View Here are the VB codes to set up a Schedule View ActiveX Control: 1. Add Proficy_SVW.ScheduleView control to the toolbox, drag-and-drop the control to the form. GE Fanuc Automation SDK Guidelines Page 17 of 22

3. Connect to the server by using the Startup function. AxScheduleView1.Startup(servername, username, password) 4. Set the SheetName. The schedule view has to be created in Plant Application ahead of time, and put the exact sheet name inside the bracket below. AxScheduleView1.set_SheetName(ScheduleViewName) To disconnect or shutdown the ScheduleView control, use the following code: AxScheduleView1.Shutdown The following is a subset of the functions exposed in the object: Function Type Description get_currentppid Integer Returns the PP_Id of the currently selected row in the control. This can be used to tie additional functions around the schedule view object. ExecuteCommand Controls behaviour of the ActiveX control. GE Fanuc Automation SDK Guidelines Page 18 of 22

7.3.01 ExecuteCommand The ExecuteCommand function allows the user to control the behavior of the ActiveX control. It accepts the following commands: Command Parameters Notes Print ProductionScheduleView ProcessOrderDetailView ProcessOrderAdd ProcessOrderEdit ProcessOrderColumnVisibilityDialog FindTimeDialog FindSpecificProcessOrder ReLoadProductionSchedule ProcessOrderViewComments ProcessOrderViewHistory ProductionScheduleEditRunTimes ProcessOrderViewChildren ProcessOrderViewParent ProcessOrderCreateChild ProcessOrderMoveFwd ProcessOrderMoveBack ProductionScheduleUnitControl ProcessOrderReWork ProcessOrderReturnToParent ViewTimeline ProcessOrderDetail DockToProcessOrderSummaryView SequenceAdd SequenceEdit SequenceColumnVisibilityDialog SequenceViewComments SequenceViewHistory SequenceMoveFwd SequenceMoveBack PatternAdd PatternEdit PatternColumnVisibilityDialog PatternViewComments PatternViewHistory PatternMoveFwd PatternMoveBack Acknowledge EditProperty DisplayHyperLinksCommand BillOfMaterialsDetails The following is an example of how to call the ExecuteCommand function: If AxScheduleView1.ExecuteCommand("ProductionScheduleView", Nothing) = False Then GE Fanuc Automation SDK Guidelines Page 19 of 22

MsgBox(AxScheduleView1.LastError) End If GE Fanuc Automation SDK Guidelines Page 20 of 22

8.0 References Beginning ASP.NET 1.0 with Visual Basic.NET, Wrox Publishing Inc., 2003, Page 15, 22 GE Fanuc Automation SDK Guidelines Page 21 of 22

9.0 Revision History Date Version Action By Action 2006-09-05 0.1 Donna Lui Created 2007-01-27 0.2 Donna Lui Added Troubleshooting, Multiple Record Sets, and Subscribe in.net Sections 2007-03-08 0.3 Donna Lui Added Active X Control Section 2007-03-22 1.0 Donna Lui Added SDK.NET section and update Active X Control 2007-05-24 1.1 Donna Lui Added Active X Control Schedule View 2007-06-06 1.2 Matthew Wells Added Schedule View functions 2008-04-30 1.4 Donna Lui Added ScrollTo function for Autolog OCX GE Fanuc Automation SDK Guidelines Page 22 of 22