@aGlance/IT for Excel



User's Guide

@aGlance/IT for Microsoft Excel

INTUITIVE TECHNOLOGY CORPORATION

The information in this document is subject to change without notice and should not be construed as a commitment by Intuitive Technology Corporation.

The software described in this document is furnished under a license agreement, and may be used or copied only in accordance with the terms of that license agreement.

Portions of this product incorporate technology licensed from Digital Equipment Corporation.

No part of this manual may be reproduced or transmitted in any form or by any means for any purpose other than the purchaser's personal use, without the express written permission of Intuitive Technology Corporation.

Intuitive Technology Corporation 1993 - 1996. All Rights Reserved.

Intuitive Technology, the Intuitive Technology logo, and @aGlance/IT are trademarks of Intuitive Technology Corporation.

Document Number AAG030-003a-96

CONTENTS

Preface v

CHAPTER 1 Introduction 1

Useful Concepts 3

CHAPTER 2 Using the Menu Interface 7

CHAPTER 3 Using the Macro Tool 11

CHAPTER 4 Using the Macro Interface 15

Specifying AAG Macro Arguments 16

AAG GetTags 18

AAG GetAttributes 20

AAG Get 23

AAG Put 26

AAG GetHistory 29

AAG GetHistEvent 33

AAG GetHistStats 37

AAG PutHistory 41

AAG Command 44

AAG Disconnect 46

CHAPTER 5 Error Handling 47

Error Types 47

Error Messages 50

Index 55

Preface

Intended Audience

This manual describes how to use the @aGlance/IT Add-in for Microsoft Excel, both Windows and Macintosh versions. It is intended for spreadsheet users who are familiar with Excel.

Conventions

[Square brackets] are used to denote optional parameters in macro calls.

A monospaced font is used in sample program dialogs.

Chapter one

Introduction

1 Introduction"Intuitive Technology provides great flexibility in accessing the @aGlance/IT client functions from desktop applications. Virtually all of these methods are available to the Excel user.

Beginning with Version 1, @aGlance/IT products have catered to the casual, ad hoc use of spreadsheets with the Macro Tools that are a part of both the Excel and the 1-2-3 Addins. More recently, a browser capability was added to the @aGlance/IT for Excel product. The Macro Tool and the Browser are described in this manual.

Beginning in Release 3.1 of the Standard and Professional Editions for Windows, an @aGlance/IT Wizard for Excel simplifies the process of retrieving and analyzing process data. The Wizard is extremely simple to use, and has extensive online help.

@aGlance/IT Version 1 was released at about the same time as Excel Version 4. Users with complex applications that required spreadsheet programming coded in Excel macro language. The @aGlance/IT Macro Interface, described in this manual, enables Excel macro programmers to utilize the @aGlance/IT client functions. The Macro Tool can be used by the programmer to construct @aGlance/IT macro calls.

Excel has long supported dynamic data exchange (DDE) for exchanging data with other Windows applications. Since @aGlance/IT Version 2, the DDE Bridge, described in the @aGlance/IT for MS Windows User’s Guide, has provided an interface to the client functions for DDE client-enabled applications. Writing Excel macro programs which utilize DDE is generally more complex than using the @aGlance/IT Macro Interface. However, DDE is invaluable if your program needs automatic updates when values change in the process data source.

Excel Version 5 introduced Visual Basic for Applications, described as an Object Oriented macro language. Microsoft supports the use of Excel macro language “subroutines” in VBA, so the Macro Interface is callable from VBA programs. In addition, Intuitive Technology introduced NetOLE in @aGlance/IT Version 3, enabling the VBA programmer to call @aGlance/IT client functions using OLE Automation. NetOLE, a part of the Professional Edition, is documented in online help that is a part of the Professional Edition.

Useful Concepts

Useful ConceptsBefore proceeding with a more detailed discussion of @aGlance, it is necessary to understand the idea of spreadsheet ranges and of the difference between a list and a table of @aGlance/IT data. These terms are explained below.

Ranges

Rectangular groups of spreadsheet cells are known as ranges. @aGlance/IT functions read and write tags, attributes and data values from and to spreadsheet ranges selected by the user.

Range Size and Shape

Size and shape refer to two characteristics of a spreadsheet range.

The size of a range is the number of cells in the range.

The shape of a range is one of the following:

Cell - A single spreadsheet cell.

Row - Two or more cells arranged in a horizontal row.

Column - Two or more cells arranged in a vertical column.

Matrix - Four or more cells arranged in a two dimensional rectangle.

The size and shape requirements of the different ranges used in @aGlance/IT macro calls are often interrelated, as shown in the list and table examples below.

Lists and Tables

Many of the @aGlance/IT functions read and write data values that are identified by their tag and attribute names. These data values and their tag and attribute names are organized either as a list or a table.

[pic]

The diagram above shows @aGlance/IT data values arranged in a list. The ranges that comprise a list can be cells, columns or rows, but all four ranges (Tag, Attribute, Data and Status) must be the same size and shape. Thus for each tag name, there is one (optional) attribute name, one data value and one (optional) status value. Although the elements comprising a list are shown arranged contiguously, this is not a requirement.

Note that any request that doesn't include the optional AttributeRange argument is a list request.

[pic]

This diagram shows @aGlance/IT data values arranged in a table. Tag and Attribute names must be contained in either a row or a column. The TagRange runs in one direction (in this example, a column) and the AttributeRange runs at right angles to the TagRange (in this example, a row). The size and shape of the DataRange is dictated by the TagRange and AttributeRange. The axis of the DataRange that runs parallel to the TagRange must be the same size as the TagRange and the axis of the DataRange that runs parallel to the AttributeRange must be the same size as the AttributeRange. The optional StatusRange, if specified, must be the same size and shape as the DataRange. Although the elements comprising a table are shown arranged contiguously, this is not a requirement.

Chapter two

Using the Menu Interface

2 Using the Menu Interface"The @aGlance/IT menu is available once the @aGlance/IT installation is complete. It provides a simplified interface for specifying server names and browsing current and historical data values from @aGlance/IT servers.

The "@aGlance/IT" menu item appears in the main Excel menu whenever a worksheet or macro sheet is open and visible. Clicking on the this menu item presents the following options in a pull-down menu:

Edit Server List...

Browse Data...

Browse History...

Macro Tool...

Utility Options...

Help

About...

Edit Server List...

The Edit Server List item presents you with a dialog box that allows your to add, delete and select server names on a list of servers that can be used for the Browse Data and Browse History menu items. This is simply a list keeper that provides an easy way of storing and selecting server names.

Use Edit Server List to select a server before invoking the Browse Data or Browse History items.

A maximum of 20 server names can be added to the list. The servers that are to be browsed should support the GetTags, GetAttributes, Get and GetHistory methods.

Browse Data...

Before invoking Browse Data, you should choose a server from the server list and select an appropriately sized macro sheet or worksheet range by clicking and dragging. This range must contain a minimum of two rows and two columns.

The Browse Data item allows you to browse current data values from the selected server. Using the currently selected sheet range, Browse Data places a set of tag names in the leftmost column, a set of attribute names in the uppermost row and then fills in the resulting table with current data values from the server.

A Browse Data dialog box then appears that allows you to:

- Check the number of tag and attribute matches

- Scroll tags up and down

- Scroll attributes left and right

- Refetch the current data values

- Specify tag and attribute filters

- Select different servers

- Ask for Help

You also have the option to provide your own set of tags (in the left column) and/or attributes (in the top row) in the pre-selected range. If Browse Data finds names in the tag column or attribute row, it uses these tags and/or attributes. User supplied tags and attributes cannot be filtered or scrolled.

The servers to be browsed must support the GetTags, GetAttributes and Get methods. A maximum of 200 tags and 200 attributes can be scrolled.

Browse History...

Before invoking Browse History, you should choose a server from the server list and select an appropriately sized macro sheet or worksheet range by clicking and dragging. This range must contain a minimum of three rows and two columns.

The Browse History item allows you to browse historical data values from the selected server. Using the currently selected sheet range, Browse History places a set of tag names in the uppermost row, a set of attribute names in the second row and then fills the remainder of the selection with historical data values and associated times from the current server.

A Browse History dialog box then appears that allows you to:

- Check the number of tag and attribute matches

- Scroll tags left and right

- Scroll attributes left and right

- Refetch the historical data values

- Specify tag and attribute filters

- Specify start and interval times

- Select different servers

- Ask for Help

You also have the option to provide your own set of tags (in the top row) and/or attributes (in the second row) in the preselected range. If Browse History finds names in the tag or attribute row, it uses these tags and/or attributes. User supplied tags and attributes cannot be filtered or scrolled.

The servers to be browsed must support the GetTags, GetAttributes and GetHistory methods. A maximum of 200 tags and 200 attributes can be scrolled.

NOTE - the Start and Interval time edit boxes used in the Browse History dialog box are text edit boxes and do not require that you enclose numeric time fields in quotes as you must do when specifying time arguments in the Macro Tool dialog box.

Macro Tool...

The Macro Tool item invokes the @aGlance/IT Macro Tool dialog box, just as clicking on the @aGlance/IT tool does.

Utility Options...

The Utility Options item invokes the @aGlance/IT Utilities dialog box, and presents two options:

[pic]

Open Demo Sheets

Selecting this option opens the AAGDEMO.XLS and AAGDEMO.XLM sheets. On screen instructions can then be followed to proceed with an @aGlance/IT demonstration.

Add AAG Toolbar

Selecting this option creates an AAG toolbar (if none exists) and places the AAG tool face on it. Clicking on the AAG tool face provides a convenient way of invoking the @aGlance/IT Macro Tool.

Typically, adding this toolbar and tool face is done only at installation time. If multiple copies of the AAG tool face are created by mistake, they can be removed by using the Excel Options/Toolbars/Customize menu option.

Help

The Help item invokes the @aGlance/IT Help facility.

About...

The About item displays a dialog box that provides information on the current version of @aGlance/IT.

Chapter three

Using the Macro Tool

3 Using the Macro Tool"The @aGlance/IT Macro Tool provides an easy to use, interactive interface to the AAG macro. Writing macro calls by hand can be tedious and it's easy to forget the number and placement of arguments. The Macro Tool is provided to help with the task of constructing and testing these macro calls.

The Macro Tool is a dialog box that provides these features:

- Invoked via tool bar or menu

- Lists all AAG functions

- Prompts for all arguments for the chosen function

- Indicates whether arguments are optional or required

- Allows use of the mouse or keyboard for filling in arguments

- Execution of the AAG macro under construction for testing or ad hoc data access

- Allows the constructed macro to be saved in an Excel macro sheet for later use

Invoking the Macro Tool

@aGlance/IT includes an AAG tool button that is available on an Excel toolbar once the @aGlance/IT installation is completed. The Macro Tool can be invoked by clicking on this AAG tool button, shown below.

[pic]

In addition, @aGlance/IT includes an @aGlance/IT menu item. By clicking on this menu item and then selecting the Macro Tool... item, the Macro Tool can be invoked.

Using the Macro Tool

When you invoke the @aGlance/IT Macro Tool, the dialog box shown below is displayed.

[pic]

The AAG function field defaults to "GetTags". To select a different function, click on the AAG Function input field to display a drop-down list box containing all of the @aGlance/IT functions:

GetTags

GetAttributes

Get

Put

GetHistory

GetHistEvent

GetHistStats

PutHistory

Command

Disconnect

Note that the dialog box shown above contains an input field for the each of the four arguments used in a GetTags macro call. Once an AAG function is selected, the Macro Tool dialog box automatically redisplays with the required argument input fields.

The square brackets ([]) around the MatchString and StartIndex labels indicate that they are optional arguments. Their default values are displayed in their input fields.

The Macro Tool dialog box shown above has the following four buttons at the bottom:

Try-It

Clicking on the Try-It button executes the AAG call that has been constructed.

Paste-It

Clicking on the Paste-It button causes the current AAG macro to be written to the location specified in the Paste-It Cell input field at the bottom of the Macro Tool dialog box. The Paste-It Cell must be specified on a macro sheet, not on a worksheet. An attempt to paste to a worksheet or an invalid location causes an Alert box with the message "Not a Valid Paste Location" to be displayed. Once an AAG macro has been pasted to a macro sheet, it can later be invoked by using standard Excel operations such as the Excel macro menu pull-down or the Excel macro toolbar.

Help

Clicking on the Help button invokes Help for the @aGlance/IT Excel add-in.

Close

Clicking on the Close button causes the Macro Tool to exit.

Macro Tool Behavior

The Macro Tool dialog box can be moved by pointing to the dialog box header and clicking and dragging the box to the desired location on the screen. Macro Tool dialog boxes are dynamically sized - the dialog box used for a GetHistory function is larger than that used for a GetTags function because it uses a larger number of input arguments, each of which requires its own input field.

The ServerName argument is a required argument for each AAG function. Once it has been specified for any AAG function, its value is "sticky", meaning that it will automatically be filled in for all subsequent AAG functions. The dialog box will also automatically fill in the latest values for TagRange and AttributeRange after successful invocations of the GetTags and GetAttributes functions.

The input fields for the AAG arguments and for the Paste-It Cell are Excel formula edit boxes. To enter a value in such a box, make sure that the box has input focus - that is, the cursor must be displayed in the box. Once input focus is established, you can enter values directly into the edit box or you can use the mouse to select a range of cells on an exposed sheet. If you select a cell range, Excel will enter an absolute range value into the formula edit box.

Once Excel processes a value in a formula edit box, it adds an equal sign (=) to the front of the value or range specification. This equal sign is a byproduct of using an Excel formula edit box and does not appear in the argument that is used in the AAG macro.

When you enter text in a formula edit box, Excel encloses it in double quotes and precedes it with an equal sign when it evaluates it. However, a problem can arise if this text can be interpreted as a name or number by Excel. In this case, your text field will not be interpreted properly. To avoid this problem, you should place the text value in double quotes and precede it with an equal sign, preventing Excel from evaluating it incorrectly. An example of this would occur if you wish to enter a string value of 12:00 in the StartTime field of a GetHistory function - unless you enter it as ="12:00", Excel will interpret it as an Excel time value and the GetHistory function will fail with an error.

Chapter four

Using the Macro Interface

4 Using the Macro Interface"The @aGlance/IT client add-in is implemented as an Excel macro named AAG. The AAG macro allows you to get the names of tags and attributes available in an @aGlance/IT server and to read and write both current and historical data values.

The AAG macro is invoked from an Excel macro sheet (not from a worksheet). To invoke it, a formula that calls the AAG macro is placed in a macro sheet cell and that cell is then executed.

The general syntax of an @aGlance/IT AAG macro call is:

=AAG("Function", ServerName, argument1, argument2...)

The first two arguments of an AAG macro are the name of the @aGlance/IT function being requested and the name of the target server. The remaining arguments are function-specific. Arguments shown in square brackets are optional and may be left blank.

An AAG macro call can be placed in an Excel macro sheet cell by hand-editing the cell or by using the Macro Tool to construct the AAG call, test it and paste it to a cell. Once the AAG macro call is placed in a cell, it can be invoked by using any of the normal Excel mechanisms for running a macro (for example, by using the macro menu option or the macro tool bar).

The AAG macro returns the Excel value TRUE if it executes successfully. If an error is encountered, an Alert dialog box with an error message is displayed and the Excel error value #N/A is returned. These return values are placed in the macro sheet cell from which the AAG macro was invoked.

Specifying AAG Macro Arguments

Specifying AAG Macro ArgumentsAAG arguments are specified in two ways:

In an edit box when the Macro Tool is being used

Directly in a cell when an AAG macro is being hand-edited

AAG macro arguments are required to resolve to either a range, a string or an integer. "Resolve" refers to Excel's ability to accept a cell or range specification for an argument that requires an integer or a string and then to look in that cell or range to retrieve the actual argument value. If a cell range is specified for an argument that requires a single value (e.g., a string or integer argument), then the contents of the cell in the upper left corner of the specified range is used as the argument.

Excel will accept a name instead of a range or cell specification. Such a name must be pre-defined to Excel as referring to a cell or range.

Absolute references in Excel include dollar signs preceding both the column letter and the row number (e.g., $A$1). Relative references in Excel do not include dollar signs (e.g., A1). Absolute references tend to be more useful when working with the AAG macro, and this is the type of reference generated by the Macro Tool. However, these references are harder to read because of the added dollar signs and for that reason, relative references are used in this document to make the examples more readable.

Range arguments for the AAG macro can be specified as Excel ranges (e.g., A1:A5) or as named ranges (e.g., tags). When using the Macro Tool, the mouse can be used to point, click and drag to select a range.

Integer arguments for the AAG macro can be specified as an integer (e.g., 3) or as an Excel cell (e.g., A1) that contains an integer or as a named cell that contains an integer. When using the Macro Tool, the mouse can be used to point and click to select a cell containing an integer.

String arguments for the AAG macro can be specified as a string (e.g., "Server1") or as an Excel cell (e.g., A1) that contains a string or as a named cell that contains a string. When using the Macro Tool, the mouse can be used to point and click to select a cell containing the string. If you are specifying a string that begins with a numeric character, Excel attempts to interpret it as a number unless you quote it - this is often a problem when specifying Time arguments that are required to be strings. See the Macro Tool Behavior section in Chapter 4 for further information on entering strings in the Macro Tool edit boxes.

AAG GetTags

AAG GetTagsThe AAG GetTags macro is a directory service that requests that the server provide a set of tag names known to it. Tag names returned from the server are written to the OutputRange.

The optional MatchString argument requests that only tag names that match the supplied pattern be returned. This argument defaults to an asterisk, requesting that no tags be filtered out. The optional StartIndex argument allows successive GetTags requests to display a set of tag names in an OutputRange that is too small to contain them all at once. This argument defaults to a zero, indicating that the server should not skip over any matching names when selecting tags to return. The index value returned by the server is written to the first cell of the OutputRange and the tag names start in the second cell.

Syntax

=AAG("GetTags", ServerName, [MatchString], [StartIndex], OutputRange)

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

MatchString

MatchString is an optional argument that if specified must resolve to a text string. MatchString provides a template for selecting the tag names to be returned by the server. The wild card characters * (match any) and ? (match single character) can be included in the MatchString. Thus the MatchString "*valve?" would match any tag name that ended with the characters "valve" followed by any single character.

If not specified, MatchString defaults to "*" and all tag names are matched.

StartIndex

StartIndex is an optional argument that if specified must resolve to an integer. It is meant to contain a server-supplied value that is used by the server as a place holder when successive requests are made to a server. By using the index returned from the server on a previous GetTags request as the StartIndex on successive GetTags requests, a set of tag names can be displayed in an OutputRange that is too small to contain them all at once.

If not specified, StartIndex defaults to zero indicating that the server should return the requested tag names starting at the beginning of its database and not skip any matching entries.

OutputRange

OutputRange is a required argument that must resolve to a range. The index value returned from the server is placed in the first cell and tag names are written in the remainder of the range. If the server does not return enough tag names to fill the OutputRange, the Excel error value #N/A is placed in the trailing cells. A non-zero index value indicates that the server has further matching names that can be retrieved.

.

Example

=AAG("GetTags", "North Plant", "*01", 0, A1:A5)

The figure below shows the results of executing this macro. The server named North Plant is asked to provide a list of all tags that end in the characters "01" and to place them in OutputRange A1:A5 on the current sheet. The zero in the StartIndex argument requests that no matches be discarded. The zero returned in A1 - the first cell of the OutputRange - indicates that all matching tags have been returned. The four matching tag names are placed in cells A2:A5 of the OutputRange.

[pic]

AAG GetAttributes

AAG GetAttributesThe AAG GetAttributes macro is a directory service that requests that the server provide a set of attribute names known to it and associated with the tags in TagRange. If more than one tag name is specified, the attributes returned represent the union of attributes for those tags (i.e., all attributes for all supplied tags). Attribute names returned from the server are written to the OutputRange.

The optional MatchString argument requests that only attribute names that match the supplied pattern be returned. This argument defaults to an asterisk, requesting that no attributes be filtered out. The optional StartIndex argument allows successive GetAttributes requests to display a set of attribute names in an OutputRange that is too small to contain them all at once. This argument defaults to a zero, indicating that the server should not skip over any matching names when selecting attributes to return. The index value returned by the server is written to the first cell of the OutputRange and the attribute names start in the second cell.

Syntax

=AAG("GetAttributes", ServerName, TagRange, [MatchString], [StartIndex], OutputRange)

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names whose attributes are being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

MatchString

MatchString is an optional argument that if specified must resolve to a text string. MatchString provides a template for selecting the attribute names for the data values being requested from the server. The wild card characters * (match any) and ? (match single character) can be included in the MatchString. Thus the MatchString "*APV?" would match any attribute name that ended with the characters "APV" followed by any single character.

If not specified, MatchString defaults to "*" and all attribute names are matched.

StartIndex

StartIndex is an optional argument that if specified must resolve to an integer. It is meant to contain a server-supplied value that is used by the server as a place holder when successive requests are made to a server. By using the index returned from the server on a previous GetAttributes request as the StartIndex on successive GetAttributes requests, a set of attribute names can be displayed in an OutputRange that is too small to contain them all at once.

If not specified, StartIndex defaults to zero indicating that the server should return the requested attribute names starting at the beginning of its database and not skip any matching entries.

OutputRange

OutputRange is a required argument that must resolve to a range. The index value returned from the server is placed in the first cell and attribute names are written in the remainder of the range. If the server does not return enough attribute names to fill the OutputRange, the Excel error value #N/A is placed in the trailing cells. A non-zero index value indicates that the server has further matching names that can be retrieved.

Example

=AAG("GetAttributes", "North Plant", A2:A5, , , A1:D1)

The figure below shows the results of executing this macro. The server named North Plant is asked to provide a list of all attributes for the tags in the TagRange A2:A5. The MatchString argument is omitted so it defaults to an asterisk, indicating that no attributes are to be filtered out. The StartIndex argument is also omitted, so it defaults to zero, indicating that the server should return attributes starting with the first match. The index value of 3 has been returned from the server and placed in A1 - the first cell of the OutputRange. This non-zero value indicates that the server has other matching attribute names that can be retrieved by passing this value as the StartIndex argument in another GetAttributes request. The three attribute names returned by the server are placed in the OutputRange cells B1:D1.

[pic]

AAG Get

AAG GetThe AAG Get macro requests the server to provide a set of current values for the items identified by the supplied tags and attributes. Values returned from the server are written to the OutputRange and the optional status information is written to the StatusRange.

If the AttributeRange is omitted or the TagRange and AttributeRange are the same size and shape, then a list of values is requested from the server and placed in the OutputRange, with one value for each tag/attribute pair.

If the TagRange and AttributeRange are orthogonal (e.g., tags in a column and attributes in a row), then a table of values is requested from the server and placed in the OutputRange.

The size and shape requirements of the OutputRange are determined by the number of tags and attributes specified and whether they form a list or a table. The StatusRange (if specified) must be the same size and shape as the OutputRange.

Syntax

=AAG("Get", ServerName, TagRange, [AttributeRange], OutputRange, [StatusRange])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names for the data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

AttributeRange

AttributeRange is an optional argument that if specified must resolve to a range. This range contains one or more text strings that are the attribute names for the data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetAttributes request. The AttributeRange can be a cell, a row or a column.

OutputRange

OutputRange is a required argument that must resolve to a range. This is the range of cells where the values returned from the server are written. Syntax checking ensures that the OutputRange is correct for the size and shape of the tag and attribute ranges. The previous contents of cells in this range are destroyed. Information returned from the server determines if the value placed in a cell is a numeric, Boolean, or a string. If the server does not supply a value for a particular item, the Excel error value #N/A is placed in the cell. Further information about the error may be reported in the optional StatusRange.

StatusRange

StatusRange is an optional argument that if specified must resolve to a range which is the same size and shape as the OutputRange. It is used to store an item-by-item status as returned by the server. Content and interpretation of the status information is server-specific, but the information can be either integer or string values. The Server Data Errors section in Chapter 6 contains details on status information returned from a server.

Example

=AAG("Get", "North Plant", A2:A5, B1:D1, B2:D5,)

The figure below shows the results of executing this macro. The server named North Plant is asked to provide a table of current values for the tags in the TagRange A2:A5 and the attributes in the AttributeRange B1:D1. The twelve values returned by the server are placed in the OutputRange B2:D5. The optional StatusRange has been omitted in this call.

[pic]

AAG Put

AAG PutThe AAG Put macro requests the server to store the values supplied in InputRange into the items identified by the supplied tags and attributes. Status returned from the server is written to the optional StatusRange.

If the AttributeRange is omitted or the TagRange and AttributeRange are the same size and shape, then the list of values in the InputRange is supplied to the server, with one value for each tag/attribute pair.

If the TagRange and AttributeRange are orthogonal (e.g., tags in a column and attributes in a row), then the table of values in the InputRange is supplied to the server.

The size and shape of the InputRange is determined by the number of tags and attributes specified and whether they form a list or a table. The StatusRange (if specified) must be the same size and shape as the InputRange.

Syntax

=AAG("Put", ServerName, TagRange, [AttributeRange], InputRange, [StatusRange])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names for the data values being passed to the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

AttributeRange

AttributeRange is an optional argument that if specified must resolve to a range. This range contains one or more text strings that are the attribute names for the data values being passed to the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetAttributes request. The AttributeRange can be a cell, a row or a column.

InputRange

InputRange is a required argument that must resolve to a range. This range contains a set of values to be sent to the server. Syntax checking ensures that the InputRange is correct for the size and shape of the tag and attribute ranges associated with it and that no cells in the InputRange are empty or contain Excel error values (e.g., #N/A).

StatusRange

StatusRange is an optional argument that if specified must resolve to a range which is the same size and shape as the InputRange. It is used to store an item-by-item status as returned by the server. Content and interpretation of the status information is server-specific, but the information can be either integer or string values. The Server Data Errors section in Chapter 6 contains details on status information returned from a server.

Example

=AAG("Put", A1, tags, attrs, data, status)

The figure below shows the results of executing this macro. The ServerName South Plant is retrieved from cell A1. Named ranges are used for the four range arguments: tags refers to TagRange B1:B2, attrs refers to AttributeRange C1:C2, data refers to InputRange D1:D2 and status refers to StatusRange E1:E2. In order for this macro to succeed, these four range names must be defined to Excel beforehand. Since the TagRange and AttributeRange are parallel to each other, this is a list request. This macro requests the server South Plant to replace its current values for the two tag/attribute pairs with the data values in the InputRange D1:D2. The optional StatusRange is included in this call and the non-blank value returned to cell E1 of the StatusRange indicates that the Put request for the Flow_01 DESC data value had an unsuccessful result. The Server Data Errors section in Chapter 6 contains details of StatusRange messages.

[pic]

AAG GetHistory

AAG GetHistoryThe AAG GetHistory macro requests the server to provide a set of historical values (and optionally, a set of related sample times) for the items identified by the supplied tags, attributes and times. Values returned from the server are written to the OutputRange, sample times are written to the optional TimeRange and the optional status information is written to the StatusRange.

GetHistory values are arranged in a matrix. One dimension of the matrix is the number of tag/attribute pairs supplied. The other dimension is the number of samples requested. The first sample consists of values from StartTime and succeeding samples consist of values offset from StartTime by IntervalTime. Values returned from the server are written to the OutputRange starting at StartTime and proceeding through each successive sample. Times returned from the server are written to the optional TimeRange in the same order, one time per sample. Optional status information is written to the StatusRange.

The AttributeRange (if specified) must match the size and shape of the TagRange. The TimeRange (if supplied) must be orthogonal to the TagRange (e.g., if TagRange is a row, then TimeRange must be a cell or a column) and must contain a cell for each expected sample time. The size and shape of the OutputRange is determined in one dimension by the number of tag/attribute names supplied and in the other by the number of samples being requested. The StatusRange (if specified) must match the size and shape of the OutputRange.

Syntax

=AAG("GetHistory", ServerName, TagRange, [AttributeRange], OutputRange, StartTime, IntervalTime, [TimeRange], [StatusRange])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names for the historical data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

AttributeRange

AttributeRange is an optional argument that if specified must resolve to a range. This range contains one or more text strings that are the attribute names for the historical data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetAttributes request. The AttributeRange can be a cell, a row or a column, but it must be the same size and shape as the TagRange.

OutputRange

OutputRange is a required argument that must resolve to a range. This is the range of cells where the historical data values returned from the server are written. Syntax checking ensures that the OutputRange is correct for the size and shape of the tag, attribute and time ranges. The previous contents of cells in this range are destroyed. Information returned from the server determines if the value placed in a cell is a numeric, Boolean, or a string. If the server does not supply a value for a particular item, the Excel error value #N/A is placed in the cell. Further information about the error may be reported in the optional StatusRange.

StartTime

StartTime is a required argument that must resolve to a text string. The formatting of the string is server-specific. This time represents the starting point from which historical values are to be retrieved. The server determines how samples will be aligned to time.

Note that time strings cannot be numeric and are not Excel time/date values.

IntervalTime

IntervalTime is a required argument that must resolve to a text string. The formatting of the string is server-specific. This time represents the interval of time that elapses between successive samples of historical data. The server determines how samples will be aligned to time.

Note that time strings cannot be numeric and are not Excel time/date values.

TimeRange

TimeRange is an optional argument that if specified must resolve to a range. Specifying this range directs the server to return an actual sample time string for each set of samples in the OutputRange. The format of a time string is server-specific.

StatusRange

StatusRange is an optional argument that if specified must resolve to a range which is the same size and shape as the OutputRange. It is used to store an item-by-item status as returned by the server. Content and interpretation of the status information is server-specific, but the information can be either integer or string values. The Server Data Errors section in Chapter 6 contains details on status information returned from a server.

Example

=AAG("GetHistory", "Historian", B1:C1, B2:C2, B3:C6, "9/15/93 12:00", "0:05", A3:A6,)

The figure below shows the results of executing this macro. The server named Historian is asked to provide a set of historical values for the two tag/attribute pairs. The tags are in TagRange B1:C1 and the attributes are in AttributeRange B2:C2. The historical values being requested for each tag/attribute pair consist of a total of four samples beginning at the StartTime of 9/15/93 12:00 and spaced at an IntervalTime of 0:05. Note that the format of these time strings is server-specific and is not dictated by @aGlance/IT. The server returns the eight values displayed in the OutputRange B3:C6. Note that the server opted to return no value for Flow_01 APV in the last sample, so @aGlance/IT displays the Excel error value of #N/A in this cell. Also note that the server has returned it's actual sample times in the optional TimeRange A3:A6 and that they don't exactly match the requested intervals. The optional StatusRange has been omitted in this call.

[pic]

AAG GetHistEvent

AAG GetHistEventThe AAG GetHistEvent macro requests the server to provide a set of compressed historical values (and optionally, a set of related sample times) for the items identified by the supplied tags, attributes and times. Values returned from the server are written to the OutputRange, sample times are written to the optional TimeRange and the optional status information is written to the StatusRange.

Unlike the GetHistory macro call, this call does not specify a start and interval time, but rather a start and an end time, and the server returns historical values as recorded by the historian, i.e., compressed and without interpolation. Since the number of samples for a given time period may not be known to the user, this call includes a StartIndex for the server to indicate that there is more data than would fit in the OutputRange.

GetHistEvent values are arranged in a matrix. One dimension of the matrix is the number of tag/attribute pairs supplied. The other dimension is the number of samples requested. The first sample consists of compressed values from StartTime and succeeding samples consist of compressed values from later times. Note that a compressed history sample may contain data only for some, and not all, of the requested tag/attribute names. Values returned from the server are written to the OutputRange starting at StartTime and proceeding through each successive sample. Times returned from the server are written to the optional TimeRange in the same order, one time per sample. Optional status information is written to the StatusRange. If the optional StartIndex argument is specified as being in a spreadsheet cell, then it is updated with the index returned from the server. If it is not specified or is specified as a constant, then no update occurs.

The AttributeRange (if specified) must match the size and shape of the TagRange. The TimeRange (if supplied) must be orthogonal to the TagRange (e.g., if TagRange is a row, then TimeRange must be a cell or a column) and must contain a cell for each expected sample time. The size and shape of the OutputRange is determined in one dimension by the number of tag/attribute names supplied and in the other by the number of samples being requested. The StatusRange (if specified) must match the size and shape of the OutputRange.

Syntax

=AAG("GetHistEvent", ServerName, TagRange, [AttributeRange], [StartIndex], OutputRange, StartTime, EndTime, [TimeRange], [StatusRange])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names for the historical data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

AttributeRange

AttributeRange is an optional argument that if specified must resolve to a range. This range contains one or more text strings that are the attribute names for the historical data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetAttributes request. The AttributeRange can be a cell, a row or a column, but it must be the same size and shape as the TagRange.

StartIndex

StartIndex is an optional argument that if specified must resolve to an integer. It is meant to contain a server-supplied value that is used by the server as a place holder when successive requests are made to a server. By using the index returned from the server on a previous GetHistEvent request as the StartIndex on successive GetHistEvent requests, a set of historical data values can be displayed in an OutputRange that is too small to contain them all at once.

If not specified, StartIndex defaults to zero indicating that the server should return the requested data starting at the beginning of its database.

OutputRange

OutputRange is a required argument that must resolve to a range. This is the range of cells where the historical data values returned from the server are written. Syntax checking ensures that the OutputRange is correct for the size and shape of the tag, attribute and time ranges. The previous contents of cells in this range are destroyed. Information returned from the server determines if the value placed in a cell is a numeric, Boolean, or a string. If the server does not supply a value for a particular item, the Excel error value #N/A is placed in the cell. Further information about the error may be reported in the optional StatusRange.

StartTime

StartTime is a required argument that must resolve to a text string. The formatting of the string is server-specific. This time represents the starting point from which historical values are to be retrieved. The server determines how samples will be aligned to time.

Note that time strings cannot be numeric and are not Excel time/date values.

EndTime

EndTime is a required argument that must resolve to a text string. The formatting of the string is server-specific. This time represents the endpoint from which historical values are to be retrieved. The server determines how samples will be aligned to time.

Note that time strings cannot be numeric and are not Excel time/date values.

TimeRange

TimeRange is an optional argument that if specified must resolve to a range. Specifying this range directs the server to return an actual sample time string for each set of samples in the OutputRange. The format of a time string is server-specific.

StatusRange

StatusRange is an optional argument that if specified must resolve to a range which is the same size and shape as the OutputRange. It is used to store an item-by-item status as returned by the server. Content and interpretation of the status information is server-specific, but the information can be either integer or string values. The Server Data Errors section contains details on status information returned from a server.

Example

=AAG("GetHistEvent", "Historian", B1:C1, B2:C2, A1, B3:C6, "9/15/93 12:00", "13:00", A3:A6,)

The figure below shows the results of executing this macro. The server named Historian is asked to provide a set of compressed historical values for the two tag/attribute pairs. The tags are in TagRange B1:C1 and the attributes are in AttributeRange B2:C2. The historical values being requested for each tag/attribute pair consist of a total of four samples beginning at the StartTime of 9/15/93 12:00 and continuing to the EndTime of 13:00. Note that the format of these time strings is server-specific and is not dictated by @aGlance/IT. The server returns the eight values displayed in the OutputRange B3:C6 - note that the server has returned no data for three of the values, so @aGlance/IT displays the Excel error value of #N/A in these cells. Also note that the server has returned it's actual sample times in the optional TimeRange A3:A6. Finally, the value of 4 has been returned from the server and placed in the StartIndex cell A1. This non-zero value indicates that the server has additional historical data from the specified time range that can be retrieved by passing this value as the StartIndex argument in another GetHistEvent request. The optional StatusRange has been omitted in this call.

[pic]

AAG GetHistStats

AAG GetHistStatsThe AAG GetHistStats macro requests the server to provide a set of statistical values for the items identified by the supplied tags, attributes and statistical types. Values returned from the server are written to the OutputRange and the optional status information is written to the StatusRange.

GetHistStats values are arranged in a matrix. One dimension of the matrix is the number of tag/attribute pairs supplied. The other dimension is defined by the TypeRange that contains strings defining the types of statistical data requested. For each tag/attribute name and each statistical type, the server is requested to return a value that represents its calculation of the requested statistic from StartTime to EndTime. Values returned from the server are written to the OutputRange. Status information is written to the optional StatusRange.

The AttributeRange (if specified) must match the size and shape of the TagRange. The TypeRange must be orthogonal to the TagRange (e.g., if TagRange is a row, then TypeRange must be a cell or a column). The size and shape of the OutputRange is determined in one dimension by the number of tag/attribute names supplied and in the other by the number of statistical types being requested. The StatusRange (if specified) must match the size and shape of the OutputRange.

Syntax

=AAG("GetHistStats", ServerName, TagRange, [AttributeRange], OutputRange, StartTime, EndTime, TypeRange, [StatusRange])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names for the historical data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

AttributeRange

AttributeRange is an optional argument that if specified must resolve to a range. This range contains one or more text strings that are the attribute names for the historical data values being requested from the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetAttributes request. The AttributeRange can be a cell, a row or a column, but it must be the same size and shape as the TagRange.

OutputRange

OutputRange is a required argument that must resolve to a range. This is the range of cells where the historical data values returned from the server are written. Syntax checking ensures that the OutputRange is correct for the size and shape of the tag and attribute ranges. The previous contents of cells in this range are destroyed. Information returned from the server determines if the value placed in a cell is a numeric, Boolean, or a string. If the server does not supply a value for a particular item, the Excel error value #N/A is placed in the cell. Further information about the error may be reported in the optional StatusRange.

StartTime

StartTime is a required argument that must resolve to a text string. The formatting of the string is server-specific. This time represents the starting point from which historical values are to be retrieved. The server determines how samples will be aligned to time.

Note that time strings cannot be numeric and are not Excel time/date values.

EndTime

EndTime is a required argument that must resolve to a text string. The formatting of the string is server-specific. This time represents the endpoint from which historical values are to be retrieved. The server determines how samples will be aligned to time.

Note that time strings cannot be numeric and are not Excel time/date values.

TypeRange

TypeRange is a required argument that must resolve to a range. This range contains a set of strings indicating to the server which type of historical statistic is being requested. These strings may be server-specific, but it is suggested that you use the following standard types wherever possible:

AAG_HIST_MIN - Minimum

AAG_HIST_MAX - Maximum

AAG_HIST_AVG - Average

AAG_HIST_STDDEV - Standard Deviation

Syntax checking ensures that the TypeRange is a valid shape and that no cells in the TypeRange are empty or contain Excel error values (e.g., #N/A). TypeRange can be a cell, a row or a column. This range defines one dimension of the OutputRange for the GetHistStats function and the tag/attribute names comprise the other dimension.

StatusRange

StatusRange is an optional argument that if specified must resolve to a range which is the same size and shape as the OutputRange. It is used to store an item-by-item status as returned by the server. Content and interpretation of the status information is server-specific, but the information can be either integer or string values. The Server Data Errors section contains details on status information returned from a server.

Example

=AAG("GetHistStats", "Historian", A2:A3, B2:B3, C2:D3, "9/15/93 12:00", "13:00", C1:D1,)

The figure below shows the results of executing this macro. The server named Historian is asked to provide the minimum and maximum values recorded for the two tag/attribute pairs in the interval between the StartTime of 9/15/93 12:00 and the EndTime of 13:00. Note that the format of these time strings is server-specific and is not dictated by @aGlance/IT. The tags are in TagRange A2:A3 and the attributes are in AttributeRange B2:B3. The type of statistic being requested is indicated by the value in the TypeRange C1:D1. The server returns the four values displayed in the OutputRange C2:D3. The optional StatusRange has been omitted in this call

. [pic]

AAG PutHistory

AAG PutHistoryThe AAG PutHistory macro requests the server to store the values supplied in InputRange into the items identified by the supplied tags, attributes and times. Status returned from the server is written to the optional StatusRange.

PutHistory information is organized as a list. For each tag/attribute pair, there is one value, one (optional) sample time and one (optional) status value. The optional PutType field allows the user to specify an optional Type string.

The TagRange, AttributeRange (if specified), TimeRange (if specified) , InputRange and StatusRange (if specified) must all be the same size and shape.

Syntax

=AAG("PutHistory", ServerName, TagRange, [AttributeRange], [TimeRange], InputRange, [StatusRange], [PutType])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

TagRange

TagRange is a required argument that must resolve to a range. This range contains one or more text strings that are the tag names for the historical data values being passed to the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetTags request. The TagRange can be a cell, a row or a column.

AttributeRange

AttributeRange is an optional argument that if specified must resolve to a range. This range contains one or more text strings that are the attribute names for the historical data values being passed to the server. This range should not include the index value that is always returned to the first cell of the OutputRange during a GetAttributes request. The AttributeRange can be a cell, a row or a column, but it must be the same size and shape as the TagRange.

TimeRange

TimeRange is an optional argument that if specified must resolve to a range. This range must contain time strings to be provided to the server. The format of a time string is server-specific.

TimeRange is an optional argument that if specified must resolve to a range. Specifying this range directs the server to return an actual sample time string for each set of samples in the OutputRange. The format of a time string is server-specific. The TimeRange must be the same size and shape of the TagRange and that no cells in the TimeRange can be empty or contain Excel error values (e.g., #N/A).

InputRange

InputRange is a required argument that must resolve to a range. This range contains the historical data values being passed to the server. The InputRange must be the same size and shape of the TagRange and that no cells in the InputRange can be empty or contain Excel error values (e.g., #N/A).

StatusRange

StatusRange is an optional argument that if specified must resolve to a range which is the same size and shape as the InputRange. It is used to store an item-by-item status as returned by the server. Content and interpretation of the status information is server-specific, but the information can be either integer or string values. The Server Data Errors section in Chapter 6 contains details on status information returned from a server.

PutType

PutType is an optional argument that if provided must resolve to a text string. PutType can be used to provide a server-specific indicator of the type of historical put requested (e.g., insert or replace).

Example

=AAG("PutHistory", "Historian", A1, B1, C1, D1, E1, "Replace")

The figure below shows the results of executing this macro. The server named Historian is asked to execute a PutHistory function for the historical value represented by the tag name in TagRange A1, the attribute name in AttributeRange B1 and the time in TimeRange C1. The value in InputRange D1 is passed to the server as the new value. The optional PutType string is server-specific and has been defined as "Replace". The blank StatusRange cell E1 indicates that the PutHistory operation was successful.

[pic]

AAG Command

AAG CommandThe AAG Command macro requests the server to perform a server-specific command. Optional InputValues can be provided to the server and optional OutputValues can be accepted from the server as part of the command processing. This function is completely server defined - the command string is passed to the server along with any values from the optional InputValues range and return values are placed in the optional OutputValues range.

Syntax

=AAG("Command", ServerName, Command, [InputValues], [OutputValues])

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

Command

Command is a required argument that must resolve to a text string. This string contains a server-specific command.

InputValues

InputValues is an optional argument that if specified must resolve to a range. This range contains values to be sent to the server. There are no specific size and shape rules for this range. Syntax checking ensures that InputValues includes no cells that are empty or that contain Excel error values (e.g., #N/A).

OutputValues

OutputValues is an optional argument that if specified must resolve to a range. This is the range of cells where the values returned from the server are written. There are no specific size and shape rules for this range. The previous contents of cells in this range are destroyed. Information returned from the server determines if the value placed in a cell is a numeric, Boolean, or a string. If the server does not supply a value for a particular item, the Excel error value #N/A is placed in the cell.

Example

=AAG("Command", "MyServer", "Number of", A1:A2, B1:B2)

The figure below shows the results of executing this macro. The server named Myserver is asked to execute the command "Number of" with the data from the InputValues range of A1:A2. The return values from the server are placed in the OutputValues range B1:B2. Again, the implementation and interpretation of the Command function is completely server-specific, and users require detailed knowledge of a server in order to use this macro successfully.

[pic]

AAG Disconnect

AAG DisconnectThe AAG Disconnect macro ends the current communication session with the specified server. This macro allows an @aGlance/IT user to explicitly free resources once all requests to a specific server are complete. If further requests are made to a server after a Disconnect, a new session is started. If no Disconnect request is made, the session is automatically disconnected when Excel exits.

Because of the overhead involved in starting a new session, an existing session should not be disconnected unless:

1. The user will remain in Excel for some time

and

2. No further use will be made of the existing @aGlance/IT session.

Syntax

=AAG("Disconnect", ServerName)

ServerName

ServerName is a required argument that must resolve to a text string. This string is the name of the specific server targeted to receive the @aGlance/IT request.

Example

=AAG("Disconnect", Sheet1.XLS!$A$1)

There are no visible results from executing this macro. A Disconnect request is passed to the server whose name is found in cell $A$1 on Sheet1.XLS. This type of external cell reference allows the AAG macro to operate on cells other than those in the current sheet.

Chapter five

Error Handling

5 Error Handling" There are three kinds of errors that can occur when requests are made of the @aGlance/IT add-in. These are:

Add-in Errors

Server Data Errors

Overflow Errors

Error Types

Error Types Add-in Errors

The @aGlance/IT Excel add-in reports errors such as user syntax errors or the inability to reach the specified server in a pop-up Alert Box. This Alert Box requires a response from the user before allowing the add-in to regain control. Whenever an add-in error occurs, the AAG macro returns the Excel error value #N/A to the cell that contains the AAG macro.

All @aGlance/IT add-in error messages displayed in an Alert Box have the prefix "AAG Error:" to help you identify them as @aGlance/IT error messages. This is done because a variety of other Excel errors can occur during the processing of Excel macro calls.

A Help button on the Alert box allows you to jump to the section of the Help file that explains the possible causes of the error. Text for these error messages is shown in the Error Messages section below.

Server Data Errors

A server may encounter a variety of data errors when processing an AAG request to get or put data. When such an error occurs with a particular data item, the server has the option of returning status information in the StatusRange of the AAG request if this optional argument has been specified.

Additionally, if the request is a "get" of current or historical data, the server has the option of returning or not returning a value for a particular item.

A server can use the StatusRange to signal four possible status severity levels for an individual data item:

Success

Warning

Error

Fatal

In addition to the status severity level, the server can provide either status text or a status code for any item whose status level is not Success.

The following rules govern the display of information in the StatusRange:

- If the StatusRange is not specified in the request, then no

status can be reported.

- If a status severity level of Success is set for a data item

or if the server declines to report status for a particular item,

the corresponding cell in StatusRange is cleared regardless

of whether a status code or status text was also provided by

the server.

- If a status severity level of Warning, Error or Fatal is set

for a data item, the corresponding cell in StatusRange is

used to report the status. If the server provides status text,

that text is moved to the cell, otherwise the status code is

moved to the cell.

The following rules govern the display of values in the OutputRange of a Get or any of the three GetHistory requests:

- If no value is supplied for a data item, then the Excel value

#N/A is moved to the corresponding cell in OutputRange,

regardless of status level.

- If a status severity level of Success or Warning is set for

a data item, then the value returned by the server is moved

to the corresponding cell in OutputRange.

- If a status severity level of Error or Fatal is set for a data

item, then the Excel error value #N/A is moved to the

corresponding cell in OutputRange.

Overflow Errors

The largest string that Excel can handle is 255 characters. If a server returns a string larger than this, the @aGlance/IT add-in truncates the string to 255 characters and displays it normally. No error indication is given.

Error Messages

Error Messages@aGlance/IT Init Failed

The @aGlance/IT initialization failed. This error message should be followed by text explaining the problem (for example, insufficient memory).

Attempt to Run Multiple Copies

(Windows only)

Only a single copy of @aGlance/IT for Excel can be run at once. Another copy is currently active.

Bad AttributeRange Argument

The AttributeRange argument is optional on the functions where it is used. If specified, it must be a range or a name that resolves to a range. This range must be a cell, row, or column that is filled with attribute names.

Bad Command Argument

The Command argument is required on the function where it is used. It must be specified as a string or a reference that resolves to a string. The format of the string is server-specific.

Bad EndTime Argument

The EndTime argument is required on the functions where it is used. It must be specified as a string or a reference that resolves to a string. The format of the string is server-specific.

Bad Function Argument

An unknown function was specified. Function names must be text strings. Valid functions are listed in the Macro Syntax section of Chapter 3.

Bad InputRange Argument

The InputRange argument is required on the functions where it is used. It must be a range or a name that resolves to a range. The InputRange is often paralleled along one or both dimensions by other ranges that define its size and shape requirements. Also this error can signal a problem with the contents of InputRange - this range cannot include cells that are empty or that contain Excel error values such as #N/A.

Bad IntervalTime Argument

The IntervalTime argument is required on the functions where it is used. It must be specified as a string or a reference that resolves to a string. The format of the string is server-specific.

Bad MatchString Argument

The MatchString argument is required on the functions where it is used. If the default value is not used, it must be specified as a string or a reference that resolves to a string.

Bad OutputRange Argument

The OutputRange argument is required on the functions where it is used. It must be a range or a name that resolves to a range. The OutputRange is often paralleled along one or both dimensions by other ranges that define its size and shape requirements.

Bad PutType Argument

The PutType argument is optional on the functions where it is used. If specified, it must be a string or a reference that resolves to a string.

Bad ServerName Argument

The ServerName argument is required on all functions and it must be specified as a string or as a reference that resolves to a string.

Bad StartIndex Argument

The StartIndex argument is required on the functions where it is used. If the default value is not used, it must be specified as an integer value or as a reference that resolves to an integer.

Bad StartTime Argument

The StartTime argument is required on the functions where it is used. It must be specified as a string or a reference that resolves to a string. The format of the string is server-specific.

Bad StatusRange Argument

The StatusRange argument is optional on the functions where it is used. If specified, it must be a range or a name that resolves to a range. It must be the same size and shape as its associated InputRange or OutputRange.

Bad TagRange Argument

The TagRange argument is required on the functions where it is used. It must be specified as a range or as a name that resolves to a range. This range is required to be a cell, row, or column that is filled with tag names.

Bad TimeRange Argument

The TimeRange argument is optional on the functions where it is used. If specified, it must be a range or a name that resolves to a range. Its size and shape is dictated by the InputRange or OutputRange argument. When used with the PutHistory function, this range must contain time strings.

Bad TypeRange Argument

The TypeRange argument is required on the functions where it is used. It must be a range or a name that resolves to a range. This range must be a valid shape and contain no empty cells or Excel error values (e.g., #N/A).

Extra Argument

Too many arguments were included for the function specified.

Internal Error

Indicates an internal error with the add-in. Please report this.

Internal Error - Excel Call Failed

In Excel call made by the add-in has failed unexpectedly. Please report this.

Out of Memory

There is not enough dynamic memory available to service the request. Try a smaller request.

Server Request Failed

An error occurred while a server request was being processed by lower software layers. This error message should be followed by text explaining the lower level problem (for example, server not found).

Tag/Attribute Mismatch

The specified TagRange and AttributeRange have an incompatible size and shape for the function being requested. For example, both of the ranges are columns (or both are rows) but the ranges have different sizes - an invalid circumstance.

Unable to Launch @aGlance/IT Bridge

(Macintosh only)

The @aGlance/IT Bridge application cannot be launched. Quit all applications including Excel and retry. Also check for the existence of the @aGlance/IT Bridge file in the Excel folder.

Unable to Register AAG Macro

The AAG macro cannot be registered. Please check for the existence of the XLAAG.DLL (Windows) or XLAAG (Macintosh) file in the Excel directory/folder.

Index

Index “

A

AAG Functions

Command • 42

Disconnect • 44

Get • 21

Get Attributes • 18

Get History • 27

Get History Event • 31

Get History Statistics • 35

Get Tags • 16

Put • 24

Put History • 39

AAG Macro

Arguments • 14

Cell References • 14

Integer Arguments • 14

Lists as Arguments • 10

String Arguments • 14

Syntax • 13

Tables as Arguments • 11

Absolute References • 14

AUTOEXEC.BAT • 4

B

Browser • 50

D

DECnet • 2

Demo sheets • 6, 52

E

Errors

Add-in • 53

Message Text • 56

Overflow • 55

Server data • 54

G

Get ... • See AAG Functions

Get Uncompressed History • See Get History Event

I

Installation

@aGlance/IT for Windows • 4

ObjectBroker for Windows • 4

L

Licensing • 8

M

Macro Tool • 8, 45, 47, 51

Menu Interface • 7, 49

O

ObjectBroker Configuration

for Windows • 4

On Line Help • 6, 47, 52

P

Put ... • See AAG Functions

R

Ranges • 9, 14

Relative References • 14

S

Sample Server • 6

Setup Diagnostic • 4

SYSTEM.INI • 4

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download