AVEVA Query Reference Manual

Query
Reference Manual
AVEVA Solutions Limited
Disclaimer
1.1 AVEVA does not warrant that the use of the AVEVA software will be uninterrupted, error-free or free from
viruses.
1.2 AVEVA shall not be liable for: loss of profits; loss of business; depletion of goodwill and/or similar losses; loss of
anticipated savings; loss of goods; loss of contract; loss of use; loss or corruption of data or information; any
special, indirect, consequential or pure economic loss, costs, damages, charges or expenses which may be
suffered by the user, including any loss suffered by the user resulting from the inaccuracy or invalidity of any data
created by the AVEVA software, irrespective of whether such losses are suffered directly or indirectly, or arise in
contract, tort (including negligence) or otherwise.
1.3 AVEVA's total liability in contract, tort (including negligence), or otherwise, arising in connection with the
performance of the AVEVA software shall be limited to 100% of the licence fees paid in the year in which the user's
claim is brought.
1.4 Clauses 1.1 to 1.3 shall apply to the fullest extent permissible at law.
1.5 In the event of any conflict between the above clauses and the analogous clauses in the software licence under
which the AVEVA software was purchased, the clauses in the software licence shall take precedence.
Copyright
Copyright and all other intellectual property rights in this manual and the associated software, and every part of it
(including source code, object code, any data contained in it, the manual and any other documentation supplied
with it) belongs to, or is validly licensed by, AVEVA Solutions Limited or its subsidiaries.
All rights are reserved to AVEVA Solutions Limited and its subsidiaries. The information contained in this document
is commercially sensitive, and shall not be copied, reproduced, stored in a retrieval system, or transmitted without
the prior written permission of AVEVA Solutions Limited. Where such permission is granted, it expressly requires
that this copyright notice, and the above disclaimer, is prominently displayed at the beginning of every copy that is
made.
The manual and associated documentation may not be adapted, reproduced, or copied, in any material or
electronic form, without the prior written permission of AVEVA Solutions Limited. The user may not reverse
engineer, decompile, copy, or adapt the software. Neither the whole, nor part of the software described in this
publication may be incorporated into any third-party software, product, machine, or system without the prior written
permission of AVEVA Solutions Limited, save as permitted by law. Any such unauthorised action is strictly
prohibited, and may give rise to civil liabilities and criminal prosecution.
The AVEVA software described in this guide is to be installed and operated strictly in accordance with the terms
and conditions of the respective software licences, and in accordance with the relevant User Documentation.
Unauthorised or unlicensed use of the software is strictly prohibited.
© Copyright 1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved. AVEVA shall
not be liable for any breach or infringement of a third party's intellectual property rights where such breach results
from a user's modification of the AVEVA software or associated documentation.
AVEVA Solutions Limited, High Cross, Madingley Road, Cambridge, CB3 0HB, United Kingdom
Trademark
AVEVA and Tribon are registered trademarks of AVEVA Solutions Limited or its subsidiaries. Unauthorised use of
the AVEVA or Tribon trademarks is strictly forbidden.
AVEVA product/software names are trademarks or registered trademarks of AVEVA Solutions Limited or its
subsidiaries, registered in the UK, Europe and other countries (worldwide).
The copyright, trademark rights, or other intellectual property rights in any other product or software, its name or
logo belongs to its respective owner.
Query Reference Manual
Revision Sheet
Date Version Comments / Remarks

September 2011 12.1.1 Issued
January 2012 Copyright added to all pages.
Contents Page
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

Directing 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
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3
CLOSE
DELIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:3
END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4
EXTERNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:4
GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
© Copyright 1974 to current year. i 12 Series

AVEVA Solutions Limited and its subsidiaries.
All rights reserved.
OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:6
SEND
START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:6
TOGGLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:7
Query and ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A:1

ODBC Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:1
Connection Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:2
Special Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:3
SQL Escape Sequences in ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A:5
© Copyright 1974 to current year. ii 12 Series

Introduction
1 Introduction
Query is a flexible way to access and manipulate the contents of outside databases from
within its products. It provides for a two-way flow of data between application programs and
local or remote databases using Structured Query Language (SQL) as its database access
language. 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 macros
to 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 programmable
engineering database system.
Query supports Open Database Connectivity (ODBC), an interface standard for database
access. 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 of
the different ways in which the functionality is provided, except of course when Query or the
database is configured.
1.1 Who this Manual is Meant For

The Query Reference Manual describes the Query command syntax which you can use to
set up links between Plant and an external database. It is intended for those who need to
write application macros for use from within those products, the principal purpose of such
macros 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 writing
such macros, nor does it tell you how you should document the ways in which end-users
should use your macros and their controlling interfaces.
The manual assumes that you have some prior experience of programming and that you are
already familiar with the following aspects:
• The functions of Plant and the ways in which these are controlled via the standard user
interface.
• The data server commands necessary to insert, delete, query and protect data in your
chosen database.
• The concepts of writing and running macro command files, including the use of
Programmable Macro Language (PML), as detailed in the Software Customisation
Guide.
• The design and implementation of a forms and menus graphical user interface.
© Copyright 1974 to current year. 1:1 12 Series

Introduction
1.2 Guide Structure

The Query Reference Manual is divided into the following sections:
Communicating Using Query describes the basic principles of using Query,

including some top-level commands which apply
during its use.
Command Syntax is the commands reference section and describes the

command syntax which you can use to control Plant
from within Query.
Query and ODBC describes the ODBC architecture used by Query with
its setup requirements and special features.
1.3 Conventions used in the Text

The following conventions are used throughout this manual to highlight certain features of
the 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 minimum
permissible abbreviation. Where a command word is first introduced, or where its use
is 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
Example of Input/Output Sequence Typeface
• Character strings which begin with the slash character / are either names of elements
in 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 command
syntax diagrams. For example, <diagram_name>.

Communicating Using Query
2 Communicating Using Query
The Communicating Using Query section explains the commands available within Query for
accessing an external database, such as a remote source on a data sever. Data settings
can be read from, or written to the data server. It also explains how the user can store and
manipulate 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 between
the two.
To connect Query to a data server which is installed on the same machine, use one of the
commands:
EXTERnal OPEn synonym token_var

EXTERnal OPEn synonym token_var [AS connect_string]
where synonym is a text string which identifies the server daemon through which
communication 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 be
written; and (if your data server requires login data) connect_string is a text string which
confirms the users access rights (such as their username and password).

Example:
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT AS ’bull/robert’

or
EXTERNAL OPEN ’ODBC’ !!MAINT AS ’DSN=MAINTDAT;’
To connect Query to a data server which is installed on a different machine, use the
extended form of the command
EXTERnal OPEn synonym token_var ON host [AS connect_string]
where synonym, token_var and connect_string are as above and host is a text string which
identifies the node on the network on which the server daemon. For example, to connect to
a data server on a machine called pc35, enter
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT ON ’pc35’ AS ’bull/
robert’
or, alternatively, a generalised version such as
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT ON ’sqlnet’ AS ’bull/
robert’
where the alias ‘sqlnet’ has been defined so as to point to the current host for, say, an SQL
database server.
To disconnect Query from a data server to which it is currently connected, use the command
EXTERnal CLOse token
where token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token_var variable).
Example:
EXTERnal CLOse $!!MAINT
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 ODBC
drivers will be set to this log file instead of the ODBC default filename. Trace output is
switched on and off with the EXTERNAL TRACE command.
Note: The ODBC Data Source Administrator also provides control over this logging.

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 an
SQL 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 newline character is
entered to terminate the command line.
• In continuous mode, such that a sequence of command lines is concatenated and sent
as a single command string. The maximum length for an individual command line is
120 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:
EXTERnal SENd token command_text
EXTERNAL OPEN command (and stored in the token_var variable) and command_text is
the command string to be sent to the data server.
Example:
EXTERNAL SEND $!!MAINT ’commit’
To send a continuous command sequence to the data server, use the syntax
EXTERnal SENd token STArt

command_text_1
command_text_2
...
END
EXTERNAL OPEN command (and stored in the token_var variable) and command_text_1
etc. are the command strings to be sent to the data server.
Example:
EXTERNAL SEND $!!MAINT START

’select refno, description, datedue’
’from maintdata’
’where datedue<sysdate+7’
END
where each line of command text is terminated by a newline character.

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 the
START 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 data
server.
To set a variable to the next row of data resulting from a data server query, use the syntax
VAR varname EXTERnal GET token NEXT
EXTERNAL OPEN command (and stored in the token_var variable). The variable varname
will be interpreted automatically as an array variable and each data item will be stored in a
separate element of the array. (The PML SPLIT command is not required here; splitting is
carried out automatically.)
Note: No data field should be longer than 120 characters, since this is the maximum
permitted length that can be stored in a variable. If a data field exceeds 120
characters, nothing will be returned by the query.
As an example, the querying command

EXTERNAL SEND $!!MAINT ’select refno, servint, lastserv
from maintdata’ VAR !datarow EXTERNAL GET $!!MAINT NEXT
might return the following results:
$!datarow[1] C1101 (first value of field refno)

$!datarow[2] 182 (first value of field servint)
$!datarow[3] 22-JAN-10 (first value of field lastserv)
Repeating the command

VAR !datarow EXTERNAL GET $!!MAINT NEXT
will retrieve the next data record, which will progressively overwrite the current settings of
the array element elements. For example,
$!datarow[1] E1201 (second value of field refno)

$!datarow[2] 31 (second value of field servint)
$!datarow[3] 07-JAN-10 (second value of field lastserv)

and so on for subsequent data records. If the newly read record has less completed fields
than the preceding record, some elements of the array variable will remain with their
previous 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 10
of the array variable, rather than starting from element 1 by default, the user could use the
syntax
VAR !datarow[10] EXTERNAL GET $!!MAINT NEXT
To read a record and append the resulting data to the array variable, rather than overwriting
the current settings of the array elements, the user could use the syntax
VAR !datarow APPEND EXTERNAL GET $!!MAINT NEXT
and so on.
The most convenient way to retrieve multiple data records is usually to incorporate the
NEXT command into a PML ‘infinite’ DO loop construct, reading one data record during
each cycle of the loop. When the last record has been read in, the next cycle of the loop will
generate the message
(79, 10) No more data
which can be dealt with by using the PML HANDLE facility. For example:
EXTERNAL SEND $!!MAINT ’select * from maintdata’

DO
HANDLE (79, 10)
BREAK
ENDHANDLE
PML commands
...
ENDDO
To set the column headings returned by a data server query in an array variable, use either
version of the following syntax:
VAR varname EXTERnal GET token RESult

VAR varname EXTERnal GET token HEADer
These commands always return the first row of the result of the last request sent to the data
server identified by token (typically, but not necessarily, header information resulting from an
SQL database SELECT command).
For example, the querying command
VAR !header EXTERNAL GET $!!MAINT RESULT

might return the following results:
$!header[1] refno
$!header[2] servint
$!header[3] lastserv
Note: As with the data fields, no heading should be longer than 120 characters. If a
heading exceeds 120 characters, nothing will 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 data
field 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 the
points at which to split the data into individual fields. If the data includes the delimiter
character within a text field, Query will split the data block at the wrong point.
For example, the data stored in the following fields:
Area Catalytic Cracker

Plant Reflux~Heater
Code DES21142
would be received by Query, using the default ~ delimiter, as the data block
Catalytic Cracker~Reflux~Heater~DES21142
and would be split, incorrectly, into the fields
$!a[1] Catalytic Cracker

$!a[2] Reflux
$!a[3] Heater
$!a[4] DES21142
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
EXTERnal DELImit token text_char
EXTERNAL OPEN command (and stored in the token_var variable) and text_char is the
required data field delimiter character.
For example, the specification
EXTERNAL DELIMIT $!!MAINT ’&’
would cause the data block from the preceding example to be received as

Catalytic Cracker&Reflux~Heater&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 the
following error messages (where info represents any supplementary information about the
error which is generated by the data server or the communications software).
Server Daemon Messages:
(79, 3) Cannot initialise server daemon: info

For example, the server daemon executable cannot be found via
any of the expected directory paths
(79, 4) Cannot connect to data server: info

For example, an invalid password has been used
(79, 5) Cannot send request to data server: info

For example, a networking problem has interrupted
communications (info will show the request that has failed)
(79, 6) Error returned: info

Reason appended to the message by the data server
(79, 7) Request failed: info

For example, an invalid data server command has been entered
(79, 8) Cannot fetch next row: info

For example, a network interruption or a data server error has
occurred while waiting for the result of an EXTERNAL GET ...
NEXT request (see Setting Variables from the Data Server
Responses)
(79, 9) Command is too long

The command has exceeded the limit of 4095 characters (don’t
forget the separating spaces when summing the lengths of the
individual command strings)
(79, 10) No more data

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

The text of a data server error message is usually explicit, since it is generated from the
database, 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 $!!MAINT ’select * from emp’
could result in the error
(79, 7) Request failed: ORA-00942: table or view does not
exist
Similarly, the command
EXTERNAL SEND $!!MAINT ’select * from emp’
could result in the error
(79, 7) Request failed: ORA-00904: invalid SQL statement
Communications Software Messages:
Note: These are most likely to be caused by general network problems rather than by
Query itself.
(79, 51) Cannot initialise remote process query

(79, 52) Connected to data server (for information only -
cannot be released)
(79, 53) Data server released (for information only -
cannot be released)
(79, 54) Cannot set delimiter character: info
(79, 55) Cannot terminate server daemon: info
(79, 56) Daemon file incorrect or missing
(79, 57) Unknown daemon synonym: info
Check that the required synonym has been entered correctly and
that it is included in the daemon_file
(79, 58) Cannot toggle tracing in server daemon: info

(79, 59) No licenses available for remote process query
The maximum number of communication channels (daemons)
permitted by the users license are already open. Close an
unwanted channel if possible
(79, 60) Remote process query security error: info

Contact AVEVA Support for advice
(79, 63) Server daemon has shut down because a FATAL error
was detected

Command Syntax
3 Command Syntax
The Command Syntax section gives detailed information on how to use the relevant
commands for using Query to communicate with other data servers.
The commands described in the main part of this section have their legal command and
interrogation options presented in the form of syntax diagrams. These diagrams formalise
the precise command sequences which may be used and supplement the explanations
given 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. <direction>)
represent subsidiary syntax diagrams. Such names are used for cross-reference
purposes within other syntax diagrams.
• Commands to be input from the terminal are shown in a combination of uppercase and
lowercase 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 of
uppercase and lowercase letters.
For example, the command

CONnect
may be input in any of the following forms:
CON
CONN
CONNE
CONNEC
CONNECT
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 any
one of the commands to the right of the junction. Thus
>---+--- ABC -----.
| |
|--- PQR -----|
| |
|--- <dia> ---|
| |
‘-------------+--->

Command Syntax
means the user can type in ABC or PQR or any command allowed by the syntax given
in subsidiary syntax diagram <dia> or just 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
.-----<-------.
/ |
>---*--- option1 ---|
| |
|--- option2 ---|
| |
‘--- option3 ---+--->
permits any combination of option1 and/or option2 and/or option3 to be used (where
the 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 one
space.
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 Arguments

Command Arguments are inputs which are necessary to qualify command words. They are
distinguished by appearing in italics.
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
3.2 Commands
The information is given under the following headings:

Command Syntax
Description:
A brief explanation of what the command enables the user to do and when the user might
use 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 a
result of an OPEN command).
Example:
EXTERNAL CLOSE $!!MAINT
Syntax:
>-- EXTERnal -- CLOse -- token -->
where:
token is the token for the communication channel which was supplied by a successful
OPEN 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 fields
when querying a specified data server. The default delimiter is the ~ (tilde) character.
Example:
EXTERNAL DELIMIT $!!TOK_VAR ’&’
Syntax:
>-- EXTERnal DELImit server_token text_char -->
where:
server_token is an integer identifying the required data server channel and text is a
single 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.

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 composite
command 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 and
END commands) is 4095 characters.
Example:
’select refno, servint, lastserv from maintdata’
’where elementtype = ’’EQUIPMENT’’’
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:

|select refno, servint, lastserv from maintdata|
|where elementtype = ’EQUIPMENT’|
END
Syntax:
.-----<-----.
/ |
>-- EXTERnal SENd server_token START --*-- text nl --+-- END -->
where:
server_token is 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 following
headings:
CLOSE
DELIMIT
END
GET
OPEN
SEND
START
TOGGLE

Command Syntax
Example:
This sends the specified text string to the data server whose channel token is stored in
the 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 all
of 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 an
array variable (using RESULT or HEADER).
Example:
VAR !header EXTERNAL GET $!!MAINT RESULT
Syntax:
>- VAR varname EXTERnal GET token -+- NEXT -------.
| |
|- RESult -----|
| |
‘- HEADer -----+--->
where:
token is the token for the communication channel which was supplied by a successful
EXTERNAL OPEN command (and stored in the token_var variable).
varname will be interpreted automatically as an array variable and each data item will
be stored in a separate element of the array. (The PML SPLIT command is not
required here; splitting is carried out automatically.)
Note: RESULT and HEADER commands always return the first row of the result of the last
request 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 a
heading exceeds 120 characters, nothing will 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 subsequent
reference.

Command Syntax
Example:
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT AS ’bull/robert’
EXTERNAL OPEN ’MAINTENANCE’ !!MAINT ON ’pc35’ AS ’bull/
robert’
Syntax:
>- EXTERnal OPEn synonym token_var -+- ON hostid-.
| |
‘------------+- AS connect_string -.
| |
‘---------------------+->
where:
synonym is a text string which identifies the server daemon through which
communication 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 the
server when the communication channel is successfully opened. The user uses the
setting 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 data
server (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 SEND
command line, or the user can concatenate multiple command strings by using the START
and END commands (q.v.).
Example:
EXTERNAL SEND $!!MAINT ’commit’
Syntax:
>-- EXTERnal SENd server_token text -->
3.2.8 START
Description:
Allows the user to send a long command string to a specified data server (by extending the
SEND command).
All command lines following a START entry will be concatenated to form a composite
command of any required length until terminated by a corresponding END entry.
The maximum length for a single query line is 120 characters.

Command Syntax
The maximum total length for the overall query string (i.e. all lines between the START and
END commands) is 4095 characters.
Example:
’select refno, servint, lastserv from maintdata’
’where elementtype = ’’EQUIPMENT’’’
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:

|select refno, servint, lastserv from maintdata|
|where elementtype = ’EQUIPMENT’|
END
Syntax:
.-------------.
/ |
>-- EXTERnal SENd server_token START --*-- text - nl --+-- END -->
where:
server_token is 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 $!!MAINT TRACE
Syntax:
>-- EXTERnal TOGgle server_token TRAce -->

Command Syntax

Query and ODBC
A Query and ODBC
A.1 ODBC Architecture

All of those AVEVA products that incorporate Query functionality have the potential to
access data controlled by external systems. The Query products communicate with the data
servers via the ODBC interface.
© Copyright 1974 to current year. A:1 12 Series

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 driver
independent ODBC escape sequences for some values and syntax elements.
• ODBC Driver Manager loads and unloads drivers on behalf of Query and processes
ODBC requests or passes them to an ODBC driver.
• ODBC Driver processes ODBC requests, submits SQL requests to a specific data
source, and returns results to Query. If necessary, the driver modifies an application’s
request 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 associated
management system and network communications (if any) used to access it.
When making a connection to a database, ODBC uses a Data Source Name (DSN). Each
DSN fully specifies the database including the identity of the ODBC driver and whatever
driver 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 a
new one. The ODBC Administrator prompts the user for the driver to use and then uses it
while prompting for driver specific information and completing its operations.
The DSN forms part of a connection string which may include other optional parameters
such as user name and password.
Note: For all ODBC connections that the ON hostid clause of the EXTERNAL OPEN
command is not used. All the information it needs is supplied by the DSN any other
parts 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 a
keyword, an ‘=’ character and a value. A semicolon separates each parameter definition
from the next and is also placed at the end of the string. For example:
DSN=MyDB;UID=myname;PWD=mypassword;
Usually, the DSN, UID and PWD keywords are the only keywords that are needed.
The following table describes the attribute values of all the common keywords:
Keyword Attribute value description

DSN Name of a data source.
FILEDSN Name of a .DSN file from which a connection string will be built for the data
source.
DRIVER Description of the driver. For example, Rdb or SQL Server.
UID A user ID.

Query and ODBC
Keyword Attribute value description

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 used
in making the present, successful connection should be saved.
A.3 Special Facilities

Query includes some general enquiry facilities for DSN's and ODBC driver names and
provides access to them using the same method used for tables of an ODBC data source.
The DSN to use to access this information is AdminSpecial and the table names are DSN
and Drivers. They make it possible for a user interface designer to create a selection of
available DSN's from which to make a connection. Here are the main Query commands for
AdminSpecial and the only supported SQL commands:
external open |synonym| !!TOK as |DSN=AdminSpecial;|
external send $!!TOK |select * from DSN|
external send $!!TOK |select * from Drivers|
external close $!TOK
The external open command requires a valid synonym for ODBC.

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

Query and ODBC
Example:
$* clear the user interface gadgets

var _PARA1 ||
$* clear the user interface gadgets
var _PARA1 ||
var list _TABLE1 clear
exit
$* connect to the AdminSpecial DSN

external open |ODBC| !TOK as |DSN=AdminSpecial;|
handle any
error |$!!ERROR.TEXT|
endhandle
$* select all of the records from the DSN table

external send $!TOK |select * from DSN|
handle any
endhandle
$* fetch the first column header to the paragraph gadget
var !HEAD delete
var !HEAD external get $!TOK HEADER
handle any
endhandle
var _PARA1 (trim(vtext(!HEAD[1])))
do
var !INFO delete
var !INFO external get $!TOK NEXT
handle ( 79, 10 )
break $* end of data
endhandle
var list _TABLE1 add (trim(vtext(!INFO[1])))
exit
enddo
$* close the connection
external close $!TOK
handle any
endhandle
return
Important: It is important to remember that these facilities are not based on the system
ODBC libraries and that the commands that are shown are the only ones that
are supported.

Query and ODBC
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 where
standards bodies have defined standard syntaxes. For that reason, ODBC has defined its
own 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 the
escape sequences with the correct database-specific grammar. Note however, that the
drivers 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 be
interoperable.
ODBC escape sequences are enclosed in braces, e.g. {extension}. Examples of some types
of escape sequence are as follows:
Date, time, and timestamp escape sequence literals are:
{literal-type 'value'}
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...]

Query and ODBC

Index
C Errors
Handling Returned . . . . . . . . . . . . . . 2:7
Commands
Abbreviations . . . . . . . . . . . . . . . . . . 3:1
AS . . . . . . . . . . . . . . . . . . . . 2:1, 2:2, 3:5
O
CLOSE . . . . . . . . . . . . . . . . . . . 2:2, 3:3 ODBC
DELIMIT . . . . . . . . . . . . . . . . . . 2:6, 3:3 Architecture . . . . . . . . . . . . . . . . . . . A:1
END . . . . . . . . . . . . . . . . . . . . . 2:3, 3:4 SQL Escape Sequences . . . . . . . . . A:5
EXTERNAL . . . . . . . . . . . . . . . 2:1, 3:4
GET . . . . . . . . . . . . . . . . . . 2:4, 2:5, 3:5
S
HEADER . . . . . . . . . . . . . . . . . 2:5, 3:5
NEXT . . . . . . . . . . . . . . . . . . . . 2:4, 3:5 Synonym (data server) . . . . . . . . . . . 2:1, 3:5
ON . . . . . . . . . . . . . . . . . . . . . . 2:2, 3:5
OPEN . . . . . . . . . . . . . . . . . 2:1, 2:2, 3:5 T
RESULT . . . . . . . . . . . . . . . . . . 2:5, 3:5
SEND . . . . . . . . . . . . . . . . . 2:3, 3:4, 3:6 Token . . . . . . . . . . . . . . . . . . . . . . . . . . . 3:5
START . . . . . . . . . . . . . . . . . . . 2:3, 3:6 (data server) . . . . . . . . . . . . . . . 2:1, 3:5
TOGGLE . . . . . . . . . . . . . . . . . . . . . 3:7
TRACE . . . . . . . . . . . . . . . . . . . . . . . 2:2
D
Data Field Delimiter
Specifying . . . . . . . . . . . . . . . . . . . . . 2:6
Data Server
Connecting Query . . . . . . . . . . . . . . 2:1
Directing Commands . . . . . . . . . . . . 2:1
Sending Commands . . . . . . . . . . . . . 2:3
Setting Variables from Responses . . 2:4
E
Environmental Setup Requirements . . . . 2:2
Error messages
Server daemon . . . . . . . . . . . . . . . . . 2:7
© Copyright 1974 to current year. Index page i 12 Series


AVEVA Query Reference Manual

Uploaded by

Copyright:

Available Formats

AVEVA Query Reference Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

AVEVA Query Reference Manual

Uploaded by

Copyright:

Available Formats

Query

Date Version Comments / Remarks

Query Reference Manual

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

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

© Copyright 1974 to current year. i 12 Series

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

© Copyright 1974 to current year. ii 12 Series

1.1 Who this Manual is Meant For

© Copyright 1974 to current year. 1:1 12 Series

1.2 Guide Structure

Communicating Using Query describes the basic principles of using Query,

Command Syntax is the commands reference section and describes the

1.3 Conventions used in the Text

© Copyright 1974 to current year. 1:2 12 Series

2 Communicating Using Query

2.1 Directing Commands to the Data Server

2.2 Connecting Query to a Data Server

EXTERnal OPEn synonym token_var

© Copyright 1974 to current year. 2:1 12 Series

EXTERNAL OPEN ’MAINTENANCE’ !!MAINT AS ’bull/robert’

EXTERnal OPEn synonym token_var ON host [AS connect_string]

EXTERnal CLOse token

EXTERnal CLOse $!!MAINT

2.3 Environmental Setup Requirements

© Copyright 1974 to current year. 2:2 12 Series

2.4 Sending Commands to a Data Server

EXTERnal SENd token command_text

EXTERNAL SEND $!!MAINT ’commit’

EXTERnal SENd token STArt

EXTERNAL SEND $!!MAINT START

where each line of command text is terminated by a newline character.

© Copyright 1974 to current year. 2:3 12 Series

Note: Command texts may include references to PML variables.

2.5 Setting Variables from the Data Server Responses

VAR varname EXTERnal GET token NEXT

As an example, the querying command

$!datarow[1] C1101 (first value of field refno)

Repeating the command

$!datarow[1] E1201 (second value of field refno)

© Copyright 1974 to current year. 2:4 12 Series

EXTERNAL SEND $!!MAINT ’select * from maintdata’

VAR varname EXTERnal GET token RESult

© Copyright 1974 to current year. 2:5 12 Series

might return the following results:

2.6 Specifying the Data Field Delimiter

Area Catalytic Cracker

$!a[1] Catalytic Cracker

EXTERnal DELImit token text_char

© Copyright 1974 to current year. 2:6 12 Series

2.7 Handling Returned Errors

Server Daemon Messages:

(79, 3) Cannot initialise server daemon: info

(79, 4) Cannot connect to data server: info

(79, 5) Cannot send request to data server: info

(79, 6) Error returned: info

(79, 7) Request failed: info

(79, 8) Cannot fetch next row: info

(79, 9) Command is too long

(79, 10) No more data