Campbell Scientific LoggerNet Server SDK User Manual

Download

LoggerNet Server

Software Development Kit

Version 4.1

Programmer’s Reference

Revision: 12/11

Campbell Scientific, Inc.

ll rights reserved; no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form o by any means, electronics, mechanical, photocopying, recording, or otherwise without either the prior written permission o the Publisher. This book may not be lent, resold, hired out or otherwise disposed of by way of trade in any form of binding o cover other than that in which it is published, without the prior written consent of the Publisher. The programs in this manual have been included for their instructional value. The Publisher does not offer any warranties or representations in respect o their fitness for a particular purpose, nor does the Publisher accept any liability for any loss or damage arising from their use.

Campbell Scientific, Inc. Software SDK End User License Agreement (EULA)

NOTICE OF AGREEMENT: Please carefully read this EULA. By installing or using this software, you are agreeing to comply with the terms and conditions herein. If you do not want to be bound by this EULA, you must promptly return the software, any copies, and accompanying documentation in its original packaging to Campbell Scientific or its representative.

By accepting this agreement you acknowledge and agree that Campbell Scientific may from time-to-time, and without notice, make changes to one or more components of the LoggerNet Server SDK or make changes to one or more components of other software on which the LoggerNet Server SDK relies. In no instance will Campbell Scientific be responsible for any costs or liabilities incurred by you or other third parties as a result of these changes.

This LoggerNet Server Software Development Kit software is hereinafter referred to as the LoggerNet Server SDK. The term "developer" herein refers to anyone using this LoggerNet Server SDK.

LICENSE FOR USE: Campbell Scientific grants you a non-exclusive, nontransferable, royalty-free license to use this software in accordance with the following:

1) The purchase of this software allows you to install and use the software on

one computer only.

2) This software cannot be loaded on a network server for the purposes of

distribution or for access to the software by multiple operators. If the software can be used from any computer other than the computer on which it is installed, you must license a copy of the software for each additional computer from which the software may be accessed.

3) If this copy of the software is an upgrade from a previous version, you

must possess a valid license for the earlier version of software. You may continue to use the earlier copy of software only if the upgrade copy and earlier version are installed and used on the same computer. The earlier version of software may not be installed and used on a separate computer or transferred to another party.

4) This software package is licensed as a single product. Its component parts

may not be separated for use on more than one computer.

5) You may make one (1) backup copy of this software onto media similar to

the original distribution, to protect your investment in the software in case of damage or loss. This backup copy can be used only to replace an unusable copy of the original installation media.

6) You may not use Campbell Scientific’s name, trademarks, or service

marks in connection with any program you develop with the LoggerNet Server SDK. You may not state or infer in any way that Campbell Scientific endorses any program you develop, unless prior written approval is received from Campbell Scientific.

7) If the software program you develop requires you, your customer, or a

third party to use additional licensable software from Campbell Scientific, that software must be purchased from Campbell Scientific or its representative under the terms of its separate EULA.

8) This license allows you to redistribute the ActiveX (dll) controls and the

communication DLL with the software developed using the LoggerNet Server SDK. No other Campbell Scientific examples, documentation, or source code may be distributed with your application.

9) The LoggerNet Server SDK may not be used to develop and publicly sell

or distribute any product that directly competes with Campbell Scientific’s datalogger support software.

10) This Agreement does not give Developer the right to sell or distribute any

other Campbell Scientific, Inc. Software (e.g., PC200W, VisualWeather, LoggerNet or any of their components, files, documentation, etc.) as part of Developer's application. Distribution of any other Campbell Scientific, Inc. software requires a separate distribution agreement.

The ActiveX® controls provided with this LoggerNet Server SDK ("LoggerNet Server SDK Controls") include the files: CsiBrokerMap.dll, CsiCoraScript.dll, CsiDatalogger.dll, CsiDataSource.dll, CsiLogMonitor.dll and CsiServer.dll. In addition, the LoggerNet server DLL, CORALIB3.DLL, is included with the LoggerNet Server SDK.

RELATIONSHIP: Campbell Scientific, Inc. hereby grants a license to use LoggerNet Server SDK Controls in accordance with the license statement above. No ownership in Campbell Scientific, Inc. patents, copyrights, trade secrets, trademarks, or trade names is transferred by this Agreement. Developer may use these LoggerNet Server SDK controls to create as many applications as desired and freely distribute those applications. Campbell Scientific, Inc. expects no royalties or any other compensation outside of the LoggerNet Server SDK purchase price. Developer is responsible for supporting applications created using the LoggerNet Server SDK Controls.

RESPONSIBILITIES OF DEVELOPER

The Developer agrees:

• To provide a competent programmer familiar with Campbell Scientific,

Inc. datalogger programming and software to write the applications.

• Not to sell or distribute documentation on use of LoggerNet Server SDK

Controls.

• Not to sell or distribute the applications that are provided as examples in

the LoggerNet Server SDK.

• To develop original works. Developers may copy and paste portions of the

code into their own applications, but their applications are expected to be unique creations.

• Not to sell or distribute applications that compete directly with any

application developed by Campbell Scientific, Inc. or its affiliates.

• To assure that each application developed with LoggerNet Server SDK

Controls clearly states the name of the person or entity that developed the

application. This information should appear on the first window the user will see.

WARRANTIES: The following warranties are in effect for ninety (90) days from the date of shipment of the original purchase. These warranties are not extended by the installation of upgrades or patches offered free of charge:

Campbell Scientific warrants that the installation media on which the software is recorded and the documentation provided with it are free from physical defects in materials and workmanship under normal use. The warranty does not cover any installation media that has been damaged, lost, or abused. You are urged to make a backup copy (as set forth above) to protect your investment. Damaged or lost media is the sole responsibility of the licensee and will not be replaced by Campbell Scientific.

Campbell Scientific warrants that the software itself will perform substantially in accordance with the specifications set forth in the instruction manual when properly installed and used in a manner consistent with the published recommendations, including recommended system requirements. Campbell Scientific does not warrant that the software will meet licensee’s requirements for use, or that the software or documentation are error free, or that the operation of the software will be uninterrupted.

Campbell Scientific will either replace or correct any software that does not perform substantially according to the specifications set forth in the instruction manual with a corrected copy of the software or corrective code. In the case of significant error in the installation media or documentation, Campbell Scientific will correct errors without charge by providing new media, addenda, or substitute pages. If Campbell Scientific is unable to replace defective media or documentation, or if it is unable to provide corrected software or corrected documentation within a reasonable time, it will either replace the software with a functionally similar program or refund the purchase price paid for the software.

All warranties of merchantability and fitness for a particular purpose are disclaimed and excluded. Campbell Scientific shall not in any case be liable for special, incidental, consequential, indirect, or other similar damages even if Campbell Scientific has been advised of the possibility of such damages. Campbell Scientific is not responsible for any costs incurred as a result of lost profits or revenue, loss of use of the software, loss of data, cost of re-creating lost data, the cost of any substitute program, telecommunication access costs, claims by any party other than licensee, or for other similar costs.

This warranty does not cover any software that has been altered or changed in any way by anyone other than Campbell Scientific. Campbell Scientific is not responsible for problems caused by computer hardware, computer operating systems, or the use of Campbell Scientific’s software with non-Campbell Scientific software.

Licensee’s sole and exclusive remedy is set forth in this limited warranty. Campbell Scientific’s aggregate liability arising from or relating to this agreement or the software or documentation (regardless of the form of action; e.g., contract, tort, computer malpractice, fraud and/or otherwise) is limited to the purchase price paid by the licensee.

There is no written or implied warranty provided with the LoggerNet Server SDK software other than as stated herein. Developer agrees to bear all warranty responsibility of any derivative products distributed by Developer.

TERMINATION: Any license violation or breach of Agreement will result in immediate termination of the developer's rights herein and the return of all LoggerNet Server SDK materials to Campbell Scientific, Inc.

MISCELLANEOUS: Notices required hereunder shall be in writing and shall be given by certified or registered mail, return receipt requested. Such notice shall be deemed given in the case of certified or registered mail on the date of receipt. This Agreement shall be governed and construed in accordance with the laws of the State of Utah, USA. Any dispute resulting from this Agreement will be settled in arbitration.

This Agreement sets forth the entire understanding of the parties and supersedes all prior agreements, arrangements and communications, whether oral or written pertaining to the subject matter hereof. This agreement shall not be modified or amended except by the mutual written agreement of the parties. The failure of either party to enforce any of the provisions of this Agreement shall not be construed as a waiver of such provisions or of the right of such party thereafter to enforce each and every provision contained herein. If any term, clause, or provision contained in this Agreement is declared or held invalid by a court of competent jurisdiction, such declaration or holding shall not affect the validity of any other term, clause, or provision herein contained. Neither the rights nor the obligations arising under this Agreement are assignable or transferable.

If within 30 days of receiving the LoggerNet Server SDK product developer does not agree to the terms of license, developer shall return all materials without retaining any copies of the product and shall remove any use of the LoggerNet Server SDK Controls in any applications developed or distributed by Developer. CSI shall refund 1/2 of the purchase price within 30 days of receipt of the materials. In the absence of such return, CSI shall consider developer in agreement with the herein stated license terms and conditions.

COPYRIGHT: This software is protected by United States copyright law and international copyright treaty provisions. This software may not be altered in any way without prior written permission from Campbell Scientific. All copyright notices and labeling must be left intact.

LoggerNet Server Software Development Kit Table of Contents

PDF viewers note: These page numbers refer to the printed version of this document. Use the Adobe Acrobat® bookmarks tab for links to specific sections.

1. LoggerNet Server SDK Overview ............................1-1

1.1 Purpose of the LoggerNet Server SDK................................................. 1-1

1.2 Requirements ........................................................................................ 1-1

1.2.1 Required Campbell Scientific, Inc. Software.............................. 1-1

1.2.2 Development Tools Requirements.............................................. 1-1

1.3 Included Components ........................................................................... 1-2

1.3.1 Files Included in the LoggerNet Server SDK ............................. 1-2

1.3.1.1 ActiveX® Controls (DLLs)............................................... 1-2

1.3.1.2 LoggerNet Server (CORALIB3.DLL)............................... 1-2

1.3.1.3 Manuals ............................................................................. 1-2

1.3.1.4 Example Projects............................................................... 1-2

1.3.2 Adding Controls to a Project....................................................... 1-2

1.3.2.1 Adding a Control to a Visual Basic Project....................... 1-3

1.3.2.2 Adding a Control to a Delphi Project ................................ 1-3

1.3.2.3 Adding a Control to a .NET Project .................................. 1-4

2. CsiServer Control .....................................................2-1

2.1 Purpose of the CsiServer Control ......................................................... 2-1

2.2 CsiServer Interface ............................................................................... 2-1

2.2.1 Properties .................................................................................... 2-2

2.2.2 Methods....................................................................................... 2-2

2.2.3 Events.......................................................................................... 2-2

3. Developing an Application Using the CsiServer

Control....................................................................3-1

3.1 Purpose ................................................................................................. 3-1

3.2 Using the CsiServer Control................................................................. 3-1

3.2.1 Getting Started with the CsiServer Control................................. 3-1

3.2.2 CsiServer Control Application Example..................................... 3-2

4. CsiCoraScript Control ..............................................4-1

4.1 Purpose of the CsiCoraScript Control................................................... 4-1

4.2 Connecting to the Server....................................................................... 4-1

4.3 Using CoraScript Commands ............................................................... 4-1

4.3.1 Setting up a Network................................................................... 4-2

4.3.2 Real-Time Data Display.............................................................. 4-2

4.3.2.1 Table-Data Dataloggers..................................................... 4-3

4.3.2.2 Mixed-Array Dataloggers.................................................. 4-3

LoggerNet Software Development Kit Table of Contents

4.4 CsiCoraScript Interface......................................................................... 4-4

4.4.1 Properties..................................................................................... 4-4

4.4.2 Methods....................................................................................... 4-4

4.4.3 Events.......................................................................................... 4-4

5. Developing an Application Using the

CsiCoraScript Control .......................................... 5-1

5.1 Purpose.................................................................................................. 5-1

5.2 Using the CsiCoraScript Control...........................................................5-1

5.2.1 Getting Started with the CsiCoraScript Control ..........................5-1

5.2.2 CsiCoraScript Control Application Example .............................. 5-2

6. CsiBrokerMap Control............................................. 6-1

6.1 Purpose of the CsiBrokerMap Control.................................................. 6-1

6.2 Connecting to the LoggerNet Server..................................................... 6-1

6.3 How Collections Work.......................................................................... 6-2

6.3.1 Visual Basic View of Collections................................................6-2

6.3.1.1 Accessing Collections with For Each ................................6-2

6.3.1.2 Accessing Collections with Indexes and Names................6-2

6.3.2 Delphi/Visual C++ View of Collections ..................................... 6-2

6.4 CsiBrokerMap Interfaces ...................................................................... 6-3

6.4.1 BrokerMap Interface ................................................................... 6-3

6.4.1.1 Properties........................................................................... 6-3

6.4.1.2 Methods .............................................................................6-3

6.4.1.3 Events ................................................................................ 6-3

6.4.2 BrokerCollection Interface.......................................................... 6-3

6.4.2.1 Properties........................................................................... 6-3

6.4.2.2 Methods .............................................................................6-4

6.4.3 Broker Interface........................................................................... 6-4

6.4.3.1 Properties........................................................................... 6-4

6.4.3.2 Methods .............................................................................6-4

6.4.4 Table Collection Interface........................................................... 6-4

6.4.4.1 Properties........................................................................... 6-4

6.4.4.2 Methods .............................................................................6-4

6.4.5 Table Interface............................................................................. 6-4

6.4.5.1 Properties........................................................................... 6-4

6.4.5.2 Methods .............................................................................6-4

6.4.6 ColumnCollection Interface ........................................................6-5

6.4.6.1 Properties........................................................................... 6-5

6.4.6.2 Methods .............................................................................6-5

6.4.7 Column Interface......................................................................... 6-5

6.4.7.1 Properties........................................................................... 6-5

7. Developing an Application Using the

CsiBrokerMap Control.......................................... 7-1

7.1 Purpose.................................................................................................. 7-1

7.2 Using the CsiBrokerMap Control .........................................................7-1

7.2.1 Getting Started with the CsiBrokerMap Control......................... 7-1

7.2.2 CsiBrokerMap Control Application Example ............................. 7-2

LoggerNet Software Development Kit Table of Contents

8. CsiDatalogger ...........................................................8-1

8.1 Purpose of the CsiDatalogger Control.................................................. 8-1

8.2 Connecting to the Server....................................................................... 8-1

8.3 Datalogger Interface ............................................................................. 8-1

8.3.1 Properties .................................................................................... 8-1

8.3.2 Methods....................................................................................... 8-2

8.3.3 Events.......................................................................................... 8-2

9. Developing an Application Using the

Datalogger Control ................................................9-1

9.1 Purpose ................................................................................................. 9-1

9.2 Using the CsiDatalogger Control.......................................................... 9-1

9.2.1 Getting Started with the CsiDatalogger Control ......................... 9-1

9.2.2 CsiDatalogger Control Application Example.............................. 9-2

10. CsiDataSource Control ........................................10-1

10.1 Purpose of the CsiDataSource Control ............................................. 10-1

10.2 Connecting to the Server................................................................... 10-1

10.3 CsiDataSource Interfaces.................................................................. 10-2

10.3.1 Dsource Interface .................................................................... 10-2

10.3.1.1 Properties....................................................................... 10-2

10.3.1.2 Methods......................................................................... 10-2

10.3.1.3 Events ............................................................................ 10-2

10.3.2 Advisor Interface..................................................................... 10-2

10.3.2.1 Properties....................................................................... 10-3

10.3.2.2 Methods......................................................................... 10-3

10.3.3 DataColumnCollection Interface............................................. 10-3

10.3.3.1 Properties....................................................................... 10-3

10.3.3.2 Methods......................................................................... 10-3

10.3.4 DataColumn Interface ............................................................. 10-3

10.3.4.1 Properties....................................................................... 10-3

10.3.5 Record..................................................................................... 10-4

10.3.5.1 Properties....................................................................... 10-4

10.3.5.2 Methods......................................................................... 10-4

10.3.6 RecordCollection .................................................................... 10-4

10.3.6.1 Properties....................................................................... 10-4

10.3.6.2 Methods.......................................................................... 10-4

10.3.7 Value Interface........................................................................ 10-4

10.3.7.1 Properties....................................................................... 10-4

11. Developing an Application Using the

CsiDataSource Control.....................................11-1

11.1 Purpose ............................................................................................. 11-1

11.2 Using the CsiDataSource Control..................................................... 11-1

11.2.1 Getting Started with the CsiDataSource Control..................... 11-1

11.2.2 CsiDataSource Control Application Example......................... 11-2

iii

LoggerNet Software Development Kit Table of Contents

12. CsiLogMonitor Control........................................ 12-1

12.1 Purpose of the CsiLogMonitor Control............................................. 12-1

12.2 CsiLogMonitor Interface................................................................... 12-2

12.2.1 Properties................................................................................. 12-2

12.2.2 Methods................................................................................... 12-2

12.2.3 Events...................................................................................... 12-2

13. Developing an Application Using the

CsiLogMonitor Control .................................... 13-1

13.1 Purpose.............................................................................................. 13-1

13.2 Using the CsiLogMonitor Control .................................................... 13-1

13.2.1 Getting Started with the CsiLogMonitor Control.................... 13-1

13.2.2 CsiLogMonitor Control Application Example ......................... 13-2

14. CsiServer Control Reference .............................. 14-1

14.1 Server Interface................................................................................. 14-1

14.1.1 Properties................................................................................. 14-1

14.1.2 Methods................................................................................... 14-4

14.1.3 Events...................................................................................... 14-5

15. CsiCoraScript Control Reference....................... 15-1

15.1 CoraScript Interface .......................................................................... 15-1

15.1.1 Properties................................................................................. 15-1

15.1.2 Methods................................................................................... 15-3

15.1.3 Events...................................................................................... 15-4

16. CsiBrokerMap Control Reference ...................... 16-1

16.1 BrokerMap Interface......................................................................... 16-1

16.1.1 Properties................................................................................. 16-1

16.1.2 Methods................................................................................... 16-4

16.1.3 Events...................................................................................... 16-5

16.2 BrokerCollection Interface................................................................ 16-7

16.2.1 Properties................................................................................. 16-7

16.2.2 Methods................................................................................... 16-8

16.3 Broker Interface ................................................................................16-9

16.3.1 Properties................................................................................. 16-9

16.3.2 Methods................................................................................. 16-11

16.4 TableCollection Interface................................................................ 16-12

16.4.1 Properties............................................................................... 16-12

16.4.2 Methods................................................................................. 16-12

16.5 Table Interface ................................................................................ 16-14

16.5.1 Properties............................................................................... 16-14

16.5.2 Methods................................................................................. 16-15

16.6 ColumnCollection Interface............................................................ 16-16

16.6.1 Properties............................................................................... 16-16

16.6.2 Methods................................................................................. 16-16

16.7 Column Interface............................................................................. 16-18

16.7.1 Properties............................................................................... 16-18

LoggerNet Software Development Kit Table of Contents

17. CsiDatalogger Control Reference .......................17-1

17.1 Datalogger Interface ......................................................................... 17-1

17.1.1 Properties ................................................................................ 17-1

17.1.2 Methods................................................................................... 17-6

17.1.3 Events.................................................................................... 17-13

18. CsiDataSource Control Reference ......................18-1

18.1 DSource Interface ............................................................................. 18-1

18.1.1 Properties ................................................................................ 18-1

18.1.2 Methods................................................................................... 18-4

18.1.3 Events...................................................................................... 18-5

18.2 Advisor Interface ............................................................................ 18-11

18.2.1 Properties .............................................................................. 18-11

18.2.2 Methods................................................................................. 18-19

18.3 DataColumnCollection Interface .................................................... 18-22

18.3.1 Properties .............................................................................. 18-22

18.3.2 Methods................................................................................. 18-22

18.4 DataColumn Interface..................................................................... 18-25

18.4.1 Properties .............................................................................. 18-25

18.5 Record Interface.............................................................................. 18-25

18.5.1 Properties .............................................................................. 18-25

18.5.2 Methods................................................................................. 18-27

18.6 RecordCollection ............................................................................ 18-29

18.6.1 Properties .............................................................................. 18-29

18.6.2 Methods................................................................................. 18-29

18.7 Value Interface................................................................................ 18-30

18.7.1 Properties .............................................................................. 18-30

19. CsiLogMonitor Control Reference ......................19-1

19.1 LogMonitor Interface........................................................................ 19-1

19.1.1 Properties ................................................................................ 19-1

19.1.2 Methods................................................................................... 19-5

19.1.3 Events...................................................................................... 19-8

Appendix

A. Server and Device Operational Statistics Tables. A-1

A.1 Device History Statistics..................................................................... A-1

A.1.1 Attempts.................................................................................... A-1

A.1.2 Failures...................................................................................... A-1

A.1.3 Retries ....................................................................................... A-1

A.2 Device Standard Statistics................................................................... A-2

A.2.1 Communication Enabled........................................................... A-2

A.2.2 Average Error Rate.................................................................... A-2

A.2.3 Total Retries.............................................................................. A-2

A.2.4 Total Failures ............................................................................ A-2

A.2.5 Total Attempts........................................................................... A-2

A.2.6 Communication Status .............................................................. A-3

A.2.7 Last Clock Check ...................................................................... A-3

A.2.8 Last Clock Set ........................................................................... A-3

A.2.9 Last Clock Difference ............................................................... A-3

LoggerNet Software Development Kit Table of Contents

A.2.10 Collection Enabled .................................................................. A-4

A.2.11 Last Data Collection................................................................ A-4

A.2.12 Next Data Collection ............................................................... A-4

A.2.13 Last Collect Attempt................................................................ A-4

A.2.14 Collection State ....................................................................... A-4

A.2.15 Values in Last Collection ........................................................A-5

A.2.16 Values to Collect ..................................................................... A-5

A.2.17 Values in Holes........................................................................ A-5

A.2.18 Values in Uncollectable Holes ................................................ A-6

A.2.19 Line State................................................................................. A-6

A.2.20 Polling Active.......................................................................... A-7

A.2.21 FS1 to Collect.......................................................................... A-7

A.2.22 FS1 Collected ........................................................................... A-7

A.2.23 FS2 to Collect.......................................................................... A-7

A.2.24 FS2 Collected .......................................................................... A-7

A.2.25 Logger Ver ..............................................................................A-7

A.2.26 Watchdog Err........................................................................... A-8

A.2.27 Prog Overrun ........................................................................... A-8

A.2.28 Mem Code ............................................................................... A-8

A.2.29 Collect Retries ......................................................................... A-8

A.2.30 Low Voltage Stopped Count ................................................... A-8

A.2.31 Low Five Volts Error Count.................................................... A-9

A.2.32 Lithium Battery Voltage.......................................................... A-9

A.2.33 Table Definitions State............................................................ A-9

A.3 Server Statistics................................................................................... A-9

A.3.1 Disc Space Available............................................................... A-10

A.3.2 Available Virtual Memory....................................................... A-10

A.3.3 Used Virtual Memory.............................................................. A-10

Figures

Tables

3-1 CsiServer Example ...............................................................................3-2

5-1 CsiCoraScript Example.........................................................................5-2

7-1 CsiBrokerMap Example .......................................................................7-2

9-1 CsiDatalogger Example........................................................................ 9-2

11-1 CsiDataSource Example ................................................................... 11-2

13-1 CsiLogMonitor Example .................................................................. 13-2

1-1. Supported Development Tools ............................................................ 1-1

Section 1. LoggerNet Server SDK Overview

1.1 Purpose of the LoggerNet Server SDK

The LoggerNet Server Software Development Kit (SDK) provides a method to communicate with a datalogger network through ActiveX controls provide an abstraction to the server messaging and datalogger communication protocols. Together these controls encapsulate all of the messaging between client applications and the LoggerNet server whether the client resides on a local machine or accesses the LoggerNet server over a network.

Without these controls, creating custom client applications that communicate with Campbell Scientific dataloggers would require an implementation of all the protocol details when sending messages to dataloggers and reading messages from dataloggers. By using the SDK, developers not only reduce development time but also insulate their application from future changes with datalogger communication protocols.

1.2 Requirements

1.2.1 Required Campbell Scientific, Inc. Software

SDK communication requires access to a functioning LoggerNet server. Client applications use the SDK controls to create connections with dataloggers through the LoggerNet server DLL. This version of the SDK still allows the creation of custom software applications that can communicate to an existing installation of LoggerNet. Alternately, custom software can be created that starts, stops, and communicates through the included LoggerNet server DLL (CORALIB3.DLL). The SDK controls communicate with CSI dataloggers using LoggerNet server version 1.1 or higher.

controls. These

1.2.2 Development Tools Requirements

The SDK's ActiveX® controls have been tested with the following development tools for Microsoft Windows:

TABLE 1-1. Supported Development Tools

Development Tool Examples Available

Visual Basic 6.0 Yes

Delphi 2007 Yes

Visual C++ VS-2010 MFC Yes

C#.NET Yes

VB.NET Yes

1-1

Section 1. LoggerNet Server SDK Overview

NOTE

The C#.NET and VB.NET example code targets the x86 compilation platform to facilitate proper functionality on 64-bit versions of Windows platforms should use this compiler directive, since the ActiveX controls in the SDK must run in a 32-bit process on 64-bit machines to work properly.

1.3 Included Components

1.3.1 Files Included in the LoggerNet Server SDK

The files included with the LoggerNet Server SDK installation are: ActiveX ® SDK controls, the LoggerNet server DLL, working examples for several development controls, licensing information, and the SDK Beginner’s Guide and Programmer’s Reference. Please note that although simple examples are provide for reference, the SDK does not contain a complete user interface software package for creating connections and manipulating data within datalogger networks. The SDK merely provides all the controls necessary for development of the user interface software.

1.3.1.1 ActiveX® Controls (DLLs)

The six included ActiveX controls are DLL files that are registered and must be added to your project. For help adding these controls to your project, see the next section "Adding the Controls to a Project".

. Any new projects created on 64-bit

1.3.1.2 LoggerNet Server (CORALIB3.DLL)

The LoggerNet server DLL available in the installed Controls folder can be started, stopped, and accessed with the included ActiveX Controls. This DLL does not need to be registered but must be placed in the application folder, in the PATH environmental variable, or in the Windows system directory.

1.3.1.3 Manuals

The SDK Beginner’s Guide contains information comparing available Campbell Scientific SDK products. The LoggerNet Server SDK Programmer’s Reference contains detailed information regarding the use of the LoggerNet Server SDK. Both manuals are in PDF format.

1.3.1.4 Example Projects

Example projects are included with the SDK. These projects collectively use all of the controls to demonstrate simple functionality. The example projects have been written in various development environments.

1.3.2 Adding Controls to a Project

This section describes how to add controls to a project in Visual Basic 6.0, Delphi, or .NET. Before trying to add any of the SDK controls to your development project, make sure that the installation program has installed all of

1-2

Section 1. LoggerNet Server SDK Overview

the controls. The standard installation program will register the SDK control DLLs.

1.3.2.1 Adding a Control to a Visual Basic Project

1. Start Visual Basic.

2. Create a new project (

your choice. "Standard EXE" would be a good choice.

3. Add "Components" to your project (

Check the controls that you would like to add to the project and click "OK".

4. Select a control on the toolbar by clicking it and draw the control onto the

form by clicking and dragging (creating a rectangle or square).

File -> New Project ) and select the project of

1.3.2.2 Adding a Control to a Delphi Project

1. Start Delphi.

2. Delphi

3. Select a SDK component (e.g., CsiBrokerMap 1.0 Type Library (Version

4. Select the tab Into New Package in the Install window and click on the

Main menu -> Component -> Import ActiveX Control…

1.0)) from the Import Active X window and click on the Install button.

Browse button. Locate the directory where you would like this new package to reside and assign a name to this new package, e.g., CsiBrokerMap. Click on OK button.

Project -> Components...).

1-3

Section 1. LoggerNet Server SDK Overview

5. A confirmation message similar to one below will appear. Click on Yes.

6. A new window titled Information (not shown) will appear informing you

that the package has been installed.

7. Finally you will be asked to save the changes. Click on Yes.

8. Follow the same procedure to obtain the other two ActiveX controls as

icons on the ActiveX palette in Delphi.

1.3.2.3 Adding a Control to a .NET Project

ActiveX controls are imported using the COM Interop wrapper capability in the .NET development environment. This importing should happen automatically when the ActiveX DLL is referenced in the project.

1. From the Project menu item choose "Add Reference".

2. Find and select the SDK component to import (e.g. CsiBrokerMap 1.0

Type Library) under the COM tab.

3. Add the component to the project form.

1-4

Section 2. CsiServer Control

2.1 Purpose of the CsiServer Control

The CsiServer Control allows the user to start and stop the included, LoggerNet server DLL (CORALIB3.DLL). All SDK controls must connect to and use a LoggerNet server to communicate with Campbell Scientific dataloggers. Therefore, a LoggerNet server must be running on the network before the included examples or any custom SDK software will function.

Campbell Scientific sells a complete LoggerNet software package that includes the LoggerNet server and many complex software clients. This version of LoggerNet may already be installed and in use on the network where the custom SDK application will reside. If the LoggerNet software is already installed and running on the network, it is not necessary to use the CsiServer control to start another LoggerNet server. However, if a separate version of LoggerNet has not been started or installed on the network, use the CsiServer control to start the included CORALIB3.DLL. The included CORALIB3.DLL must be located in the same folder as the created application, the PATH environmental variable, or in the Windows system directory before it can be started.

All of the configuration information and data for the datalogger network will be stored in the LoggerNet working directory described in the CsiServer control properties. Only one LoggerNet server at a time can use the network configuration information contained in the working directory. If a previous installation of LoggerNet created the network map and configuration information, the LoggerNet server included in the SDK can point to and use this configuration information. However, avoid file conflict issues by making sure only one LoggerNet server accesses the same working directory at a time.

Careful consideration should be given before beginning a project using the SDK. Consider the type of software application needed. Many developers merely want to create custom software interfaces that extend a previous installation of LoggerNet. The CsiServer control won’t be needed for this type of application. However, if you are interested in creating a complete software solution that will replace or be used instead of Campbell Scientific’s LoggerNet software package, make sure a LoggerNet server is not running and then start the included LoggerNet server DLL with the CsiServer control. Moreover, an understanding of CoraScript commands, which are discussed in the next section, is required to set up and manipulate the datalogger network.

2.2 CsiServer Interface

See the Reference section in this manual for detailed descriptions of these properties, methods, and events.

2-1

Section 2. CsiServer Control

2.2.1 Properties

2.2.2 Methods

2.2.3 Events

• applicationWorkDir As String

• buildDate As String (read-only)

• logFileDir As String

• serverStarted As Boolean (read-only)

• serverVersion As String (read-only)

• serverWorkDir As String (Required)

• tcpPort As Integer

• tcpPortEx As Long

• startServer()

• stopServer()

• onServerFailure(String Reason)

2-2

Section 3. Developing an Application Using the CsiServer Control

3.1 Purpose

This section shows by example how to build an application using the SDK CsiServer control. The application’s functions are:

1. Start the LoggerNet server (CORALIB3.DLL).

2. Stop the LoggerNet server (CORALIB3.DLL).

3.2 Using the CsiServer Control

3.2.1 Getting Started with the CsiServer Control

The CsiServer SDK control (an ActiveX object) starts and stops the LoggerNet server (CORALIB3.DLL).

This example assumes that:

• you have registered the CsiServer control correctly

• you will develop the application with Visual Basic 6.0

• the CORALIB3.DLL exists in the folder with the created application, the

PATH environmental variable, or the Windows system directory

• both the CORALIB3.DLL and application you are developing reside on

the same computer

Complete the following steps first:

1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |

Microsoft Visual Basic 6)

2. Start a new project (File | New Project | Standard EXE | OK) opening a

new, blank form.

3. View the toolbox for this new project (VB 6 Main Menu | View |

Toolbox).

4. Right click on the toolbox area and select Components. A component

window will open and the following SDK controls will appear within the list if they are registered properly:

CsiBrokerMap 1.0 Type Library CsiCoraScript 1.0 Type Library CsiDatalogger 1.0 Type Library CsiDataSource 1.0 Type Library

3-1

Section 3. Developing an Application Using the CsiServer Control

CsiLogMonitor 1.0 Type Library CsiServer 1.0 Type Library

Check the box next to the CsiServer 1.0 Type Library, click Apply, and then close the window. Now an icon for the CsiServer control and other common controls will appear in the toolbox.

3.2.2 CsiServer Control Application Example

Begin creating an application that will start and stop the LoggerNet server. An example of a user interface that accomplishes this task is shown in Figure 3-1. This interface includes the CsiServer control and other objects on the form to create a functional application that will start and stop the LoggerNet server.

FIGURE 3-1. CsiServer Example

Now that the interface has been designed, the code can be organized to accomplish the requirements of the application. Initially, the one required parameter, serverWorkDir, must be set and then the startServer() method can be called to start the LoggerNet server. A basic example of code used to start the LoggerNet server is listed in the table below:

Private Sub cmdStart_Click()

'Set the required properties for the LoggerNet Server CsiServer.serverWorkDir = "c:\campbellsci\loggernet\sys\bin"

'Start the LoggerNet Server If CsiServer.serverStarted Then txtServer.Text = "Server Already Started" Else CsiServer.startServer txtServer.Text = "Server Started" cmdStart.Enabled = False cmdStop.Enabled = True End If

End Sub

3-2

Section 3. Developing an Application Using the CsiServer Control

In order to stop the LoggerNet server, use the method stopServer(). A basic example of code used to stop the LoggerNet server is found in the following table:

Private Sub cmdStop_Click() 'Stop the LoggerNet Server If CsiServer.serverStarted Then CsiServer.stopServer txtServer.Text = "Server Stopped" cmdStop.Enabled = False cmdStart.Enabled = True Else txtServer.Text = "Server Already Stopped" End If End Sub

Add additional functionality and objects as necessary to meet the specific requirements of your application. Complete examples using the CsiServer control are included with the LoggerNet Server SDK installation.

3-3

Section 3. Developing an Application Using the CsiServer Control

3-4

Section 4. CsiCoraScript Control

4.1 Purpose of the CsiCoraScript Control

The CsiCoraScript control provides the power to administer the LoggerNet server. There are many different settings and commands available with this control.

Specific LoggerNet server functions and tasks are set by passing CoraScript commands to the LoggerNet server. CoraScript commands execute LoggerNet server operations that include adding devices to the network map, data collection, listing table and datalogger information, and changing settings in the LoggerNet server and attached devices. CoraScript commands and their purposes can be found in the Quick Reference help file installed with the LoggerNet Server SDK.

NOTE

The following CoraScript commands are currently unsupported in the SDK: connect, disconnect, help, exit, bye, quit, and listcommands.

4.2 Connecting to the Server

There are two basic actions required for this control to connect to the LoggerNet server:

1. Set server properties:

• serverName - The name or IP address of the LoggerNet server . The

default value is

• serverPort - The port on which the LoggerNet server is running. The

default value is 6789.

• serverLogonName (Optional) - If security has been enabled on the

server, a valid logon name is required.

• serverLogonPassword (Optional) - If security has been enabled on the

server, a valid password that corresponds with a valid logon name is required.

localhost.

2. Invoke the

serverConnect() method.

4.3 Using CoraScript Commands

CoraScript commands are used to setup and manipulate the LoggerNet server. A complete listing of these commands can be found in the LoggerNet Server SDK Quick Reference. A thorough knowledge of these powerful commands is recommended before attempting to make changes to settings or devices in the LoggerNet server. The following sections outline some basic commands that can be used to quickly set up devices and collect data from the network.

4-1

Section 4. CsiCoraScript Control

4.3.1 Setting up a Network

Some of the commands that can be used when initially setting up a datalogger network on the LoggerNet server include:

• add-device – used to add root ports, dataloggers, and telecommunication

devices to the network map.

• set-device-setting – used to change settings of specific devices in the

network map.

• delete-branch – used to remove a device and any children of a device from

the network map.

• list-devices – shows the devices in the network map

The following example shows the basic CoraScript commands used to set up a CR10X connected directly to the LoggerNet server via RS232:

add-device com-port COM1 as-child “”; add-device cr10x CR10X as-child “COM1”;

The following example shows basic CoraScript commands used to set up a CR9000 connected to the LoggerNet server via Ethernet:

add-device tcp-com-port IPPort as-child “”; set-device-setting IPPort 5 192.168.1.1:6781; add-device cr9000 CR9000 as-child “IPPort”;

4.3.2 Real-Time Data Display

Some developers want to display data values as quickly as they change in the datalogger. Each time a datalogger program executes, new values are written as input locations. Collecting these input locations provides a snapshot of the most recent values contained in the datalogger. The DataSource control of the SDK can be used to set up an advisor that will watch the LoggerNet data cache and display new or existing data values that are collected. CoraScript commands are used to set up the collect areas of LoggerNet and to enable scheduled collection of specific datalogger tables to automate the collection process.

Please note that although the commands below will enable collection of input locations from a datalogger, using input locations for real-time comparison of values can be problematic. When input locations are collected, the collection is merely a snapshot of the current values that exist in each location. If, for example, the datalogger program has not completely executed, some of the values collected may be new while other values may have not changed from the previous program execution. Please keep this information in mind if input locations are used in real-time data display or calculations. If correlating values are necessary, a better approach writes values to Final Storage every program execution and collects those values as quickly as possible.

4-2

4.3.2.1 Table-Data Dataloggers

The LoggerNet server, by default, creates a collect area for the Public or InLocs table of table-data dataloggers such as the CR9000 or CR10X-TD. The basic CoraScript commands that are used to enable collection and establish scheduled collection are:

set-collect-area-setting – used to enable a device for collection

•

set-device-setting – used to activate scheduled collection for a device

If you have added a CR9000 to the datalogger network and you have a program running on that device, the following command will enable the public table for collection by activating the collect-area-setting scheduleEnabled (id = 2):

set-collect-area-setting CR9000 public 2 1;

Every time a manual poll or any other collection occurs, data will be collected for the public table of the CR9000. If a DataSource advisor has been created, it will trigger and display the new values. If you want to automate the data collection process, set the device's scheduled collection interval through the device setting collectSched (id = 5):

Section 4. CsiCoraScript Control

set-device-setting CR9000 5 {1 19900101 300000 120000 3 86400000};

With the above setting, the LoggerNet server will automatically collect all tables enabled for collection from the CR9000 every 300000 milliseconds. Once this setting is in place, the activated DataSource advisor will display updates as they are automatically collected.

4.3.2.2 Mixed-Array Dataloggers

Although the DataSource control can create a temporary data cache to watch all input locations, mixed-array dataloggers, like the CR7 and CR10X, require additional commands to create a permanent collect area for input locations. Input Locations (InLocs) contain values that are usually stored every time the program executes. However, the LoggerNet server does not create a permanent data cache by default containing data from InLocs for a mixed-array datalogger. If a permanent collect area for InLocs is desired or only specific InLocs are needed, the collect area must be created manually in the LoggerNet server. The following commands are used to set up a permanent InLocs collect area for a mixed-array datalogger:

create-inlocs-area – create a collect area containing specified input

•

locations

set-collect-area-setting – used to enable a device for collection

•

set-device-setting – used to activate scheduled collection for a device

The following example sets up collection for two input locations of a CR10X by identifying the station, declaring a name for the collect area, and listing the input locations to include:

create-inlocs-area CR10X InLocsArea {1 "inlocs1"} {2 {inlocs2}};

4-3

Section 4. CsiCoraScript Control

Collect area names must always be unique. Therefore, if an attempt is made to create a collect area with exactly the same name as a collect area that already exists, the LoggerNet server will automatically index the name of the collect area being created. For example, if collect area InLocsArea already exists and an attempt is made to create another collect area with the same name, the LoggerNet server will automatically name the new collect area InLocsArea1.

To activate a collect area for collection and to automate the collection process use the following commands:

set-collect-area-setting CR10X InLocsArea 2 1; set-device-setting CR10X 5 {1 19900101 300000 120000 3 86400000};

With the above setting, the LoggerNet server will automatically collect all tables enabled for collection from the CR10X every 300000 milliseconds. Once this setting is in place, the activated DataSource advisor will display new data values as they are collected.

4.4 CsiCoraScript Interface

See the Reference section for descriptions of these properties, methods, and events.

4.4.1 Properties

4.4.2 Methods

4.4.3 Events

• serverConnected As Boolean (read-only)

• serverLogonName As String

• serverLogonPassword As String

• serverName As String

• serverPort As Long

• executeScript(String script, Long asyncID) As String

• serverConnect()

• serverDisconnect()

• onScriptComplete(Long asyncID, String result)

• onServerConnectStarted()

• onServerConnectFailure(server_failure_type server_failure)

4-4

Section 5. Developing an Application Using the CsiCoraScript Control

5.1 Purpose

This section shows an example of how to build an application using the CsiCoraScript control. The application’s functions are:

1. Connect to a running LoggerNet server

2. Execute CoraScript commands to administer the LoggerNet server.

5.2 Using the CsiCoraScript Control

5.2.1 Getting Started with the CsiCoraScript Control

The CsiCoraScript SDK control (an ActiveX object) administers the datalogger network by passing CoraScript commands to the LoggerNet server.

This example assumes that:

• you have registered the CsiCoraScript control correctly

• you are developing the application in Visual Basic 6.0

• a LoggerNet server is running and accessible on the network

Complete the following steps first:

1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |

Microsoft Visual Basic 6)

2. Start a new project (File | New Project | Standard EXE | OK) opening a

new, blank form.

3. View the toolbox for this new project (VB 6 Main Menu | View |

Toolbox).

4. Right click on the toolbox area and select Components. A component

window will open and the following SDK controls will appear within the list if they are registered properly:

CsiBrokerMap 1.0 Type Library CsiCoraScript 1.0 Type Library CsiDatalogger 1.0 Type Library CsiDataSource 1.0 Type Library CsiLogMonitor 1.0 Type Library CsiServer 1.0 Type Library

5-1

Section 5. Developing an Application Using the CsiCoraScript Control

Check the box next to the CsiCoraScript 1.0 Type Library, click Apply, and then close the window. Now an icon for the CsiCoraScript control and other common controls will appear in the toolbox.

5.2.2 CsiCoraScript Control Application Example

You are now ready to begin creating an application that executes CoraScript commands with the LoggerNet server. An example of a user interface that accomplishes this task is shown in Figure 5-1. This interface includes the CsiCoraScript control and other objects on the form to create a functional application.

5-2

FIGURE 5-1. CsiCoraScript Example

Now that the interface has been designed, the code can be organized to accomplish the requirements of the application. Initially, the application must connect to the LoggerNet server using the serverConnect() method. A basic example of code used to accomplish this task is shown in the table that follows:

Section 5. Developing an Application Using the CsiCoraScript Control

Private Sub cmdConnect_Click()

'Connect using the default logon settings. CsiCoraScript.serverName = txtServerAddress CsiCoraScript.serverPort = txtServerPort CsiCoraScript.serverLogonName = txtUsername CsiCoraScript.serverLogonPassword = txtPassword

'The following attempts to connect to the LoggerNet server 'and calls the event onServerConnectStarted()if the connection 'starts or the event onServerConnectFailure()if it fails.

CsiCoraScript.serverConnect

End Sub

If the connection succeeds, the onServerConnectStarted() event gets triggered. Otherwise, the onServerConnectFailure() event gets called if the connection fails.

In order to execute CoraScript commands on the LoggerNet server, use the method executeScript(). A basic example of code using this method to execute CoraScript commands and displaying the results in the interface follows:

Private Sub cmdCoraScript_Click()

Dim corascript As String

'Send CoraScript commands to the LoggerNet Server 'Sample CoraScript commands include: 'list-devices; 'add-device com-port Com1 before ""; 'add-device CR10x CR10X_Test as-child Com1; corascript = CsiCoraScript.executeScript(txtCoraScript.Text, 0) txtCoraResult.Text = corascript

End Sub

Add additional functionality, error handling, and objects as necessary beyond the example interface and code listed above to meet the specific requirements of your application. Complete examples using the CsiCoraScript control are included in the LoggerNet SDK installation.

5-3

Section 5. Developing an Application Using the CsiCoraScript Control

5-4

Section 6. CsiBrokerMap Control

6.1 Purpose of the CsiBrokerMap Control

The CsiBrokerMap control gives developers access to the broker map, which is the list of brokers or dataloggers known by the LoggerNet server. This control also keeps track of all tables on each of the brokers including the table definitions or columns. This table information is derived from the collect areas that are known by the LoggerNet server. Collect areas are known by the LoggerNet server after a datalogger program has been associated or table definitions have been retrieved. The user may also create collect areas manually in the LoggerNet server.

The information given by the CsiBrokerMap control can be used as parameters for other controls in the SDK. For example, the CsiDataLogger control can use the name of a datalogger that was displayed to the user through the CsiBrokerMap control. Similarly, the CsiBrokerMap control can display specific brokers, tables, and columns that the CsiDataSource control can use to create an advisor that monitors acquired data.

This control can also be used in combination with the CsiDatalogger control to set a value within a datalogger table. With information about the names of a broker, a table, and a column provided by the CsiBrokerMap control, the

variableSetStart method of the CsiDatalogger control could be used to set

the value of that column.

The CsiBrokerMap can be a useful tool to display the dataloggers, tables and columns that exist in the LoggerNet server datalogger network.

6.2 Connecting to the LoggerNet Server

There are two basic actions required to connect to the LoggerNet server:

1) Set server properties:

serverName - The name of the LoggerNet server or IP address. The

default value is

b) serverPort - The port on which the LoggerNet server is running. The

default value is

c) serverLogonName (Optional) - If security has been enabled on the

server, a valid logon name is required.

serverLogonPassword (Optional) - If security has been enabled on

the server, a valid password that corresponds with a valid logon name is required.

2) Invoke the s

tart() method.

localhost.

6789.

6-1

Section 6. CsiBrokerMap Control

6.3 How Collections Work

The CsiBrokerMap uses the concept of collections in its implementation. Collections provide layers of objects and a standard way to access those objects. There are two basic ways to look at collections. The Visual Basic (VB) view describes how a VB programmer would view a collection, which is simpler than for Delphi or Visual C++.

6.3.1 Visual Basic View of Collections

The CsiBrokerMap collections are simply three levels of grouped items. Brokers exist at the top-most level. Then within Brokers are Tables, and within Tables are Columns. Each of these levels can be accessed with the dot operator in Visual Basic. The following example illustrates how to access all of the Brokers in the BrokerMap:

6.3.1.1 Accessing Collections with For Each

For Each b in BrokerMap.Brokers Debug.Print b.name Next

This simplistic code allows you to iterate through the BrokerMap simply without having to worry about indexes and going out of bounds. In the code above, it would be possible to access all of the tables in each broker by nesting a similar loop inside the existing one stating

BrokerMap.Brokers(b).Tables. By repeating similar code for the

columns the whole broker map could be displayed.

For Each t in

6.3.1.2 Accessing Collections with Indexes and Names

The brokers, tables, and columns can be accessed not only with the “For

Each

” loop, but also by index and name. Consider the following examples:

BrokerMap.Brokers("CR9000").Tables("minute").Columns("temp").size For i = 0 to BrokerMap.Brokers.Count – 1 Debug.Print BrokerMap.Brokers(i) Next

The first line of code assumes that a datalogger named CR9000 with a table named minute exists in the broker map. The code also assumes a column named temp exists in the table named minute. These names could also be

String variables instead of literal strings.

6.3.2 Delphi/Visual C++ View of Collections

Delphi and Visual C++ require a little more work to capture the information provided by this control, but not much more than Visual Basic's iterative method using indexes. Please refer to the code in the Delphi and Visual C++ examples included with the LoggerNet SDK installation.

6-2

6.4 CsiBrokerMap Interfaces

The following interfaces are included in the CsiBrokerMap control:

• Broker

• BrokerMap

• BrokerCollection

• Column

• ColumnCollection

• Table

• TableCollection

6.4.1 BrokerMap Interface

See the Reference Section for detailed descriptions of these properties, methods, and events.

6.4.1.1 Properties

• serverName As String

• serverLogonName As String

• serverLogonPassword As String

• serverPort As Long

• autoExpand As Boolean

• serverConnected As Boolean

Section 6. CsiBrokerMap Control

6.4.1.2 Methods

• brokers() As Object

• finish()

• start()

6.4.1.3 Events

• onAllStarted()

• onBrokerAdded(Object Broker)

• onBrokerDeleted(Object Broker)

• onFailure(BrokerMapFailureType failure_code)

• onTableAdded(Object Broker, Object Table)

• onTableDeleted(Object Broker, Object Table)

• onTableChanged(Object Broker, Object Table)

• onBrokerStarted(Object Broker)

6.4.2 BrokerCollection Interface

See the Reference Section for descriptions of these properties and methods.

6.4.2.1 Properties

• count As Long

6-3

Section 6. CsiBrokerMap Control

6.4.2.2 Methods

• item(id) As Broker

• _NewEnum() (GetEnumerator() in .NET)

6.4.3 Broker Interface

See the Reference Section for descriptions of these properties and methods.

6.4.3.1 Properties

• id As Long

• name As String

• type As BrokerType

• datalogger_type as String

• allStarted as Boolean

6.4.3.2 Methods

• tables() As Object

• start_expansion()

6.4.4 Table Collection Interface

See the Reference Section for descriptions of these properties and methods.

6.4.4.1 Properties

• count As Long

6.4.4.2 Methods

• item(id) As Table

• _NewEnum() (GetEnumerator() in .NET)

6.4.5 Table Interface

See the Reference Section for descriptions of these properties and methods.

6.4.5.1 Properties

• interval As Long

• name As String

• originalSize As Long

• size As Long

6-4

6.4.5.2 Methods

• columns() As Object

• start_expansion()

6.4.6 ColumnCollection Interface

See the Reference Section for descriptions of these properties and methods.

6.4.6.1 Properties

• count As Long

6.4.6.2 Methods

• item(id) As Column

• _NewEnum() (GetEnumerator() in .NET)

6.4.7 Column Interface

See the Reference Section for descriptions of these properties.

6.4.7.1 Properties

• description As String

• name As String

• process As String

• type As CsiDataTypeCode

• units As String

• writable As Long

Section 6. CsiBrokerMap Control

6-5

Section 6. CsiBrokerMap Control

6-6

Section 7. Developing an Application Using the CsiBrokerMap Control

7.1 Purpose

This section shows by example how to build an application using the CsiBrokerMap SDK control. The application’s stated functions are:

1. Display names of all stations in the current network.

2. Upon selection of any single station, display tables associated with that

station's currently running program.

3. Upon selection of any single table, display all fields (columns) included in

that table.

The following section illustrates how to build an application that can perform these tasks using SDK controls and the LoggerNet server.

7.2 Using the CsiBrokerMap Control

7.2.1 Getting Started with the CsiBrokerMap Control

The CsiBrokerMap is an SDK control (an ActiveX object) designed to display names of dataloggers in the current network. This control can also display names of all tables belonging to the selected datalogger and columns in the selected table. This information is derived from collect area information created when a program is associated with a datalogger or when table definitions are retrieved from the datalogger. Since the BrokerMap control does not list devices if collect areas are not known, use the CoraScript control to associate the program or to retrieve table definitions.

This example assumes that:

• you have registered the SDK controls correctly

• you are developing the application with Visual Basic 6.0

• a LoggerNet server is currently running and accessible on the network

• at least one station already exists in the LoggerNet server's network map

• the datalogger program has been associated or table definitions have been

retrieved

Complete the following steps first:

1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |

Microsoft Visual Basic 6)

7-1

Section 7. Developing an Application Using the CsiBrokerMap Control

2. Start a new project (File | New Project | Standard EXE | OK). This will

open a new, blank form.

3. View the toolbox for this new project (VB 6 Main Menu | View |

Toolbox).

4. Right click on the toolbox area and then on the word Components to open

the component window. If the SDK controls are registered on your PC, the following CSI components will appear:

CsiBrokerMap 1.0 Type Library CsiCoraScript 1.0 Type Library CsiDatalogger 1.0 Type Library CsiDataSource 1.0 Type Library CsiLogMonitor 1.0 Type Library CsiServer 1.0 Type Library

Check the box next to CsiBrokerMap 1.0 Type Library, click on Apply, and then close the window. An icon for the CsiBrokerMap control will appear in the toolbox.

7.2.2 CsiBrokerMap Control Application Example

Begin creating an application that displays the stations, tables, and columns that exist in the LoggerNet server. Design the interface and change properties to meet the requirements of your application. An example for a user interface that accomplishes the tasks outlined in the previous section is shown in Figure 7-1. This interface includes the CsiBrokerMap control and other objects to create a functional application.

7-2

FIGURE 7-1. CsiBrokerMap Example

Section 7. Developing an Application Using the CsiBrokerMap Control

Now that the interface has been designed, the code can be organized to accomplish the requirements of the application. The control must be started using the correct parameters to connect with a LoggerNet server. A basic example of code used to accomplish this task is listed in the table below:

Private Sub cmdConnect_Click()

'Assign the connection parameters BrokerMap.serverName = txtServerAddress.Text BrokerMap.serverPort = txtServerPort.Text BrokerMap.serverLogonName = txtUsername.Text BrokerMap.serverLogonPassword = txtPassword.Text

'Start the BrokerMap control using the variables above 'The onAllStarted() event will be activated if a connection 'occurs or the onFailure() event will be activated if the 'connection fails BrokerMap.start

End Sub

If the connection succeeds, the onAllStarted() event gets triggered. Otherwise, the

onFailure() event gets called. The onAllStarted() event

should contain code that iterates through the stations and displays the appropriate values in a window on the user interface. Example code for the

onAllStarted() event is listed in the table below:

Private Sub BrokerMap_onAllStarted()

Dim n As Node Dim b As Broker Dim t As Table Dim c As Column

'After the broker map starts, ignore any changes such as additions 'or deletions of brokers or tables from the broker map. BrokerMap.finish

'Clear out the tree view for a fresh network map tvwDisplay.Nodes.Clear

'Set the root node Set n = tvwDisplay.Nodes.Add(, , "Root", "Broker Map")

'Read in the checkboxes to determine the names of the stations, 'tables and columns that will populate the TreeView object. If chkStations.Value = 1 Then For Each b In BrokerMap.Brokers Debug.Print b.Name & " " & b.Type

'Display the Broker Names if checked Set n = tvwDisplay.Nodes.Add("Root", tvwChild, b.Name, b.Name)

'If Tables are checked, get all of the tables in that Broker If chkTables.Value = 1 Then For Each t In b.Tables 'Display the table names Set n = tvwDisplay.Nodes.Add(b.Name, tvwChild, b.Name & "." & t.Name, t.Name) 'If Columns checked, get all of the columns in the tables If chkColumns.Value = 1 Then For Each c In t.Columns 'Display the column names Set n = tvwDisplay.Nodes.Add(b.Name & "." & t.Name, tvwChild, b.Name & _

7-3

Section 7. Developing an Application Using the CsiBrokerMap Control

"." & t.Name & "." & c.Name, c.Name) Next End If Next End If Next

Else MsgBox "You must first select to display the Stations." End If

End Sub

Add additional functionality, error handling, and objects as necessary to meet the specific requirements of your application. Complete examples using the CsiBrokerMap control are included in the LoggerNet SDK installation.

7-4

Section 8. CsiDatalogger

8.1 Purpose of the CsiDatalogger Control

The CsiDatalogger control allows the developer to manage datalogger functions through the LoggerNet server. The basic managerial functions of this control include: sending a program to the datalogger, retrieving a program from the datalogger, checking the clock on the datalogger as well as setting it to the current time, setting variable values, and performing manual polls of the datalogger. Another important function creates an active connection between the server and the datalogger, to eliminate connection and disconnection overhead on slower connections.

8.2 Connecting to the Server

There are two basic actions required for this control to connect to the LoggerNet server:

1. Set server properties:

serverName - The name or IP address of the LoggerNet server . The

•

default value is

serverPort - The port on which the LoggerNet server is running.

•

The default value is 6789

localhost.

serverLogonName (Optional) - If security has been enabled on the

•

server, a valid logon name is required.

serverLogonPassword (Optional) - If security has been enabled on

•

the server, a valid password that corresponds with a valid logon name is required.

2. Invoke the

8.3 Datalogger Interface

8.3.1 Properties

• clockBusy As Boolean

• loggerConnected As Boolean

• loggerName As String

• manualPollBusy As Boolean

• programReceiveBusy As Boolean

• programSendBusy As Boolean

• serverConnected As Boolean

• selectiveManualPollBusy As Boolean

• serverLogonName As String

• serverLogonPassword As String

• serverName As String

• serverPort As Long

serverConnect() method.

8-1

Section 8. CsiDatalogger

8.3.2 Methods

8.3.3 Events

• clockCancel()

• clockCheckStart()

• clockSetStart()

• loggerConnectCancel()

• loggerConnectStart(logger_priority_type priority)

• manualPollCancel()

• manualPollStart()

• programReceiveCancel()

• programReceiveStart(String fileName)

• programSendCancel()

• programSendStart(String file_name, String program_name)

• selectiveManualPollCancel()

• selectiveManualPollStart()

• serverConnect()

• serverDisconnect()

• onClockComplete(Boolean successful, clock_outcome_type respose_code,

Date current_date)

• onLoggerConnectFailure(logger_failure_type fail_code)

• onLoggerConnectStarted()

• onManualPollComplete(Boolean successful, manual_poll_outcome_type

response_code)

• onProgramCompiled()

• onProgramReceiveComplete(Boolean successful,

prog_receive_outcome_type response_code)

• onProgramReceiveProgress(Long received_bytes)

• onProgramSendComplete(Boolean successful, prog_send_outcome_type

response_code, String compile_result)

• onProgramSendProgress(Long sent_bytes, Long total_bytes)

• onProgramSent()

• onSelectiveManualPollComplete(Boolean successful,

selective_manual_poll_outcome_type response_code)

• onServerConnectFailure(server_failure_type failure_code, )

• onServerConnectStarted()

8-2

Section 9. Developing an Application Using the Datalogger Control

9.1 Purpose

This section illustrates the use of the CsiDatalogger control. This control interacts with dataloggers through the LoggerNet server to perform managerial tasks. These tasks require a connection with the specified datalogger. The user-interface we are about to develop will:

• Connect to the LoggerNet server

• Enter a datalogger to manage

• Establish an active connection with the datalogger

• Check and display time at the datalogger

• Send/Receive datalogger programs

• Retrieve data collected by a datalogger

The following section illustrates how to build an application that can perform these tasks using the CsiDatalogger control and the LoggerNet server.

9.2 Using the CsiDatalogger Control

9.2.1 Getting Started with the CsiDatalogger Control

CsiDatalogger is an SDK control (an ActiveX object) designed to display names of dataloggers in the current network. This control can also display names of all tables belonging to the selected datalogger and columns in the selected table.

This example assumes that:

• you have registered the SDK controls correctly

• you are developing the application with Visual Basic 6.0

• a LoggerNet server is currently running and accessible on the network

• at least one station already exists in the LoggerNet server's network map

Complete the following steps first:

1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |

Microsoft Visual Basic 6)

9-1

Section 9. Developing an Application Using the Datalogger Control

2. Start a new project (File | New Project | Standard EXE | OK). This will

open a new, blank form.

3. View the toolbox for this new project (VB 6 Main Menu | View |

Toolbox).

4. Right click on the toolbox area and then on the word Components to open

a component window. If the SDK controls are registered on your PC, the following CSI components will appear:

CsiBrokerMap 1.0 Type Library CsiCoraScript 1.0 Type Library CsiDatalogger 1.0 Type Library CsiDataSource 1.0 Type Library CsiLogMonitor 1.0 Type Library CsiServer 1.0 Type Library

Check the box next to the CsiDatalogger 1.0 Type Library, click Apply, and then close the window. An icon for the CsiDatalogger control will appear in the toolbox.

9.2.2 CsiDatalogger Control Application Example

Begin creating an application that manages an existing datalogger in the LoggerNet server network map. Design the interface and change properties to meet the requirements of your application. An example for a user interface that accomplishes the tasks outlined in the previous section is shown in Figure 9-1. This interface includes the CsiDatalogger control and other objects to create a functional application.

9-2

FIGURE 9-1. CsiDatalogger Example

Section 9. Developing an Application Using the Datalogger Control

Now that the interface has been designed, the code can be organized to accomplish the requirements of the application. The control must connect with the LoggerNet server using the correct parameters and the

serverConnect()

method. A basic example of code used to accomplish this task is listed in the table below:

Private Sub cmdConnect_Click()

'Set the connection parameters DataLogger.serverName = txtServerAddress DataLogger.serverPort = txtServerPort DataLogger.serverLogonName = txtUsername DataLogger.serverLogonPassword = txtPassword

'Connect to the LoggerNet server DataLogger.serverConnect

End Sub

If the connection succeeds, the onServerConnectStarted() event is triggered. Otherwise, the

onServerConnectFailure() event is called.

Next, set the name of the specific datalogger to be managed. An application can use the CsiBrokerMap control to display all stations and allow the user to select a specific datalogger from the network map. However, in this example, the user merely enters the name of a datalogger known to exist in the LoggerNet server network map. In this example, the user changes the datalogger to manage by entering a new datalogger name. However, if communication is in progress between the LoggerNet server and the datalogger, the user will not be able to change the datalogger name. An example of the code used to set the datalogger name can be found in the table below:

Private Sub txtDataloggerName_Change()

'Make sure a datalogger connection is not active If DataLogger.loggerConnected Then MsgBox "Connection Active. Can't change datalogger name." TxtDataloggerName = DataLogger.loggerName Else DataLogger.loggerName = txtDataloggerName End If

End Sub

After setting the datalogger name, the managerial functions can be called to access the datalogger. The

loggerConnectStart() method can be used to

create a persistent connection between the LoggerNet server and the datalogger. The connection succeeds. Otherwise, the

onLoggerConnnectStarted() event gets called if the

onLoggerConnectFailed() event gets

called if the connection fails. A persistent connection allows multiple transactions to occur without the need to connect and disconnect across the network to the datalogger. The following code illustrates the use of the loggerConnectStart() method:

9-3

Section 9. Developing an Application Using the Datalogger Control

Private Sub cmdDataloggerConnect_Click()

'Create an active connection to the datalogger so that a 'new connection isn't required for every transaction If DataLogger.serverConnected Then If DataLogger.loggerConnected Then WriteMessage "Already connected to datalogger" CmdDataloggerConnect.Enabled = False cmdDataloggerDisconnect.Enabled = True Else DataLogger.loggerConnectStart lp_priority_normal WriteMessage "Datalogger Connection Active" End If Else WriteMessage "Not connected to the LoggerNet server" End If

End Sub

The loggerConnectCancel() method cancels the managerial connection between the LoggerNet server and the datalogger. After running this method, the server will be returned to the default behavior of connecting and disconnecting from the datalogger for each transaction. The example code in the table below shows this method:

Private Sub cmdDataloggerDisconnect_Click()

'Stop the active connection to the datalogger. If DataLogger.serverConnected Then If DataLogger.loggerConnected Then DataLogger.loggerConnectCancel WriteMessage "Active Datalogger Connection Stopped." Else WriteMessage "No Active Connection" End If Else WriteMessage "Not connected to the LoggerNet server" End If

End Sub

The clockCheckStart() method will check the clock on the datalogger while the

clockSetStart() method sets the clock on the datalogger to the

time on the LoggerNet server. Both of these methods call the

onClockComplete() event that returns the current time of the datalogger

clock. Example code for the clock check, clock set, and clock complete methods and event can be found in the following tables:

9-4

Section 9. Developing an Application Using the Datalogger Control

Private Sub cmdCheck_Click()

'Check the clock on the datalogger. If DataLogger.clockBusy Then WriteMessage "Clock check already in progress" Else If DataLogger.serverConnected Then DataLogger.clockCheckStart WriteMessage "Clock Check Started" Else WriteMessage "Not connected to the LoggerNet server" End If End If

End Sub

Private Sub cmdSet_Click()

'Set the clock on the If DataLogger.clockBusy Then WriteMessage "Clock set already in progress" Else If DataLogger.serverConnected Then DataLogger.clockSetStart WriteMessage "Clock Set Started" Else WriteMessage "Not connected to the LoggerNet server" End If End If

End Sub

Private Sub DataLogger_onClockComplete(ByVal successful _ As Boolean, ByVal response_code As _ CSIDATALOGGERLibCtl.clock_outcome_type, ByVal _ current_date As Date)

'Clock check complete If successful Then WriteMessage "Current Datalogger Clock: " & _ current_date Else WriteMessage "Clock Check/Set failed. Code: " & _ response_code End If

End Sub

The manualPollStart() method connects to the datalogger and retrieves data. The

manualPollCancel() method can be called to cancel a polling

event in progress. Both of these methods trigger the

onManualPollComplete() event, which returns the appropriate response

code if the poll succeeded, failed, or was cancelled. The following tables contain code illustrating the use of these methods and event:

9-5

Section 9. Developing an Application Using the Datalogger Control

Private Sub cmdDataStart_Click()

'Begin a manual poll to retrieve data If DataLogger.serverConnected Then DataLogger.manualPollStart WriteMessage "Manual Poll Started" Else WriteMessage "Not connected to the LoggerNet server" End If

End Sub

Private Sub cmdDataStop_Click()

'Try to cancel a manual poll that is in progress. If DataLogger.serverConnected Then DataLogger.manualPollCancel WriteMessage "Trying to Cancel Manual Poll" Else WriteMessage "Not connected to the LoggerNet server" End If

End Sub

Private Sub DataLogger_onManualPollComplete(ByVal _ successful As Boolean, ByVal response_code As _ CSIDATALOGGERLibCtl.manual_poll_outcome_type)

If successful Then WriteMessage "Manual Poll Complete" Else If response_code = mp_outcome_aborted Then WriteMessage "Manual Poll Aborted Successfully" Else WriteMessage "Manual Poll Failed. Code: " & _ response_code End If End If

End Sub

The programReceiveStart() method retrieves the current program from a datalogger and saves it as a specified filename. The

onProgramReceiveProgress() event is triggered and provides information

regarding the progress of the program retrieval.

onProgramReceiveComplete() event also runs when the file retrieval

The

process either completes or fails. The following table shows example code for

the programReceiveStart() method:

9-6

Section 9. Developing an Application Using the Datalogger Control

Private Sub cmdRetrieve_Click()

'Get the current program from the datalogger If DataLogger.serverConnected Then DataLogger.programReceiveStart txtRetrieve WriteMessage "Retrieving Program from the Datalogger" Else WriteMessage "Not connected to the LoggerNet server" End If

End Sub

The programSendStart() method sends a program to the specified datalogger and calls the onProgramSendProgress() event, the onProgramSent() event, and the onProgramSendComplete() event respectively. The following table contains example code for the programSendStart() method:

Private Sub cmdSend_Click()

'Send a program to the datalogger If DataLogger.serverConnected Then If txtSend = "" Then WriteMessage "Enter a Program to Send" Else DataLogger.programSendStart txtSend, "" WriteMessage "Sending Program " & txtSend End If Else WriteMessage "Not connected to the LoggerNet server" End If

End Sub

Additional functionality, error handling, and objects should be added as necessary beyond the example interface and code listed above to meet the specific requirements of your application. Complete examples using the CsiDatalogger control are included in the LoggerNet SDK installation.

9-7

Section 9. Developing an Application Using the Datalogger Control

9-8

Section 10. CsiDataSource Control

10.1 Purpose of the CsiDataSource Control

The CsiDataSource control allows an application to monitor data collected through the LoggerNet server. These sessions that monitor data are know as Advisors. Advisors display data collected in the LoggerNet server data cache. This control can have multiple advisor sessions with a single server connection.

This control requires that the LoggerNet server collect data for the same tables or final storage areas that are being monitored. If you start an advisor on a table that is not being collected by the LoggerNet server, you will not receive any onAdviseRecord events. An exception to this rule occurs if you are monitoring input locations on a mixed-array datalogger. When you create an advisor for an input location on a mixed-array datalogger, a temporary data cache is created. Then, with the advisor ready, enabling scheduled collection with the datalogger will return records to the advisor.

The CsiBrokerMap control is often used in conjunction with this control to display what tables and columns can be monitored. Additionally, the CsiDatalogger control can also be used to issue a manual data poll and collect records from the datalogger.

10.2 Connecting to the Server

There are two basic actions required to connect to the LoggerNet server:

1. Set server properties:

• serverName - The name or IP address of the LoggerNet server. The

default value is

• serverPort - The port on which the LoggerNet server is running. The

default value is

• logonName (Optional) - If security has been enabled on the server, a

valid logon name is required.

• logonPassword (Optional) - If security has been enabled on the

server, the correct password for a valid logon name is required.

2. Invoke the

connect() method.

localhost.

6789

10-1

Section 10. CsiDataSource Control

10.3 CsiDataSource Interfaces

The following interfaces are used in the CsiDataSource control:

• DSource – the controlling interface

• Advisor - created through the DSource interface to monitor certain data

columns on a specified station and table.

• Record - received in the event onAdviseRecord. A record is a collection

of values that contain data.

• Value - contains the name and value of a single column.

10.3.1 Dsource Interface

See the Reference Section for descriptions of these properties, methods, and events.

10.3.1.1 Properties

10.3.1.2 Methods

10.3.1.3 Events

• logonName As String

• logonPassword As String

• serverName As String

• serverPort As Long

• state As data_source_state

• sendRecordBlocks as Boolean

• connect()

• createAdvisor() As Object

• disconnect()

• onAdviseReady(Object myAdvisor)

• onAdviseRecord(Object myAdvisor, Object myRecord)

• onAdvisorFailure(csiAdvisorFailureCode failure, Object myAdvisor)

• onControlFailure(csidsFailureCode failureCode)

• onControlReady()

• onVariableSetComplete(Long tran_id, Object myAdvisor, Boolean

successful, variable_outcome_type response_code)

• onAdviseRecords(Object myAdvisor, object record_collection)

10-2

10.3.2 Advisor Interface

See the Reference Section for descriptions of these properties, methods, and events.

10.3.2.1 Properties

10.3.2.2 Methods

Section 10. CsiDataSource Control

• advisorName As String

• orderOption As csidsOrderOptionType

• startDate As Date

• startFileMarkNo As Long

• startIntervalSeconds As Long

• startOption As csidsStartOptionType

• startRecordNo As Long

• startRecordNoString As String

• state As advisor_state

• stationName As String

• tableName As String

• startDateNanoSeconds As Long

• maxRecordsPerBlock As Long

• columns() As Object

• start()

• stop()

• variableSetCancel(Long tran_id)

• variableSetStart(String column_name, String value) as Long

10.3.3 DataColumnCollection Interface

See the Reference Section for descriptions of these properties and methods.

10.3.3.1 Properties

• count As Long

10.3.3.2 Methods

• add(String columnName)

• addAll()

• find(String column_name) As Long

• Item(id) As DataColumn

• remove(String columnName)

• removeAll()

• _NewEnum() (GetEnumerator() in .NET)

10.3.4 DataColumn Interface

See the Reference Section for descriptions of these properties.

10.3.4.1 Properties

• name As String

10-3

Section 10. CsiDataSource Control

10.3.5 Record

See the Reference Section for descriptions of these properties, methods, and events.

10.3.5.1 Properties

• fileMarkNo As Long

• recordNo As Long

• timeStamp As Date

• valuesCount As Long

• nanoSeconds as Long

10.3.5.2 Methods

• item(id) as value

• _NewEnum() (GetEnumerator() in .NET)

10.3.6 RecordCollection

10.3.6.1 Properties

• Count As Long

10.3.6.2 Methods

• Item(id, record)

• _NewEnum() (GetEnumerator() in .NET)

10.3.7 Value Interface

See the Reference Section for descriptions of these properties, methods, and events.

10.3.7.1 Properties

• columnName As String

• value As Variant

10-4

Section 11. Developing an Application Using the CsiDataSource Control

11.1 Purpose

The CsiDataSource control primarily monitors data residing in the LoggerNet server data cache. The LoggerNet server data cache is a location where the server stores collected datalogger records. The control can also be used to see measurements performed in real-time; for example, values being recorded for input locations in mixed-array dataloggers. The BrokerMap control often accompanies this control to display the names of tables and columns in each table so they can be selected for data monitoring. However, the example illustrated in this section requires that the user enter a station and table that are known to exist on the LoggerNet server and all columns will be monitored within that table. The application we develop will:

• Connect to a LoggerNet server

• Allow the user to enter a known station and table

• Monitor data in all columns of the table

The following section illustrates how to build an application that can perform these tasks using the CsiDataSource control and the LoggerNet server.

11.2 Using the CsiDataSource Control

11.2.1 Getting Started with the CsiDataSource Control

CsiDataSource is an SDK control (an ActiveX object) designed to monitor data collected from the dataloggers in the LoggerNet network. This example assumes that:

• you have registered the SDK controls correctly

• you are developing the application with Visual Basic 6.0

• a LoggerNet server is currently running and accessible on the network

• at least one station already exists in the LoggerNet server's network map

Complete the following steps first:

1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |

Microsoft Visual Basic 6)

2. Start a new project (File | New Project | Standard EXE | OK). This will

open a new, blank form.

11-1

Section 11. Developing an Application Using the CsiDataSource Control

3. View the toolbox for this new project (VB 6 Main Menu | View |

Toolbox).

4. Right click on the toolbox area and then on the word Components to open

a component window. If the SDK controls are registered on your PC, the following CSI components will appear:

CsiBrokerMap 1.0 Type Library CsiCoraScript 1.0 Type Library CsiDatalogger 1.0 Type Library CsiDataSource 1.0 Type Library CsiLogMonitor 1.0 Type Library CsiServer 1.0 Type Library

Check the box next to the CsiDataSource 1.0 Type Library, click Apply, and then close the window. An icon for the CsiDataSource control will appear in the toolbox.

11.2.2 CsiDataSource Control Application Example

You are now ready to begin creating an application that monitors data from an existing datalogger table in the LoggerNet server network map. Design the interface and change properties to meet the requirements of your application. An example interface that accomplishes the tasks outlined previously in this section is shown in Figure 11-1. This interface includes the CsiDataSource control and other objects to create a functional application.

11-2

FIGURE 11-1. CsiDataSource Example

Section 11. Developing an Application Using the CsiDataSource Control

connect() method.

If the connection succeeds, the onControlReady() event will be called. A basic example of code used to accomplish this task is listed in the table below:

Private Sub cmdConnect_Click()

'Set connection parameters DSource.serverName = txtServerAddress DSource.serverPort = txtServerPort DSource.logonName = txtUsername DSource.logonPassword = txtPassword

'Connect to the LoggerNet server. Successful connections will be 'handled by the onControlReady() function. If the control fails, 'the onControlFailure() function will handle these failures DSource.Connect

End Sub

Once connected to the LoggerNet server, the Advisor can be created by entering a known datalogger and table in the text fields and calling the createAdvisor() method. An application may use the CsiBrokerMap to display all stations and allow the user to select a specific datalogger, table, and column. However, in this example, the user merely enters the name of a datalogger and table known to exist in the LoggerNet server network map. An example of the code used to start an Advisor that will monitor data in all columns of a specific datalogger and table can be found in the table below:

Private Sub cmdStartAdvisor_Click() Dim CurrentAdvisor as Advisor Dim dcc as DataColumnCollection

'Create a new advisor. Make sure a connection is active to the 'LoggerNet server before attempting to start the Advisor. 'Add all columns to the Advisor to simplify the example. Set CurrentAdvisor = Dsource.createAdvisor

'Set some properties for the advisor CurrentAdvisor.advisorName = "NewAdvisor" CurrentAdvisor.stationName = txtDatalogger CurrentAdvisor.tableName = txtTable

'Add all columns to the advisor. Set dcc = CurrentAdvisor.columns dcc.addAll

'Start the Advisor. When started, onAdviseReady and 'onAdviseRecord will activate. If an advisor fails, the 'onAdvisorFailure event will be called. CurrentAdvisor.start End If

End Sub

After starting the Advisor, the onAdviseReady() event will run and begin watching the specified table and columns for new data. The onAdviseRecord() event gets called when new records appear in the LoggerNet server data cache from the specified datalogger table and columns. The following code illustrates how records are received:

11-3

Section 11. Developing an Application Using the CsiDataSource Control

Private Sub DSource_onAdviseRecord(ByVal myAdvisor As Object, _ ByVal myRecord As Object)

'Declare Variables Dim val As Value Dim rec As Record

Set rec = myRecord

'Display the Advisor and record information to the user WriteMessage "" WriteMessage "OnAdvise ready event occurred" WriteMessage "Advisor Name: " & CurrentAdvisor.advisorName WriteMessage "FileMarkNo. " & rec.fileMarkNo WriteMessage "RecordNo. " & rec.recordNo WriteMessage "TimeStamp. " & rec.TimeStamp

'Display the values for all columns in the record For Each val In rec WriteMessage val.columnName & ": " & val.Value Next

End Sub

The Advisor will continue displaying new records as they are received until the stopAdvisor() method is called to stop the Advisor. The following code illustrates the use of this method:

Private Sub cmdStopAdvisor_Click()

'Stop the Advisor. CurrentAdvisor.stop WriteMessage "Advisor Stopped"

End Sub

Additional functionality, error handling, and objects should be added as necessary beyond the example interface and code listed above to meet the specific requirements of your application. Complete examples using the CsiDataSource control are included in the LoggerNet SDK installation.

11-4

Section 12. CsiLogMonitor Control

12.1 Purpose of the CsiLogMonitor Control

The CsiLogMonitor Control provides access to log message from the LoggerNet server. The log messages stream to this control as a text string. Use this control to display log messages or to monitor events as they occur on the server and call other operations or programs based on these LoggerNet server events.

The types of log files that can be retrieved from the LoggerNet server with the CsiLogMonitor control include the transaction log and the communication log. The transaction log messages use the following basic format:

“StationName”, “MessageNumber”, “Message”

The developer can create a program using the CsiLogMonitor control to filter each message by station name and watch for message numbers and messages that indicate a specific event. By parsing the transaction log text string and looking for the triggering messages listed below, the declared station event can be monitored.

Some station events require a preceding message. In these cases, look for the preceding message and then for the triggering message to appear later in the log messages. The preceding message will not necessarily appear in the logs immediately prior to the triggering log message.

Station Event Triggering Log Message

“MessageNumber”, “Message”

On Call-Back “114”, “Call-back Started” N/A

After Call-Back “116”, “Call-back Stopped” N/A

The communication log messages use the following basic format:

“StationName”, “MessageType”, “Message”

The message types in the communication log are “S” for a status message, “W” for a warning message, and “F” for a failure message. Status messages are general communication messages, warning messages declare a possible problem and communication retries, and failure messages appear when all retries have been exhausted and communication will no longer be attempted by the LoggerNet server for a specific transaction.

Preceding Log Message “MessageNumber”, “Message”

12-1

Section 12. CsiLogMonitor Control

12.2 CsiLogMonitor Interface

See the Reference section in this manual for detailed descriptions of these properties, methods, and events.

12.2.1 Properties

• commLogMonitorBusy As Boolean

• commLogRecordsBack As Long

• serverConnected As Boolean

• serverLogonName As String

• serverLogonPassword As String

• serverName As String

• serverPort As Long

• tranLogMonitorBusy As Boolean

• tranLogRecordsBack As Long

12.2.2 Methods

• commLogMonitorStart()

• commLogMonitorStop()

• serverConnect()

• serverDisconnect()

• tranLogMonitorStart()

• tranLogMonitorStop()

12.2.3 Events

• onCommLogFailure(log_monitor_failure_type failure_code)

• onCommLogRecord(Date timestamp, String comm_log_record)

• onServerConnectFailure(server_failure_type failure_code)

• onServerConnectStarted()

• onTranLogFailure(log_monitor_failure_type failure_code)

• onTranLogRecord(Date timestatmp, String tran_log_record)

12-2

Section 13. Developing an Application Using the CsiLogMonitor Control

13.1 Purpose

This section shows an example of how to build an application using the CsiLogMonitor control. The application’s functions are:

1. Connect to a running LoggerNet server

2. Monitor the LoggerNet server transaction and communication logs.

13.2 Using the CsiLogMonitor Control

13.2.1 Getting Started with the CsiLogMonitor Control

The CsiLogMonitor SDK control (an ActiveX object) connects to the LoggerNet server and monitors transaction and communication logs.

This example assumes that:

• you have registered the CsiLogMonitor control correctly

• you are developing the application in Visual Basic 6.0

• a LoggerNet server is running and accessible on the network

Complete the following steps first:

1. Start Visual Basic 6.0 (Start | Programs | Microsoft Visual Basic 6.0 |

Microsoft Visual Basic 6)

2. Start a new project (File | New Project | Standard EXE | OK) opening a

new, blank form.

3. View the toolbox for this new project (VB 6 Main Menu | View |

Toolbox).

4. Right click on the toolbox area and select Components. A component

window will open and the following SDK controls will appear within the list if they are registered properly:

CsiBrokerMap 1.0 Type Library CsiCoraScript 1.0 Type Library CsiDatalogger 1.0 Type Library CsiDataSource 1.0 Type Library CsiLogMonitor 1.0 Type Library CsiServer 1.0 Type Library

13-1

Section 13. Developing an Application Using the CsiLogMonitor Control

Check the box next to the CsiLogMonitor 1.0 Type Library, click Apply, and close the window. An icon for the CsiLogMonitor control will appear in the toolbox.

13.2.2 CsiLogMonitor Control Application Example

You are now ready to begin creating an application that monitors log messages from the LoggerNet server. An example of a user interface that accomplishes this task is shown in Figure 13-1. This interface includes the CsiLogMonitor control and other objects on the form to create a functional application.

13-2

FIGURE 13-1. CsiLogMonitor Example

Section 13. Developing an Application Using the CsiLogMonitor Control

Private Sub cmdConnect_Click() 'Connect using the default logon settings. CsiLogMonitor.serverName = txtServerAddress CsiLogMonitor.serverPort = txtServerPort CsiLogMonitor.serverLogonName = txtUsername CsiLogMonitor.serverLogonPassword = txtPassword

'Start the connection to the LoggerNet server CsiLogMonitor.serverConnect

Exit Sub

If the connection succeeds, the onServerConnectStarted() event gets triggered. Otherwise, the onServerConnectFailure() event gets called if the connection fails.

In order to start monitoring the transaction log, the tranLogMonitorStart() method must be called. To monitor communication log messages, call the commLogMonitorStart() method.

The LoggerNet server maintains a buffer of historical log messages. By default, the last 100 log file messages will be retrieved when log monitoring first starts. To change the number of historical log messages that are retrieved, set the commLogRecordsBack and tranLogRecordsBack properties before starting log monitoring. A basic example of code using these methods to set the number of historical records received and to start collecting both types of log messages follows:

Private Sub cmdStart_Click() 'Set the number of historical log messages to retrieve from the 'LoggerNet server when monitoring starts CsiLogMonitor.commLogRecordsBack = 5 CsiLogMonitor.tranLogRecordsBack = 5

'Start Monitoring the Tranaction Log and the Communications Log 'on the LoggerNet server CsiLogMonitor.commLogMonitorStart CsiLogMonitor.tranLogMonitorStart

End Sub

Log messages will be passed as Strings to the onCommLogRecord() and onTranLogRecord() events respectively as they are generated by the LoggerNet server. A timestamp for when the log message is generated is also passed to these events. The String can be displayed or parsed and manipulated by station name and message type.

Private Sub CsiLogMonitor_onCommLogRecord(ByVal timestamp As Date, ByVal comm_log_record As String)

lstCommLog.AddItem timestamp & " : " & comm_log_record If lstCommLog.ListCount = 10 Then lstCommLog.Clear End If

End Sub

13-3

Section 13. Developing an Application Using the CsiLogMonitor Control

Stop monitoring logs with the commLogMonitorStop() and tranLogMonitorStop() events. You can check for active log monitoring by checking the commLogMonitorBusy and tranLogMonitorBusy properties or this control.

Private Sub cmdStop_Click() If CsiLogMonitor.commLogMonitorBusy Then CsiLogMonitor.commLogMonitorStop End If

If CsiLogMonitor.tranLogMonitorBusy Then CsiLogMonitor.tranLogMonitorStop End If

End Sub

Add additional functionality, error handling, and objects as necessary beyond the example interface and code listed above to meet the specific requirements of your application. Complete examples using the CsiLogMonitor control are included in the LoggerNet SDK installation.

13-4

Section 14. CsiServer Control Reference

14.1 Server Interface

14.1.1 Properties

Server.applicationWorkDir

Name

Server.applicationWorkDir As String

Description

This property gives the location where the LoggerNet server data files are stored and must be set before starting the LoggerNet. If this property needs to be changed after the LoggerNet server has been started, call stopServer(), set the new location, and then call startServer().

COM Return Values

Table of Possible Values

Server.buildDate

Name

Description

COM Return Values

Code Meaning

S_OK

E_CSI_BUSY

Server.buildDate As String

This read-only property displays the build date of the LoggerNet server.

Table of Possible Values

Code Meaning

S_OK

E_CSI_FAIL

E_CSI_NOT_STARTED

Success: Normal return

Error: The property cannot be set while a connection to the LoggerNet server is present

Success: Normal return

Error: Unexpected error

Error: The LoggerNet server is not started

14-1

Section 14. CsiServer Control Reference

Server.logFileDir

Name

Server.logFileDir As String

Description

This property specifies the location where the LoggerNet server writes log files and must be set before starting the LoggerNet server. If this property needs to be changed after the LoggerNet server has been started, call stopServer(), set the new location, and then call startServer(). By default the log file directory will be placed in the LoggerNet server working directory.

COM Return Values

Table of Possible Values

Code Meaning

Server.serverStarted

Name

Description

COM Return Values

S_OK

E_CSI_BUSY

Success: Normal return

Error: The property cannot be set while a connection to the LoggerNet server is present

Server.serverStarted As Boolean

This read-only value displays the current state of a LoggerNet server that has been started by the Server control. If the LoggerNet server is running, this value will be TRUE. Otherwise, this value will be FALSE.

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

14-2

Server.serverVersion

Name

Server.serverVersion As String

Description

This property is a read-only value that displays the version of the LoggerNet server.

COM Return Values

Table of Possible Values

Section 14. CsiServer Control Reference

Code Meaning

Server.serverWorkDir

Name

Description

COM Return Values

S_OK

E_CSI_FAIL

E_CSI_NOT_STARTED

Success: Normal return

Error: Unexpected error

Error: The LoggerNet server is not started

Server.serverWorkDir As String (Required)

This required property must be specified before starting the LoggerNet server and describes the location of the LoggerNet server configuration files. This property must be set before starting the LoggerNet server or the startServer() event will fail. If this location needs to be changed after the LoggerNet server has been started, call stopServer(), set the new location, and then call startServer().

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

Server.tcpPort

Name

Description

COM Return Values

E_CSI_BUSY

Error: The property cannot be set while a connection to the LoggerNet server is present

Server.tcpPort As Integer

This property sets the TCP port that the LoggerNet server will use when listening for client connections and must be set before starting the LoggerNet server. LoggerNet uses the TCP port 6789 by default. This property accepts 1 - 32767 as valid values.

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

14-3

Section 14. CsiServer Control Reference

Server.tcpPortEx

Name

Server.tcpPortEx As Long

Description

This property sets the TCP port that the LoggerNet server will use when listening for client connections and must be set before starting the LoggerNet server. LoggerNet uses TCP port 6789 by default This property accepts the full range of valid TCP port numbers 1 – 65535.

COM Return Values

Table of Possible Values

Code Meaning

14.1.2 Methods

Server.startServer()

Name

Description

COM Return Values

S_OK

Server.startServer()

This method starts the limited LoggerNet server (CORALIB3.DLL). The CORALIB3.DLL must exist in the application folder, the PATH environmental variable, or the Windows directory or this method will fail.

Table of Possible Values

Code Meaning

S_OK

E_CSI_ALREADY_STARTED

Success: Normal return

Error: This error is returned if the Server control has already started the LoggerNet server

14-4

E_CSI_INVALIDARG

E_CSI_FAIL

Error: No working directory set

Error: Another LoggerNet server not started by the Server control is already running or an unexpected error has occurred

Server.stopServer()

Name

Description

COM Return Values

Section 14. CsiServer Control Reference

Server.stopServer()

This method will stop the limited LoggerNet server (CORALIB3.DLL).

Table of Possible Values

Code Meaning

S_OK

14.1.3 Events

Server_onServerFailure()

Name

onServerFailure(String reason)

Description

This event gets triggered when the LoggerNet server started by the Server control fails.

Success: Normal return

14-5

Section 14. CsiServer Control Reference

14-6

Section 15. CsiCoraScript Control Reference

15.1 CoraScript Interface

15.1.1 Properties

CoraScript.serverConnected

Name

CoraScript.serverConnected As Boolean (read-only)

Description

This Boolean property describes the state of the connection between the CoraScript control and the LoggerNet server. The property returns TRUE if the connection exists. Otherwise, the property returns FALSE.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

CoraScript.serverLogonName

Name

CoraScript.serverLogonName As String

Valid Values

If security is enabled on the target LoggerNet server, this string must be one of the account names recognized by the LoggerNet server.

Default Value

The default value for this property is an empty string. This property will only affect the operation of the control if security is enabled on the LoggerNet server.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

E_CSI_BUSY

Error: The property cannot be set while a connection to the LoggerNet server is present

15-1

Section 15. CsiCoraScript Control Reference

CoraScript.serverLogonPassword

Name

CoraScript.serverLogonPassword As String

Valid Values

If security is enabled on the target LoggerNet server, this string must be the password associated with the account named by CoraScript.serverLogonName.

Default Value

The default value for this property is an empty string. This property will only affect the operation of the control if security is enabled on the LoggerNet server.

COM Return Values

Table of Possible Values

Code Meaning

CoraScript.serverName

Name

CoraScript.serverName As String

Description

Specifies the TCP/IP interface address for the computer hosting the LoggerNet server. This string must be formatted either as a qualified Internet machine domain name or as an Internet address string. An example of a valid machine domain name address is Internet address string is

The default value for this property is the string

COM Return Values

Table of Possible Values

S_OK

E_CSI_BUSY

Success: Normal return

Error: The property cannot be set while a connection to the LoggerNet server is present

www.campbellsci.com. An example of a valid

63.255.173.183.

Code Meaning

localhost.

15-2

S_OK

E_CSI_BUSY

Success: Normal return

Error: Attempt to set serverName while connected to the LoggerNet server

CoraScript.serverPort

Name

Description

COM Return Values

Section 15. CsiCoraScript Control Reference

CoraScript.serverPort As Long

Specifies the TCP port number that the LoggerNet server is using on the hosting computer. The valid range for this property is port 1 to port 65535.

The default value for this property is port 6789, which is the default port number assigned for the LoggerNet server. The default value for this property will connect to a LoggerNet server port in most cases.

Table of Possible Values

Code Meaning

S_OK

E_CSI_INVALIDARG

E_CSI_BUSY

15.1.2 Methods

CoraScript.executeScript()

Name

CoraScript.executeScript(String script, Long asychID) As String

Description

This method allows CoraScript commands to be executed by the LoggerNet server. Pass the CoraScript command in as the first parameter and use the second parameter to determine whether the method performs asynchronously or synchronously. If you want this command to execute synchronously, pass in a zero (0) for the asyncID. If an asyncID other than zero (0) is specified, the onScriptComplete() event will be triggered with the result and the asyncID that was specified.

COM Return Values

Success: Normal return

Error: The port value is out of range or invalid

Error: Attempt to set serverPort while connected to the LoggerNet server

Table of Possible Values

Code Meaning

S_OK

E_CSI_FAIL

Success: Normal return

Error: Unexpected Error

15-3

Section 15. CsiCoraScript Control Reference

CoraScript.serverConnect()

Name

CoraScript.serverConnect()

Description

This method attempts to connect to the LoggerNet server using the values in the previously set properties: serverName, serverPort, serverLogonName, and serverLogonPassword. This method triggers the connection is successful, or fails.

COM Return Values

Table of Possible Values

Code Meaning

onServerConnectStarted() if

onServerConnectFailure() if the connection

S_OK

E_CSI_FAIL

CoraScript.serverDisconnect()

Name

CoraScript.serverDisconnect()

Description

This method will disconnect from the LoggerNet server and will set the

serverConnected state to FALSE. This method should only be called when

the value of

E_CSI_NOT_CONNECTED.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

15.1.3 Events

Success: Normal return

Error: Unexpected error

serverConnected, is TRUE. Otherwise, this method will return

Success: Normal return

15-4

CoraScript_onScriptComplete()

Name

onScriptComplete(Long asyncID, String result)

Description

This event displays the results from the method CoraScript.executeScript(). However, this event is only activated when an asyncID other than “0” is passed to that method.

CoraScript_onServerConnectStarted()

Name

onServerConnectStarted()

Description

The control has connected to the LoggerNet server.

CoraScript_onServerConnectFailure()

Name

onServerConnectFailure(server_failure_type server_failure)

Description

An error has occurred that caused the connection to the LoggerNet server to fail for this control.

Table of Possible failure codes.

Enumeration Name Value Description

Section 15. CsiCoraScript Control Reference

server_failure_unknown 0 Indicates that an error has occurred

but its nature is unknown

server_failure_logon 1 Indicates that this control was unable

to logon to the LoggerNet server because either the logonName or logonPassword property is incorrect

server_failure_session 2 Indicates that the communication

session with the LoggerNet server failed resulting in a failed transaction

server_failure_unsupported 3 The version of the LoggerNet server

does not support this transaction

server_failure_security 4 Indicates that the account specified

by logonName does not have sufficient privileges to start this transaction with the LoggerNet server

server_failure_bad_host_or_port 5 Indicates that either the serverName

or the serverPort property is incorrect

15-5

Section 15. CsiCoraScript Control Reference

15-6

Section 16. CsiBrokerMap Control Reference

16.1 BrokerMap Interface

16.1.1 Properties

BrokerMap.serverName

Name

BrokerMap.serverName As String

Description

Specifies the TCP/IP interface address for the computer that is hosting the LoggerNet server. This string must be formatted either as a fully qualified Internet machine domain name or as an IP address string. An example of a valid machine domain name address is www.campbellsci.com. An example of a valid IP address string is

Default Value

63.255.173.183.

The default value for this property is the string

COM Return Values

Table of Possible Values

Code Meaning

S_OK

E_CSI_BUSY

BrokerMap.serverLogonName

Name

BrokerMap.serverLogonName As String

Valid Values

If security is enabled on the target LoggerNet server, this string must be an account name recognized by the LoggerNet server. These accounts can be set up using the Security Manager that is part of the LoggerNet Admin software suite or through the CsiCoraScript control.

Default Value

localhost.

Success: Normal return

Error: Attempt to set serverName while connected to the server

Notes

The default value for this property is an empty string.

This property is only used if security is enabled on the LoggerNet server.

16-1

Section 16. CsiBrokerMap Control Reference

COM Return Values

Table of Possible Values

Code Meaning

S_OK

E_CSI_BUSY

BrokerMap.serverLogonPassword

Name

BrokerMap.serverLogonPassword As String

Valid Values

If security is enabled on the target LoggerNet server, this string must be a valid password associated with the account described in the serverLogonName property.

Default Value

The default value for this property is an empty string.

Notes

This property is only used if security is enabled on the LoggerNet server.

COM Return Values

Success: Normal return

Error: Attempt to set serverLogonName while connected to the LoggerNet server

BrokerMap.serverPort

Name

Description

Default Value

Table of Possible Values

Code Meaning

S_OK

E_CSI_BUSY

Success: Normal return

Error: Attempt to set serverLogonPassword while connected to the LoggerNet server

BrokerMap.serverPort As Long

Specifies the TCP port number that the LoggerNet server is using on the hosting computer. The valid range for this property is 1 to 65535.

The default value for this property, assigned to the LoggerNet server, is 6789. In most cases, the default value for this property is acceptable.

16-2

COM Return Values

Table of Possible Values

Section 16. CsiBrokerMap Control Reference

Code Meaning

BrokerMap.autoExpand

Name

BrokerMap.autoExpand As Boolean

Description

This setting determines if the broker will automatically expand to include all brokers and tables or if the Broker.start_expansion() method must be called to list all the brokers and Table.start_expansion() method to list all tables for each broker. If the list of brokers and tables is extensive, it may be quicker to list the brokers and expand the tables for each broker separately. The default setting is true, which means that all brokers and tables will be expanded automatically.

Default Value

The default value for this property is true

S_OK

E_CSI_BUSY

E_CSI_INVALIDARG

Success: Normal return

Error: Attempt to set serverPort while connected to the LoggerNet server

Error: The port value is invalid (out of range)

COM Return Values

Table of Possible Values

Code Meaning

S_OK Success: Normal return

BrokerMap.serverConnected

Name

BrokerMap.serverConnected As Boolean

Description

This property describes the state of the connection between the BrokerMap control and the LoggerNet server. If the connection is active, the property is TRUE. Otherwise, the property is FALSE.

16-3

Section 16. CsiBrokerMap Control Reference

COM Return Values

Table of Possible Values

Code Meaning

S_OK Success: Normal Return

16.1.2 Methods

BrokerMap.Brokers()

Name

BrokerMap.Brokers() As Object

Description

Use this method to iterate through the Brokers and return a Broker Collection.

BrokerMap.finish()

Name

BrokerMap.finish()

Description

COM Return Values

BrokerMap.start()

Name

Description

This method tells the control to discontinue sending events or changes to the brokers, which holds the current broker map in a static format for your application. This method should only be called after the start() method has been invoked.

Table of Possible Values

Code Meaning

S_OK

BrokerMap.start()

This method starts the broker map query to get the brokers, tables, and columns. Immediately following the invocation of this method, the events

onBrokerAdded() and onTableAdded() will follow to describe the brokers

and tables currently in the broker map.

Success: Normal return.

16-4

If there is already a connection to the server, this method will return the error

E_CSI_ALREADY_CONNECTED. If an error occurs while trying to connect, this

method will return the error

E_CSI_BAD_HOST_OR_PORT.

COM Return Values

Table of Possible Values

Section 16. CsiBrokerMap Control Reference

Code Meaning

S_OK

E_CSI_ALREADY_CONNECTED

E_CSI_BAD_HOST_OR_PORT

16.1.3 Events

BrokerMap_onAllStarted()

Name

onAllStarted()

Description

This event is a result of invoking the after all of the initial been called from the

BrokerMap_onBrokerAdded()

Name

onBrokerAdded(Object Broker)

Success: Normal return

Error: Already connected to the LoggerNet server

Error: Cannot connect. Property serverName or serverPort possibly wrong

start() method. This event gets called onBrokerAdded() and onTableAdded() events have start() method and the broker map is known.

Description

This event gets called as new brokers are added to the broker map. Information about the new broker can be accessed with the broker object returned with this event.

BrokerMap_onBrokerDeleted()

Name

onBrokerDeleted(Object Broker)

Description

This event gets called as brokers are deleted from the broker map. Information about the broker deleted from the broker map can be accessed with the broker object returned with this event. After the broker object returned by this event goes out of scope, the referenced object in the control will be permanently deleted. The broker is kept alive for this event so that its properties can be referenced by the client application one last time.

16-5

Section 16. CsiBrokerMap Control Reference

BrokerMap_onFailure()

Name

onFailure(BrokerMapFailureType failure_code)

Description

When the BrokerMap control fails, an error from the following table will be returned with this event:

Table of Failure Codes

Name Value Description

failure_unknown

failure_connection_failed

failure_invalid_logon

failure_server_security

failure_table_browser

BrokerMap_onTableAdded()

Name

onTableAdded(Object Broker, Object Table)

0 The cause of the failure

could not be determined

1 The connection has failed.

Check the serverName and serverPort

2 The LoggerNet server has

security enabled and the logon is invalid. Check serverLogonName and serverLogonPassword

3 The LoggerNet server has

security enabled and you do not have sufficient privileges to complete this transaction

4 There has been an error

while getting table information

16-6

Description

This event gets called when a new table is added to a broker in the broker map. Information about the table added to the broker in the broker map can be accessed with the table object and broker object returned by this event.

BrokerMap_onTableDeleted()

Name

onTableDeleted(Object Broker, Object Table)

Description

This event gets called when a table is deleted from a broker in the broker map. The table that was deleted will be returned as a broker object and table object with this event.

BrokerMap_onTableChanged()

Name

onTableChanged(Object Broker, Object Table)

Description

This event executes when a Table in a Broker changes. Information about the Broker and Table that changed are returned with this event.

BrokerMap_onBrokerStarted()

Name

onBrokerStarted(Object Broker)

Section 16. CsiBrokerMap Control Reference

Description

An event that indicates a Broker is in a started state. Information about the Broker is returned with this event.

16.2 BrokerCollection Interface

16.2.1 Properties

BrokerCollection.Count

Name

BrokerCollection.Count As Long

Description

This property returns the number of brokers in the network map

COM Return Values

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

16-7

Section 16. CsiBrokerMap Control Reference

16.2.2 Methods

BrokerCollection.Item()

Name

BrokerCollection.Item(id) As Broker

Description

A Broker can be referenced by an integer, a long, or by the name of the Broker (a string). If the number is less than zero or is greater than the number of brokers minus one, then the COM error E_CSI_ARRAY_OUT_OF_BOUNDS will be returned. If the broker cannot be found by name, then the COM error E_CSI_NOT_FOUND will be returned.

COM Return Values

Table of Possible Values

Code Meaning

Visual Basic

S_OK

E_CSI_ARRAY_OUT_OF_BOUNDS

E_CSI_NOT_FOUND

E_CSI_FAIL

Return Type

Broker

Example

Referencing the broker by a number value

Dim iterator As Long For iterator = 0 to BrokerMap.Broker.Count – 1 Debug.Print BrokerMap.Brokers(iterator).ID Next iterator

Referencing the broker by name:

Dim brokerName as String Dim myid as long brokerName = "cr10x" myid = BrokerMap.Brokers(brokerName).id

Success: Normal return

Error: Array out of bounds

Error: Couldn't find the broker by name in the broker map

Error: Wrong variant type passed to this method or unexpected error

16-8

BrokerCollection._NewEnum()

Name

BrokerCollection._NewEnum() — Return the next broker in the broker map sequence.

Important

This method is only intended for use with the Visual Basic programming language. Visual Basic programmers do not need to access this method directly but can use it indirectly with the included in the documentation to explain why the method exists, but, again, it is not accessed directly.

Visual Basic

Example

Dim b As Broker For Each b in BrokerMap.Brokers Debug.print b.name Next

16.3 Broker Interface

Section 16. CsiBrokerMap Control Reference

For Each loop. This method is

16.3.1 Properties

Broker.ID

Name

Broker.id As Long

Description

This is a read-only property describing the unique ID of each broker.

COM Return Values

Table of Possible Values

Broker.name

Name

Broker.name As String

Description

This read-only property returns the name of a broker.

Code Meaning

S_OK

Success: Normal return

16-9

Section 16. CsiBrokerMap Control Reference

COM Return Values

Table of Possible Values

Code Meaning

Broker.type

Name

Description

Possible Values

S_OK

Success: Normal return.

Broker.type As BrokerType — The type of the broker (read only).

This read-only property returns the type of the broker.

Table of Broker Type Enumeration

Name Value Description

broker_active

1 The data broker associated with the

current configuration of a device object

broker_backup

2 A data broker associated with a

previous configuration of a device object

broker_client

3 A data broker created at the request

of a client

COM Return Values

Table of Possible Values

Broker.datalogger_type

Name

Broker.datalogger_type As String

Description

The read-only device type of the Broker

broker_statistics

Code Meaning

S_OK

Success: Normal return

4 A data broker created by the

LoggerNet server to report operating statistics

16-10

COM Return Values

Broker.allStarted

Name

Description

COM Return Values

Section 16. CsiBrokerMap Control Reference

Table of Possible Values

Code Meaning

S_OK Success: Normal return

Broker.allStarted As Boolean

Set to TRUE when all the tables for the broker have been reported.

Table of Possible Values

Code Meaning

S_OK Success: Normal return

16.3.2 Methods

Broker.Tables()

Name

Broker.Tables() As Object

Description

This method returns a reference to a TableCollection, which can be used to iterate through the tables in a broker.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

Broker.start_expansion()

Name

Broker.start_expansion()

Success: Normal return

Description

If the BrokerMap autoExpand property has been set to FALSE, use this method to access the list of tables for a Broker.

16-11

Section 16. CsiBrokerMap Control Reference

COM Return Values

Table of Possible Values

Code Meaning

S_OK Success: Normal Return

16.4 TableCollection Interface

16.4.1 Properties

TableCollection.Count

Name

TableCollection.Count As Long

Description

This property returns the number of tables in a TableCollection

COM Return Values

16.4.2 Methods

TableCollection.Item()

Name

Description

Prototypes

Table of Possible Values

Code Meaning

S_OK

TableCollection.Item(id) As Table

Returns the requested table if it exists. A table can be referenced by a number (like an index), or by a string (the name of the table). If the number is less than zero or is greater than the number of tables, then the error

E_CSI_ARRAY_OUT_OF_BOUNDS will be returned. If the table cannot be found

by name, then the error

TableCollection.Item(Number) - Array index. TableCollection.Item(String) - Table name.

Success: Normal return

E_CSI_NOT_FOUND will be returned.

16-12

COM Return Values

Table of Possible Values

Section 16. CsiBrokerMap Control Reference

Code Meaning

Visual Basic

S_OK

E_CSI_ARRAY_OUT_OF_BOUNDS

E_CSI_NOT_FOUND

Success: Normal return

Error: Array subscript out of bounds

Error: Table not found by name in the broker map

E_CSI_FAIL

Error: Wrong variant type passed or unexpected error

Return Type

Table

Example

By number:

long iterator For iterator = 0 to BrokerMap.Broker("cr9000").Tables.Count – 1 Debug.Print BrokerMap.Brokers("cr9000").Tables.ID Next iterator

By string:

Dim tableName as String Dim myid as long tableName = "cr10x" myid = BrokerMap.Broker("cr9000").Tables(tableName).id

TableCollection._NewEnum()

Name

TableCollection._NewEnum() — Return the next Table in the sequence.

Important

This method is only intended for use with Visual Basic. Visual Basic programmers do not need to access this method directly. They use it indirectly by using the collections with the

loop. This method is included in the documentation to

Each

explain why the method exists, but, again, it is not accessed directly.

For

16-13

Section 16. CsiBrokerMap Control Reference

16.5 Table Interface

16.5.1 Properties

Table.interval

Name

Table.interval As Long

Description

The time interval between records. If the table is event-driven, a value of zero will be used.

COM Return Values

Table of Possible Values

Code Meaning

Table.name

Name

Description

COM Return Values

Table.originalSize

Name

S_OK

Table.name As String

This read-only property returns the name of the table.

Table of Possible Values

Code Meaning

S_OK

Table.originalSize As Long

Success: Normal return

16-14

Description

This property returns the number of records that can be stored in the original datalogger table.

COM Return Values

Table of Possible Values

Section 16. CsiBrokerMap Control Reference

Code Meaning

Table.size

Name

Description

COM Return Values

16.5.2 Methods

Table.Columns()

Name

S_OK

Table.size As Long

This property returns the number of records that can be stored in this table.

Table of Possible Values

Code Meaning

S_OK

Table.Columns() As Object

Success: Normal return

Description

This method is used as a reference for a ColumnCollection to get the columns of a table.

COM Return Values

Table of Possible Values

Visual Basic

Example

Dim cc As ColumnCollection Set cc = BrokerMap.Brokers("cr9000").Tables("public").Columns

Code Meaning

S_OK

Success: Normal return

16-15

Section 16. CsiBrokerMap Control Reference

Table.start_expansion

Name

Table.start_expansion()

Description

If the BrokerMap autoExpand property has been set to FALSE, use this method to access the list of Columns for a Table within a Broker.

COM Return Values

Table of Possible Values

Code Meaning

S_OK Success: Normal Return

16.6 ColumnCollection Interface

16.6.1 Properties

ColumnCollection.Count

Name

ColumnCollection.Count As Long

Description

This property returns the number of columns in the ColumnCollection.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

16.6.2 Methods

ColumnCollection.Item()

Name

ColumnCollection.Item(id) As Column

Description

Success: Normal return

16-16

This method returns the reference id for a Column. If the number is less than zero or is greater than the number of columns, then the error E_CSI_ARRAY_OUT_OF_BOUNDS will be returned. If the column cannot be found by name, then the error

E_CSI_NOT_FOUND will be returned.

Prototypes

ColumnCollection.Item(Number) - Array index. ColumnCollection.Item(String) - Table name.

COM Return Values

Table of Possible Values

Visual Basic

Return Type

Column

Section 16. CsiBrokerMap Control Reference

Code Meaning

S_OK

E_CSI_ARRAY_OUT_OF_BOUNDS

E_CSI_NOT_FOUND

Success: Normal return

Error: Array out of bounds

Error: Column not found in broker map by name

E_CSI_FAIL

Error: Wrong variant type passed or unexpected error

Examples

(1) Dim myColumn as Column BrokerMap.Brokers("cr9000").Tables("public").Columns.Item(0)

(2) Dim myColumn as Column BrokerMap.Brokers("cr9000").Tables("public").Columns(0)

(3) Dim myColumn as Column BrokerMap.Brokers("cr9000").Tables("public").Columns.Item("speed")

(4) Dim myColumn as Column BrokerMap.Brokers("cr9000").Tables("public").Columns("speed")

Examples (1) and (2) are equivalent, as well as examples (3) and (4). The default method for collection interfaces is Item().

ColumnCollection._NewEnum()

Name

ColumnCollection._NewEnum() — Return the next Column in the sequence.

Important

This method is only intended for use with Visual Basic. Visual Basic programmers do not need to access this method directly. They use it indirectly by using the collections with the

Each loop. This method is included in the documentation to

For

explain why the method exists, but, again, there is no need to access this method directly.

16-17

Section 16. CsiBrokerMap Control Reference

16.7 Column Interface

16.7.1 Properties

Column.description

Name

Column.description As String

Description

This read-only property returns a description of the column.

COM Return Values

Table of Possible Values

Code Meaning

Column.name

Name

Description

COM Return Values

Column.process

Name

Description

S_OK

Column.name As String

This read-only property returns the name of the column.

Table of Possible Values

Code Meaning

S_OK

Column.process As String

Success: Normal return

16-18

A read-only property that identifies the processing performed on the data. For data coming from table-data and mixed-array dataloggers, this value will be an empty string.

COM Return Values

Table of Possible Values

Section 16. CsiBrokerMap Control Reference

Code Meaning

Column.type

Name

Description

S_OK

Success: Normal return

Column.type As CsiDataTypeCode

This read-only property identifies the type of data for the column.Following are the possible values for this enumerated property:

Table of Data Type Enumeration

Name Value Description

dt_CsiUInt1

dt_CsiUInt2

dt_CsiUInt4

dt_CsiInt1

dt_CsiInt2

dt_CsiInt4

1 1 byte unsigned int

2 2 byte unsigned int

3 4 byte unsigned int

4 1 byte signed int

5 2 byte signed int

6 4 byte signed int

dt_CsiInt8

dt_CsiFs2

dt_CsiFs3

dt_CsiFs4

dt_CsiFsf

dt_CsiFp4

dt_CsiIeee4

dt_CsiIeee8

dt_CsiBool

dt_CsiBool8

dt_CsiSec

dt_CsiUSec

dt_CsiNSec

32 8 byte signed integer

7 2 byte final storage (also known as FP2)

15 3 byte final storage (also known as FP3)

26 4 byte final storage

27 allows storage of either CsiFs2 or CsiFs4.

Requires 4 bytes

8 4 byte CSI float

9 4 byte IEEE float

18 8 byte IEEE float

10 1 byte Boolean (0 or 1)

17 1 byte bit field

12 4 byte sec since 1 Jan 1990

13 6 byte 10s of Usec since 1 Jan 1990

14 4 byte sec since 1 Jan 1990 + 4 byte Nsec

16-19

Section 16. CsiBrokerMap Control Reference

Name Value Description

dt_CsiAscii

dt_CsiAsciiZ

dt_CsiInt4Lsf

dt_CsiUInt2Lsf

dt_CsiUInt4Lsf

dt_CsiNSecLsf

dt_CsiIeee4Lsf

dt_CsiIeee8Lsf

dt_CsiInt8Lsf

dt_CsiBool2

dt_CsiBool4

dt_CsiInt2Lsf

dt_CsiLgrDate

dt_CsiLgrDateLsf

11 fixed-length string

16 null-terminated variable-length string

20 4 byte signed int (LSB first)

21 2 byte signed int (LSB first)

22 4 byte signed int (LSB first)

23 same as NSec with the components in LSB

24 4 byte IEEE float (LSB first)

25 8 byte IEEE float (LSB first)

33 8 byte signed integer (LSB first)

30 2 byte Boolean (non-zero = true)

31 4 byte Boolean (non-zero = true)

19 2 byte signed int (LSB first)

29 8 bytes of nanoseconds since 1990

28 8 bytes of nanoseconds since 1990 (LSB

first)

COM Return Values

Column.units

Name

Description

COM Return Values

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

Column.units As String

This read-only property identifies the data engineering units.

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

16-20

Column.writable

Name

Description

COM Return Values

Section 16. CsiBrokerMap Control Reference

Column.writable As Long

This property is read-only and describes whether or not this column can be changed or set by using the variableSet() method as described in the CsiDatalogger Control.

Table of Possible Values

Code Meaning

S_OK

Success: Normal return

16-21

Section 16. CsiBrokerMap Control Reference

16-22

Section 17. CsiDatalogger Control Reference

17.1 Datalogger Interface

17.1.1 Properties

Datalogger.clockBusy

Name

Datalogger.clockBusy As Boolean

Description

This property describes the state of the control concerning clock transactions. If a clock check or a clock set is currently executing, clockBusy returns TRUE, and any attempt to execute another clock check or clock set will return an error.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

Datalogger.loggerConnected

Name

Datalogger.loggerConnected As Boolean

Description

This Boolean property describes the state of the LoggerNet server connection management invoked from loggerConnectStart(). This property only describes the state of connection management not the state of the physical connection to the datalogger. To monitor the physical line state, start an advisor with the DataSource control and monitor the statistics table for that device. For information on devices statistics tables, look in the appendix of this document.

If connection management is active, then a persistent connection between the server and the datalogger is present or in process. This type of connection can be very useful if you must make requests to the datalogger on a frequent basis because you avoid reconnection overhead for each request. To turn off active connection management, see loggerConnectCancel.

COM Return Values

Table of Possible Values

Code Meaning

Success: Normal return

S_OK

Success: Normal return

17-1

Section 17. CsiDatalogger Control Reference

Datalogger.loggerName

Name

Datalogger.loggerName As String

Valid Values

Specifies the datalogger or station name that will be accessed. This property must match one of the actual datalogger device names in the LoggerNet server network map.

Default Value

The default value for this property is an empty string.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

E_CSI_BUSY

Datalogger.manualPollBusy

Name

Datalogger.manualPollBusy As Boolean

Description

This Boolean property describes the state of the control concerning a manual poll. If a manual poll is currently executing then manualPollBusy will return TRUE, and any attempt to execute another manual poll will return an error.

COM Return Values

Table of Possible Values

Code Meaning

S_OK

Datalogger.programReceiveBusy

Success: Normal return

Error: The property cannot be set while a connection to the datalogger is present

Success: Normal return

17-2

Name

Datalogger.programReceiveBusy As Boolean

Description

This read-only, Boolean property describes the state of the LoggerNet server in relation to the method programReceiveStart(). If the LoggerNet server is currently retrieving a program from the datalogger, then this property will return TRUE.

Campbell Scientific LoggerNet Server SDK User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Campbell Scientific, Inc. Software SDK End User License Agreement (EULA)

Section 1. LoggerNet Server SDK Overview

1.1 Purpose of the LoggerNet Server SDK

1.2 Requirements

1.2.1 Required Campbell Scientific, Inc. Software

1.2.2 Development Tools Requirements

1.3 Included Components

1.3.1 Files Included in the LoggerNet Server SDK

1.3.1.1 ActiveX® Controls (DLLs)

1.3.1.2 LoggerNet Server (CORALIB3.DLL)

1.3.1.3 Manuals

1.3.1.4 Example Projects

1.3.2 Adding Controls to a Project

1.3.2.1 Adding a Control to a Visual Basic Project

1.3.2.2 Adding a Control to a Delphi Project

1.3.2.3 Adding a Control to a .NET Project

Section 2. CsiServer Control

2.1 Purpose of the CsiServer Control

2.2 CsiServer Interface

2.2.1 Properties

2.2.2 Methods

2.2.3 Events

Section 3. Developing an Application Using the CsiServer Control

3.1 Purpose

3.2 Using the CsiServer Control

3.2.1 Getting Started with the CsiServer Control

3.2.2 CsiServer Control Application Example

Section 4. CsiCoraScript Control

4.1 Purpose of the CsiCoraScript Control

4.2 Connecting to the Server

4.3 Using CoraScript Commands

4.3.1 Setting up a Network

4.3.2 Real-Time Data Display

4.3.2.1 Table-Data Dataloggers

4.3.2.2 Mixed-Array Dataloggers

4.4 CsiCoraScript Interface

4.4.1 Properties

4.4.2 Methods

4.4.3 Events

Section 5. Developing an Application Using the CsiCoraScript Control

5.1 Purpose

5.2 Using the CsiCoraScript Control

5.2.1 Getting Started with the CsiCoraScript Control

5.2.2 CsiCoraScript Control Application Example

Section 6. CsiBrokerMap Control

6.1 Purpose of the CsiBrokerMap Control

6.2 Connecting to the LoggerNet Server

6.3 How Collections Work

6.3.1 Visual Basic View of Collections

6.3.1.1 Accessing Collections with For Each

6.3.1.2 Accessing Collections with Indexes and Names

6.3.2 Delphi/Visual C++ View of Collections

6.4 CsiBrokerMap Interfaces

6.4.1 BrokerMap Interface

6.4.1.1 Properties

6.4.1.2 Methods

6.4.1.3 Events

6.4.2 BrokerCollection Interface

6.4.2.1 Properties

6.4.2.2 Methods

6.4.3 Broker Interface

6.4.3.1 Properties

6.4.3.2 Methods

6.4.4 Table Collection Interface

6.4.4.1 Properties

6.4.4.2 Methods

6.4.5 Table Interface

6.4.5.1 Properties

6.4.5.2 Methods

6.4.6 ColumnCollection Interface

6.4.6.1 Properties

6.4.6.2 Methods

6.4.7 Column Interface

6.4.7.1 Properties

Section 7. Developing an Application Using the CsiBrokerMap Control

7.1 Purpose