query reference manual

8/13/2019 Query Reference Manual

1/29

QueryReference Manual


2/29

Disclaimer

Information of a technical nature, and particulars of the product and its use, is given by AVEVASolutions Ltd and its subsidiaries without warranty. AVEVA Solutions Ltd and its subsidiaries disclaim

any and all warranties and conditions, expressed or implied, to the fullest extent permitted by law.

Neither the author nor AVEVA Solutions Ltd, or any of its subsidiaries, shall be liable to any person orentity for any actions, claims, loss or damage arising from the use or possession of any information,particulars, or errors in this publication, or any incorrect use of the product, whatsoever.

Copyright

Copyright and all other intellectual property rights in this manual and the associated software, and everypart of it (including source code, object code, any data contained in it, the manual and any otherdocumentation supplied with it) belongs to AVEVA Solutions Ltd or its subsidiaries.

All other rights are reserved to AVEVA Solutions Ltd and its subsidiaries. The information contained in

this document is commercially sensitive, and shall not be copied, reproduced, stored in a retrievalsystem, or transmitted without the prior written permission of AVEVA Solutions Ltd. Where suchpermission is granted, it expressly requires that this Disclaimer and Copyright notice is prominentlydisplayed at the beginning of every copy that is made.

The manual and associated documentation may not be adapted, reproduced, or copied, in any materialor electronic form, without the prior written permission of AVEVA Solutions Ltd. The user may also notreverse engineer, decompile, copy, or adapt the associated software. Neither the whole, nor part of theproduct described in this publication may be incorporated into any third-party software, product,machine, or system without the prior written permission of AVEVA Solutions Ltd, save as permitted bylaw. Any such unauthorised action is strictly prohibited, and may give rise to civil liabilities and criminalprosecution.

The AVEVA products described in this guide are to be installed and operated strictly in accordance withthe terms and conditions of the respective license agreements, and in accordance with the relevantUser Documentation. Unauthorised or unlicensed use of the product is strictly prohibited.

First published September 2007

AVEVA Solutions Ltd, and its subsidiaries

AVEVA Solutions Ltd, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom

Trademarks

AVEVA and Tribon are registered trademarks of AVEVA Solutions Ltd or its subsidiaries. Unauthorised

use of the AVEVA or Tribon trademarks is strictly forbidden.

AVEVA product names are trademarks or registered trademarks of AVEVA Solutions Ltd or itssubsidiaries, registered in the UK, Europe and other countries (worldwide).

The copyright, trade mark rights, or other intellectual property rights in any other product, its name orlogo belongs to its respective owner.

AVEVA Solut ions Ltd


3/29

Query Reference Manual

Contents Page

12.0i


Reference Manual

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1

Who this Manual is Meant For . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:1

Guide Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2

Conventions used in the Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1:2

Communicating Using Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1

Direct ing Commands to the Data Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1

Connecting Query to a Data Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:1

Environmental Setup Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:2

Sending Commands to a Data Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:3

Setting Variables from the Data Server Responses . . . . . . . . . . . . . . . . . . . . . . 2:4

Specifying the Data Field Delimiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:6

Handling Returned Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2:7

Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:1

Command Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:2

CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3

DELIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3

END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4

EXTERNAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4

GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5


4/29

12.0ii


OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5

SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:6

START

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:6

TOGGLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:7

Query and ODBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1

ODBC Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1

Connection Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:2

Special Facili ties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:3

SQL Escape Sequences in ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:5


5/29


Introduction

12.01:1

1 Introduction

Query is a flexible way to access and manipulate the contents of outside databases fromwithin its products. It provides for a two-way flow of data between application programs andlocal or remote databases using Structured Query Language (SQL) as its database accesslanguage. SQL became an ANSI standard in 1986 and an ISO standard in 1987; it is used

today in a great many database application programs management systems.

Query is essentially a programming toolkit which allows the user to create their own macrosto carry out functions such as:

Reading additional attribute data from local or remote databases

Adding object and attribute data to external databases

Adding functionality to existing user interfaces

The addition of Query to an application program forms a powerful programmableengineering database system.

Query supports Open Database Connectivity (ODBC), an interface standard for databaseaccess. All components necessary to provide the ODBC interface, such as

communications, are internal to ODBC.A user of Query commands is presented with the same interface and need not be aware ofthe different ways in which the functionality is provided, except of course when Query or thedatabase is configured.

1.1 Who this Manual is Meant For

The Query Reference Manual describes the Query command syntax which you can use toset up links between Plant and an external database. It is intended for those who need towrite application macros for use from within those products, the principal purpose of suchmacros being to allow users to interrogate a database and to use the results to control Plant

operations in a user-friendly manner. The manual does not attempt to define rules for writingsuch macros, nor does it tell you how you should document the ways in which end-usersshould use your macros and their controlling interfaces.

The manual assumes that you have some prior experience of programming and that you arealready familiar with the following aspects:

The functions of Plant and the ways in which these are controlled via the standard userinterface.

The data server commands necessary to insert, delete, query and protect data in yourchosen database.

The concepts of writing and running macro command files, including the use ofProgrammable Macro Language (PML), as detailed in the Software CustomisationGuide.

The design and implementation of a forms and menus graphical user interface.


6/29

12.01:2


Introduction

1.2 Guide Structure

The Query Reference Manual is divided into the following sections:

1.3 Conventions used in the Text

The following conventions are used throughout this manual to highlight certain features ofthe text:

Command words are shown as a combination of uppercase and lowercase characters,using a different typeface from that used for normal text; for example, COMMandword.The uppercase part of the word (COMM in the preceding example) is the minimumpermissible abbreviation. Where a command word is first introduced, or where its useis defined, it will usually be shown in bold type, thus

COMMandword

Command arguments are shown in lowercase italic type; for example, argument.

Parts of the command enclosed between square brackets are optional; for example, ...[ignore this part of the command if not relevant]

Examples of interactive input and output sequences are shown in a different typeface,thus

Exampl e of I nput / Out put Sequence Typef ace

Character strings which begin with the slash character / are either names of elementsin the databases or the names of files in the operating system directories. For example,/ELEMENT or /filename.

Character strings enclosed between angled brackets are the names of individual commandsyntax diagrams. For example, .

Communicating Using Query describes the basic principles of using Query,including some top-level commands which applyduring its use.

Command Syntax is the commands reference section and describes thecommand syntax which you can use to control Plantfrom within Query.

Query and ODBC describes the ODBC architecture used by Query withits setup requirements and special features.


7/29


Communicating Using Query

12.02:1

2 Communicating Using Query

The Communicating Using Query section explains the commands available within Query foraccessing an external database, such as a remote source on a data sever. Data settingscan be read from, or written to the data server. It also explains how the user can store andmanipulate the results of querying such data within Query.

2.1 Directing Commands to the Data Server

In order to direct any command line from Query to a data server, prefix the line with the word

EXTERnal

The remaining part of the line may comprise either:

A command to create a connection between Query and the data server

A command sequence for reading from or writing to the data server

The prefix is incorporated into all commands described in the remainder of this section.

2.2 Connecting Query to a Data Server

Before commands can be sent from Query to any data server, a link must be set up betweenthe two.

To connect Query to a data server which is installed on the same machine, use one of thecommands:

where synonym is a text string which identifies the server daemon through whichcommunication is to be channelled (and which therefore identifies the data server required);token_var is the name of a PML variable into which a token for the connection is to bewritten; and (if your data server requires login data) connect_string is a text string whichconfirms the users access rights (such as their username and password).

EXTERnal OPEn synonym token_var

EXTERnal OPEn synonym token_var [AS connect_string]


8/29

12.02:2



To connect Query to a data server which is installed on a different machine, use theextended form of the command

where synonym, token_varand connect_stringare as above and hostis a text string whichidentifies the node on the network on which the server daemon. For example, to connect toa data server on a machine called pc35, enter

EXTERNAL OPEN MAI NTENANCE ! ! MAI NT ON pc35 AS bul l /robert

or, alternatively, a generalised version such as

EXTERNAL OPEN MAI NTENANCE ! ! MAI NT ON sql net AS bul l /robert

where the alias sqlnet has been defined so as to point to the current host for, say, an SQLdatabase server.

To disconnect Query from a data server to which it is currently connected, use the command

where tokenis the token for the communication channel which was supplied by a successfulEXTERNAL OPEN command (and stored in the token_varvariable).

Note: The $ prefix used to expand the variable !!MAINT to give the token value.

2.3 Environmental Setup Requirements

You may need to set the following environment variables:

ODBC_DRIVER_TRACE_FILE

If this environment variable is set to a pathname, the trace output produced by ODBCdrivers will be set to this log file instead of the ODBC default filename. Trace output isswitched on and off with the EXTERNAL TRACE command.

Note: The ODBC Data Source Administ ratoralso provides control over this logging.

Example:

EXTERNAL OPEN MAI NTENANCE ! ! MAI NT AS bul l / r ober t

or

EXTERNAL OPEN ODBC ! ! MAI NT AS DSN=MAI NTDAT;

EXTERnal OPEn synonym t oken_var ON host [ AS connect _st r i ng]

EXTERnal CLOse token

Example:

EXTERnal CLOse $! ! MAI NT


9/29



12.02:3

2.4 Sending Commands to a Data Server

Note: It is assumed that the user is already familiar with the commands for communicating

with their data server; for example, the SQL commands needed to interact with anSQL database.

The user can send commands to the data server in one of two ways:

As individual command lines, each of which is sent as soon as the newlinecharacter isentered to terminate the command line.

In continuous mode, such that a sequence of command lines is concatenated and sentas a single command string. The maximum length for an individual command line is120 characters; continuous mode allows the user to send longer command sequences.

To send an individual command line to the data server, simply prefix the command text thus:

where tokenis the token for the communication channel which was supplied by a successfulEXTERNAL OPEN command (and stored in the token_varvariable) and command_textisthe command string to be sent to the data server.

To send a continuous command sequence to the data server, use the syntax

where tokenis the token for the communication channel which was supplied by a successfulEXTERNAL OPEN command (and stored in the token_varvariable) and command_text_1etc. are the command strings to be sent to the data server.

where each line of command text is terminated by a newlinecharacter.

EXTERnal SENd token command_text

Example:

EXTERNAL SEND $! ! MAI NT commi t

EXTERnal SENd token STArt

command_t ext _1

command_t ext _2

. . .

END

Example:

EXTERNAL SEND $! ! MAI NT START

sel ect ref no, descr i pt i on, datedue

f r om mai nt dat a

wher e dat edue


10/29

12.02:4



When the END command is reached, all text lines entered since START are concatenated,with a space separator between each, and sent to the data server as a single command.

Note: Command texts may include references to PML variables.The maximum length for a single text line is 120 characters.The maximum total length for the overall text string (that is, all lines between theSTART and END commands) is 4095 characters, including the separating spaces.

2.5 Setting Variables from the Data Server Responses

All of the standard syntax for setting variables is available for use within Query. In addition,Query incorporates extra syntax for setting variables to data values returned from a dataserver.

To set a variable to the next row of data resulting from a data server query, use the syntax

where tokenis the token for the communication channel which was supplied by a successfulEXTERNAL OPEN command (and stored in the token_varvariable). The variable varnamewill be interpreted automatically as an array variableand each data item will be stored in aseparate element of the array. (The PML SPLIT command is not required here; splitting iscarried out automatically.)

Note: No data field should be longer than 120 characters, since this is the maximumpermitted length that can be stored in a variable. If a data field exceeds 120characters, nothingwill be returned by the query.

As an example, the querying command

EXTERNAL SEND $!! MAI NT sel ect ref no, servi nt , l as tservf r om mai nt dat a VAR ! dat ar ow EXTERNAL GET $! ! MAI NT NEXT

might return the following results:

Repeating the command

VAR ! dat ar ow EXTERNAL GET $! ! MAI NT NEXT

will retrieve the next data record, which will progressively overwritethe current settings ofthe array element elements. For example,

VAR varname EXTERnal GET token NEXT

$! dat ar ow[ 1] C1101 ( f i r st val ue of f i el d refno)

$! dat ar ow[ 2] 182 ( f i r st val ue of f i el d servint)

$! dat ar ow[ 3] 22- J AN- 10 ( f i r st val ue of f i el d lastserv)

$! dat ar ow[ 1] E1201 ( second val ue of f i el d refno)

$! dat ar ow[ 2] 31 ( second val ue of f i el d servint)

$! dat ar ow[ 3] 07- J AN- 10 ( second val ue of f i el d lastserv)


11/29



12.02:5

and so on for subsequent data records. If the newly read record has less completed fieldsthan the preceding record, some elements of the array variable will remain with theirprevious settings unchanged.

The user can control the writing of data to an array variable explicitly by using the variable-setting syntax. For example, to read in a record such that its first field is stored in element 10of the array variable, rather than starting from element 1 by default, the user could use thesyntax

VAR ! dat ar ow[ 10] EXTERNAL GET $! ! MAI NT NEXT

To read a record and append the resulting data to the array variable, rather than overwritingthe current settings of the array elements, the user could use the syntax

VAR ! dat ar ow APPEND EXTERNAL GET $! ! MAI NT NEXT

and so on.

The most convenient way to retrieve multiple data records is usually to incorporate theNEXT command into a PML infinite DO loop construct, reading one data record duringeach cycle of the loop. When the last record has been read in, the next cycle of the loop willgenerate the message

( 79, 10) No mor e dat a

which can be dealt with by using the PML HANDLE facility. For example:

To set the column headings returned by a data server query in an array variable, use eitherversion of the following syntax:

These commands always return the firstrow of the result of the last request sent to the dataserver identified by token(typically, but not necessarily, header information resulting from anSQL database SELECT command).

For example, the querying command

EXTERNAL SEND $! ! MAI NT sel ect * f r om mai nt dat aVAR ! header EXTERNAL GET $! ! MAI NT RESULT

EXTERNAL SEND $! ! MAI NT sel ect * f r om mai nt dat aDO VAR ! dat ar ow EXTERNAL GET $! ! MAI NT NEXT HANDLE ( 79, 10) BREAK

ENDHANDLE PML commands . . .ENDDO

VAR varname EXTERnal GET token RESult

VAR varname EXTERnal GET token HEADer


12/29

12.02:6



might return the following results:

Note: As with the data fields, no heading should be longer than 120 characters. If aheading exceeds 120 characters, nothingwill be returned by the query.

2.6 Specifying the Data Field Delimiter

When data is sent from a data server to Query, it is sent as a single data block. Each datafield within the block is delimited by a special character; by default, this is the ~ (tilde)

character. When Query receives the block, it uses the delimiter character to determine thepoints at which to split the data into individual fields. If the data includes the delimitercharacter withina text field, Query will split the data block at the wrong point.

For example, the data stored in the following fields:

would be received by Query, using the default ~ delimiter, as the data block

Catal yt i c Cr acker ~Ref l ux~Heat er~DES21142

and would be split, incorrectly, into the fields

To prevent this effect, you can redefine the delimiter character to be any single character

which is not used within any database field. To do so, use the command

where tokenis the token for the communication channel which was supplied by a successfulEXTERNAL OPEN command (and stored in the token_var variable) and text_char is therequired data field delimiter character.

For example, the specification

EXTERNAL DELI MI T $! ! MAI NT &

would cause the data block from the preceding example to be received as

$! header [1] r ef no

$! header [ 2] ser vi nt

$! header [ 3] l ast ser v

Ar ea Cat al yt i c Cr acker

Pl ant Ref l ux~Heat er

Code DES21142

$! a[ 1] Cat al yt i c Cr acker

$! a[ 2] Ref l ux

$! a[ 3] Heat er

$! a[ 4] DES21142

EXTERnal DELImit token text_char


13/29



12.02:7

Catal yt i c Cr acker &Ref l ux~Heat er&DES21142

which would be correctly split at the points identified by the & characters.

2.7 Handling Returned Errors

Errors which can be trapped and handled specifically by Query may result in one of thefollowing error messages (where inforepresents any supplementary information about theerror which is generated by the data server or the communications software).

Server Daemon Messages:

( 79, 3) Cannot i ni t i al i se ser ver daemon: info

For example, the server daemon executable cannot be found via

any of the expected directory paths

( 79, 4) Cannot connect t o dat a ser ver : info

For example, an invalid password has been used

( 79, 5) Cannot send r equest t o dat a ser ver : info

For example, a networking problem has interruptedcommunications (info will show the request that has failed)

( 79, 6) Er r or r et ur ned: info

Reason appended to the message by the data server

( 79, 7) Request f ai l ed: info

For example, an invalid data server command has been entered

( 79, 8) Cannot f et ch next r ow: info

For example, a network interruption or a data server error hasoccurred while waiting for the result of an EXTERNAL GET ...NEXT request (see Setting Variables from the Data ServerResponses)

( 79, 9) Command i s t oo l ong

The command has exceeded the limit of 4095 characters (dontforget the separating spaces when summing the lengths of theindividual command strings)

( 79, 10) No mor e dat a

For example, the most recent EXTERNAL GET ...NEXTcommand has failed because there are no more rows of data toretrieve. This is a very useful error number to trap, since it allowsthe user to use an infinite DO loop to retrieve consecutive rowsfrom a table of any length and then to escape when all the rowshave been read; the user will find an example of the syntax fordoing this in Section Setting Variables from the Data Server

Responses.


14/29

12.02:8



The text of a data server error message is usually explicit, since it is generated from thedatabase, and so its meaning, and the method of resolving it, should be clear. For example,if the user is communicating with an ORACLE database, the command

EXTERNAL SEND $! ! MAI NT sel ect * f r om emp

could result in the error

( 79, 7) Request f ai l ed: ORA- 00942: t abl e or vi ew does notexi st

Similarly, the command

EXTERNAL SEND $! ! MAI NT sel ect * f r om emp

could result in the error

( 79, 7) Request f ai l ed: ORA- 00904: i nval i d SQL stat ement

Communications Software Messages:

Note: These are most likely to be caused by general network problems rather than byQuery itself.

( 79, 51) Cannot i ni t i al i se r emot e pr ocess quer y

( 79, 52) Connect ed t o dat a ser ver ( f or i nf or mat i on onl y -cannot be rel eased)

( 79, 53) Dat a server r el eased ( f or i nf ormat i on onl y -cannot be rel eased)

( 79, 54) Cannot set del i mi t er char act er : info

(79, 55) Cannot termi nate server daemon: info

( 79, 56) Daemon f i l e i ncor r ect or mi ssi ng

( 79, 57) Unknown daemon synonym: info

Check that the required synonym has been entered correctly andthat it is included in the daemon_file

( 79, 58) Cannot t oggl e t r aci ng i n ser ver daemon: info

( 79, 59) No l i censes avai l abl e f or r emot e pr ocess quer y

The maximum number of communication channels (daemons)permitted by the users license are already open. Close anunwanted channel if possible

( 79, 60) Remot e pr ocess quer y secur i t y er r or : info

Contact AVEVA Support for advice

( 79, 63) Ser ver daemon has shut down because a FATAL er r orwas det ect ed


15/29


Command Syntax

12.03:1

3 Command Syntax

The Command Syntax section gives detailed information on how to use the relevantcommands for using Query to communicate with other data servers.

The commands described in the main part of this section have their legal command andinterrogation options presented in the form of syntax diagrams. These diagrams formalisethe precise command sequences which may be used and supplement the explanationsgiven in the appropriate sections of this manual.

The following conventions apply to the syntax diagrams in this section:

Names written in lowercase letters enclosed in angled brackets (e.g. )represent subsidiary syntax diagrams. Such names are used for cross-referencepurposes within other syntax diagrams.

Commands to be input from the terminal are shown in a combination of uppercase andlowercase letters. In general, these commands can be abbreviated; the capital letters

indicate the minimum permissible abbreviation.

Note: Using this convention does not mean that the second part of the command must be

typed in lowercase letters; commands may be entered in any combination ofuppercase and lowercase letters.

For example, the command

CONnect

may be input in any of the following forms:

CONCONNCONNECONNECCONNECT

Commands shown wholly in uppercase letters cannot be abbreviated.

Names written in lowercase italics are command arguments.

Syntax diagrams are generally read from top left to bottom right.

Points marked with a plus sign (+) are option junctions which allow you to input anyone of the commands to the right of the junction. Thus

>- - - +- - - ABC - - - - - .| || - - - PQR - - - - - || || - - - - - - || | - - - - - - - - - - - - - +- - - >


16/29

12.03:2


Command Syntax

means the user can type in ABC or PQR or any command allowed by the syntax givenin subsidiary syntax diagram orjust press RETURN to get the default option.

points marked with an asterisk (*) are loop back junctions. Command options

following these may be repeated as required. Thus . - - - - - - - - * - - - opt i on1 - - - | | | | - - - opt i on2 - - - | | | - - - opt i on3 - - - +- - - >

permits any combination of option1 and/or option2 and/or option3 to be used (wherethe options may define commands, other syntax diagrams, or command arguments).Using this may form an exception to the rule of reading from top left to bottom right.

The simplified format

. - - - - - - - * - - - name - - - +- - - >

means that you may type in a list of names, separated from each other by at least onespace.

Note: The need to press the Return (or Enter or ) key to complete each command line

is implicit in all syntax diagrams and is not usually shown. Only in cases where the

need to press Return/Enter/ has some particular significance is this indicated

specifically by the abbreviation nl.

3.1 Command ArgumentsCommand Arguments are inputs which are necessary to qualify command words. They aredistinguished by appearing in italics.

3.2 Commands

The information is given under the following headings:

Name Definition Example

filename The pathname of a file /DATLISTS/SITE1

int A positive integer 0, 3

name An element name /ABCD

nodeid A host machine identifier pc36

text An alphanumeric string Enclose between quote marks

val A positive or negative number 3.142, -23.66, -34

varid A variable identifier 3, !NAME

nl New line Press Return or Enter or key

(depending on your keyboard


17/29


Command Syntax

12.03:3

Description:

A brief explanation of what the command enables the user to do and when the user mightuse it.

Example:

Examples of the permitted command variations. (Examples are omitted in trivial cases.)

Syntax:

The full command syntax, given in diagrammatic form.

3.2.1 CLOSE

Description:

Disconnects Query from a specified data server (to which it is currently connected as aresult of an OPEN command).

Example:

EXTERNAL CLOSE $!! MAI NT

Syntax:

>- - EXTERnal - - CLOse - - token -->

where:

token is the token for the communication channel which was supplied by a successfulOPEN command and which is stored in a variable.

3.2.2 DELIMIT

Description:

Allows the user to specify the delimiting character which separates the individual data fieldswhen querying a specified data server. The default delimiter is the ~ (tilde) character.

Example:

EXTERNAL DELI MI T $! ! TOK_VAR &

Syntax:

>- - EXTERnal DELI mi t server_token text_char - - >

where:

server_token is an integer identifying the required data server channel and text is asingle character only.

Note: The user must choose a delimiting character which does not occur within any data,otherwise Query will split the incoming data string in the wrong place.


18/29

12.03:4


Command Syntax

3.2.3 END

Description:

Terminates the sending of a long command string to a data server.

All command lines following a START entry will be concatenated to form a compositecommand of any required length until terminated by a corresponding END entry.

The maximum length for a single query line is 120 characters.

The maximum total length for the overall query string (i.e. all lines between the START andEND commands) is 4095 characters.

Example:

EXTERNAL SEND $! ! MAI NT START sel ect r ef no, ser vi nt , l ast ser v f r ommai ntdata

wher e el ement t ype = EQUI PMENT END

Note: The use of multiple delimiting characters for nesting text within text in this example.You could, alternatively, write the example using vertical bar text delimiters, thus:


| sel ect r ef no, ser vi nt , l ast ser v f r om mai nt dat a|| where el ement t ype = EQUI PMENT |

END

Syntax:

. - - - - - - - EXTERnal SENd ser ver _ t oken START - - *- - t ext nl - - +- - END - - >

where:

server_tokenis an integer identifying the required data server channel.

3.2.4 EXTERNAL

Description:

Allows the user to send to a specified data server any valid text string which represents a

command to read from, or write to, a database.For details of subsidiary commands relevant to EXTERNAL mode, see under the followingheadings:

CLOSE

DELIMIT

END

GET

OPEN

SEND

START

TOGGLE


19/29


Command Syntax

12.03:5

Example:

EXTERNAL SEND $! ! MAI NT sel ect * f r om mai nt dat a

This sends the specified text string to the data server whose channel token is stored inthe variable !!MAINT.

Syntax:

>- - EXTERnal . . . - - >

3.2.5 GET

Description:

Allows the user to set to data values returned from a data server (using NEXT). Note that allof the standard syntax for setting is available for use within Query.

Also allows the user to store the column headings returned by a data server query in anarray variable (using RESULTor HEADER).

Example:

VAR ! dat ar ow EXTERNAL GET $! ! MAI NT NEXT VAR ! header EXTERNAL GET $! ! MAI NT RESULT

Syntax:

>- VAR varname EXTERnal GET token - +- NEXT - - - - - - - .| || - RESul t - - - - - || |

- HEADer - - - - - +- - - >

where:

tokenis the token for the communication channel which was supplied by a successfulEXTERNAL OPEN command (and stored in the token_varvariable).

varnamewill be interpreted automatically as an array variableand each data item willbe stored in a separate element of the array. (The PML SPLIT command is notrequired here; splitting is carried out automatically.)

Note: RESULTand HEADERcommands always return the firstrow of the result of the lastrequest sent to the data server identified by token (typically, but not necessarily,header information resulting from an SQL database SELECT command).

As with the data fields, no heading should be longer than 120 characters. If aheading exceeds 120 characters, nothingwill be returned by the query.

3.2.6 OPEN

Description:

Connects Query to a specified data server (via a server daemon).

Many communication channels may be open concurrently, each being identified by a token(an integer) which is returned by the server and stored in a named variable for subsequentreference.


20/29

12.03:6


Command Syntax

Example:

EXTERNAL OPEN MAI NTENANCE ! ! MAI NT AS bul l / r ober t

EXTERNAL OPEN MAI NTENANCE ! ! MAI NT ON pc35 AS bul l /robert

Syntax:

>- EXTERnal OPEn synonym t oken_var - +- ON hosti d- .| | - - - - - - - - - - - - +- AS connect _st r i ng - .

| | - - - - - - - - - - - - - - - - - - - - - +- >

where:

synonym is a text string which identifies the server daemon through whichcommunication is to be channelled. The synonyms must be defined in the

daemon_file- refer to Appendix A.token_var identifies a variable to be used to store the integer token returned by theserver when the communication channel is successfully opened. The user uses thesetting of this variable for all subsequent references to that server daemon.

hostid is a text string which identifies the node on which the server daemon resides(not required for ODBC or if the daemon is running on the same node as Query).

connect_string is any text string needed to allow you to connect/login to the dataserver (typically contents and database name, username and password).

3.2.7 SEND

Description:

Allows the user to send a command string to a specified data server.

The user can send short command strings (up to 120 characters) within the SENDcommand line, or the user can concatenate multiple command strings by using the STARTand END commands (q.v.).

Example:

EXTERNAL SEND $! ! MAI NT commi t

Syntax:

>- - EXTERnal SENd server_token t ext - - >

3.2.8 START

Description:

Allows the user to send a long command string to a specified data server (by extending theSEND command).

All command lines following a START entry will be concatenated to form a compositecommand of any required length until terminated by a corresponding END entry.

The maximum length for a single query line is 120 characters.


21/29


Command Syntax

12.03:7

The maximum total length for the overall query string (i.e. all lines between the START andEND commands) is 4095 characters.

Example:EXTERNAL SEND $! ! MAI NT START sel ect r ef no, ser vi nt , l ast ser v f r ommai ntdata wher e el ement t ype = EQUI PMENT END

Note: The use of multiple delimiting characters for nesting text within text in this example.The user could, alternatively, write the example using vertical bar text delimiters,thus:


| sel ect r ef no, ser vi nt , l ast ser v f r om mai nt dat a|

| where el ementt ype = EQUI PMENT |

END

Syntax:

. - - - - - - - - - - - - - . / | >- - EXTERnal SENd ser ver _t oken START - - *- - t ext - nl - - +- - END - - >

where:

server_tokenis an integer identifying the required data server channel.

3.2.9 TOGGLE

Description:

Allows the user to toggle on or off any tracing facilities built into a server daemon.

Example:

EXTERNAL TOGGLE $! ! MAI NT TRACE

Syntax:

>- - EXTERnal TOGgl e server_token TRAce - - >


22/29

12.03:8


Command Syntax


23/29


Query and ODBC

12.0A:1

A Query and ODBC

A.1 ODBC Architecture

All of those AVEVA products that incorporate Query functionality have the potential toaccess data controlled by external systems. The Query products communicate with the data

servers via the ODBC interface.


24/29

12.0A:2


Query and ODBC

In the figure overleaf:

Query processes macro commands and submits Structured Query Language (SQL)commands for direct execution and retrieves results. The SQL commands are

expressed in the dialect of the particular ODBC driver but with the option of using driverindependent ODBC escape sequences for some values and syntax elements.

ODBC Driver Managerloads and unloads drivers on behalf of Query and processesODBC requests or passes them to an ODBC driver.

ODBC Driver processes ODBC requests, submits SQL requests to a specific datasource, and returns results to Query. If necessary, the driver modifies an applicationsrequest so that the request conforms to syntax supported by the associated database.

Data source consists of the data the user wants to access and its associatedmanagement system and network communications (if any) used to access it.

When making a connection to a database, ODBC uses a Data Source Name (DSN). EachDSN fully specifies the database including the identity of the ODBC driver and whateverdriver specific information it requires.

The ODBC Administrator is a desktop program that configures and manages data sources.The user can run it to create a DSN and either select an existing database file or create anew one. The ODBC Administrator prompts the user for the driver to use and then uses itwhile prompting for driver specific information and completing its operations.

The DSN forms part of a connection string which may include other optional parameterssuch as user name and password.

Note: For all ODBC connections that the ON hostid clause of the EXTERNAL OPENcommand is not used. All the information it needs is supplied by the DSN any otherparts of the connection string.

In the following sections there are some general details of ODBC, its components and

facilities. For more information, refer to the appropriate ODBC document or help file.

A.2 Connection Strings

A connection string consists of a number of parameter definitions, each of which has akeyword, an = character and a value. A semicolon separates each parameter definitionfrom the next and is also placed at the end of the string. For example:

DSN=MyDB; UI D=myname; PWD=mypasswor d;

Usually, the DSN, UIDand PWDkeywords are the only keywords that are needed.

The following table describes the attribute values of all the common keywords:

Keyword Att ribute value descr iption

DSN Name of a data source.

FILEDSN Name of a .DSN file from which a connection string will be built for the datasource.

DRIVER Description of the driver. For example, Rdb or SQL Server.

UID A user ID.


25/29


Query and ODBC

12.0A:3

A.3 Special Facilities

Query includes some general enquiry facilities for DSN's and ODBC driver names andprovides access to them using the same method used for tables of an ODBC data source.The DSN to use to access this information isAdminSpecialand the table names are DSNand Drivers. They make it possible for a user interface designer to create a selection ofavailable DSN's from which to make a connection. Here are the main Query commands for

AdminSpecial and the only supported SQL commands:

ext er nal open | synonym| ! ! TOK as | DSN=Admi nSpeci al ; |external send $! ! TOK | sel ect * f rom DSN|exter nal send $! ! TOK | sel ect * f r omDr i ver s |ext ernal cl ose $!TOK

The external open command requires a valid synonym for ODBC.

Here is an example of a macro to read all of the available DSNs into a list gadget:

PWD The password corresponding to the user ID or an empty string if there is

none (PWD=;).

SAVEFILE The file name of a .DSN file in which the attribute values of keywords usedin making the present, successful connection should be saved.

Keyword Att ribute value descr iption


26/29

12.0A:4


Query and ODBC

Important: It is important to remember that these facilities are not based on the systemODBC libraries and that the commands that are shown are the only ones thatare supported.

Example:

$* cl ear t he user i nt erf ace gadgets var _PARA1 | |$* cl ear t he user i nt erf ace gadgets var _PARA1 | | var l i st _TABLE1 cl ear exi t

$* connect t o t he Admi nSpeci al DSN ext ernal open | ODBC| ! TOK as | DSN=Admi nSpeci al ; | handl e any err or | $!! ERROR. TEXT| endhandl e

$* sel ect al l of t he r ecor ds f r om t he DSN t abl e ext er nal send $! TOK | sel ect * f r omDSN| handl e any err or | $!! ERROR. TEXT| endhandl e$* f etch the f i r st col umn header t o t he paragraph gadget var ! HEAD del et e var ! HEAD ext er nal get $!TOK HEADER handl e any err or | $!! ERROR. TEXT| endhandl e var _PARA1 (t r i m( vtext ( ! HEAD[ 1] ) ) )

do var ! I NFO del ete var ! I NFO external get $!TOK NEXT handl e ( 79, 10 ) break $* end of dat a endhandl e var l i st _TABLE1 add ( t r i m( vtext ( ! I NFO[ 1] ) ) ) exi t enddo$* cl ose t he connect i on ext er nal cl ose $! TOK handl e any err or | $!! ERROR. TEXT| endhandl e

return


27/29


Query and ODBC

12.0A:5

A.4 SQL Escape Sequences in ODBC

A number of SQL language features, such as outer joins and scalar function calls, tend to be

implemented by providers in a database-specific form, which can happen even wherestandards bodies have defined standard syntaxes. For that reason, ODBC has defined itsown escape sequences for some standard syntaxes. These language features are:

Date, time, timestamp, and datetime interval literals

Scalar functions such as numeric, string, and data type conversion functions

LIKE predicate escape character

Outer joins

Procedure calls

The escape sequence is recognised and parsed by ODBC drivers, which replace theescape sequences with the correct database-specific grammar. Note however, that thedrivers only support those escape sequences that they can map to underlying language

features. For example, if the data source does not support outer joins, neither will the driver.It is thus possible to choose to use either the ODBC escape sequence or the database-specific syntax. However, applications that use the database-specific syntax will not beinteroperable.

ODBC escape sequences are enclosed in braces, e.g. {extension}. Examples of some typesof escape sequence are as follows:

Date, time, and timestampescape sequence literals are:

{l i teral - t ype ' val ue' }

e.g. {d '2009-06-30'}

where literal-type is one of the following:

literal-type Meaning Format of value

d Date yyyy-mm-dd

t Time hh:mm:ss

ts Timestamp yyyy-mm-dd hh:mm:ss[.f...]


28/29

12.0A:6


Query and ODBC


29/29

Index


C

CommandsAbbreviations . . . . . . . . . . . . . . . . . . 3:1AS. . . . . . . . . . . . . . . . . . . . 2:1, 2:2, 3:5CLOSE . . . . . . . . . . . . . . . . . . . 2:2, 3:3DELIMIT . . . . . . . . . . . . . . . . . . 2:6, 3:3END . . . . . . . . . . . . . . . . . . . . . 2:3, 3:4EXTERNAL . . . . . . . . . . . . . . . 2:1, 3:4

GET . . . . . . . . . . . . . . . . . . 2:4, 2:5, 3:5HEADER . . . . . . . . . . . . . . . . . 2:5, 3:5NEXT . . . . . . . . . . . . . . . . . . . . 2:4, 3:5ON . . . . . . . . . . . . . . . . . . . . . . 2:2, 3:5OPEN . . . . . . . . . . . . . . . . . 2:1, 2:2, 3:5RESULT . . . . . . . . . . . . . . . . . . 2:5, 3:5SEND . . . . . . . . . . . . . . . . . 2:3, 3:4, 3:6START . . . . . . . . . . . . . . . . . . . 2:3, 3:6TOGGLE . . . . . . . . . . . . . . . . . . . . . 3:7TRACE . . . . . . . . . . . . . . . . . . . . . . . 2:2

D

Data Field DelimiterSpecifying. . . . . . . . . . . . . . . . . . . . . 2:6

Data ServerConnecting Query . . . . . . . . . . . . . . 2:1Directing Commands . . . . . . . . . . . . 2:1Sending Commands. . . . . . . . . . . . . 2:3Setting Variables from Responses . . 2:4

E

Environmental Setup Requirements . . . . 2:2Error messages

Server daemon. . . . . . . . . . . . . . . . . 2:7

ErrorsHandling Returned. . . . . . . . . . . . . . 2:7

O

ODBCArchitecture . . . . . . . . . . . . . . . . . . . A:1SQL Escape Sequences . . . . . . . . .A:5

S

Synonym (data server). . . . . . . . . . . 2:1, 3:5

T

Token . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5(data server) . . . . . . . . . . . . . . . 2:1, 3:5

query reference manual

Documents