Extreme Networks EPICenter 4.1, Software Installation Manual

Page: 501 / 546

Tcl Client API
EPICenter Software Installation and User Guide 501
Query Function
#
# extr::query channel_id ?-raw | -decode flag | -command cmd? sql ?arg arg ...?
#
# Sends a sql command to the EPICenter server. Retrieves the result.
# The result of the command can be either an error message
# signaling that there is some syntax error about the sql
# command, or a table of data. The EPICenter server returns the
# data using its external protocol.
#
# Currently, only "Select ..." sql statement is accepted by the
# EPICenter server. The where clause of the sql statement may contain
# ’?’. For each ’?’, the caller must specify an additional
# argument containing the value to replace the ’?’ in the sql
# statement. For example:
#
# extr::query $cid \
# "select name_column from Table_A where name_column = ?" \
# "Bob’s Row"
#
# The string {Bob’s Row} replaces the ? in the sql query. In
# this example, the caller does not need to quote the string in
# the where clause of the sql statement.
#
# The result from the EPICenter server is a table encoded in HTML/XML
# style tags. The caller may choose to receive this data in its
# raw encoded form by using the "-raw" option. This function
# can also return the result already decoded into a list of list
# of cell data if -raw is not specified.
#
# The caller can optionally specify -command cmd. If this is
# specified, then the user supplied "cmd" is executed after each
# row of data is received. See below for the definition of the
# "cmd" callback function.
#
# cmd dataType dataValue
#
# dataType - one of ERROR, TABLE_BEGIN,
# COLUMN_NAME, COLUMN_TYPE,
# ROW_DATA, TABLE_FINISH.
# dataValue - the value returned from the server
#
# ERROR - The given dataValue is an error message
# returned by the server.
# TABLE_BEGIN - Begin of a table. If called with this
# type, then the dataValue is always {}
# COLUMN_NAME - The given dataValue is a list of column names
# returned by the database. This is the first
# thing returned by the server when there is no
# errors.
# COLUMN_TYPE - The given dataValue is a list of column types.
# This is the 2nd thing returned by the server
# when there are no errors.
# ROW_DATA - The given value is a list of column values
# for one data row.
# TABLE_FINISH - End of the table from the server. When