Kognitio Console Scripting and Macros - Amazon S3 · Then the SQL Script button will create a Kog...

Kognitio Console Scripting and Macros

Version 7.9.2 October 2012

Public

Notices This document contains proprietary information that should not be reproduced in whole or in part, nor released to third parties nor used for purposes other than those for which it has been expressly provided without the prior written agreement of Kognitio Limited.

Kognitio Limited tries to ensure that the information in this document is correct and fairly stated, but does not accept liability for any error or omission.

Kognitio Console Macro Guide, October 2012 Kognitio Technology Centre © Kognitio Limited, 2002-2012 3A Waterside Park, Cookham Road BRACKNELL, Berks, RG12 1RB United Kingdom

Preface

Data Definition iii

Public

Public Preface

Data Definition iii

About this Manual

This manual is part of a series that describes how Error! Reference source not found. can enhance the productivity of your interactive database applications.

The manual assumes that the reader is familiar with relational concepts and SQL.

The Kognitio Console Macro system is built on XML and Lua (http://www.lua.org/), it assumes that the reader is familiar with these.

Kognitio Scripts (‘Kog’ Scripts) are an extension of Lua 5.2 which make it easier to use for the purpose of SQL access of a database.

http://www.lua.org/

Data Definition v

Contents

About this Manual ................................................................................ iii

Contents .............................................................................................. v

1 Kog Scripting ................................................................................................... ix

1.1 Getting Started .......................................................................................... ix

1.2 Naked SQL................................................................................................ x

Global Variables .................................................................................. xi

SQL statements returning a table ........................................................ xii

Using $ substitution within SQL statements ......................................... xiv

1.3 KogScript command line tool ..................................................................... xiv

1.4 Using require in Kog scripts ....................................................................... xvi

Package Path ...................................................................................... xvii

1.5 What Happens “under the hood” ............................................................... xviii

1.6 Other Kognitio Extensions ......................................................................... xix

Shell .................................................................................................... xix

Table __toString() ................................................................................ xx

Mixed Lua and Kog scripts .................................................................. xx

Lua Lanes............................................................................................ xx

2 Data Definition ................................................................................................. 43

2.1 Data Items ................................................................................................. 43

Data Item ............................................................................................. 43

Column ................................................................................................ 45

Connectors .......................................................................................... 46

Connector ............................................................................................ 46

Domains .............................................................................................. 47

Domain ................................................................................................ 48

External Scripts ................................................................................... 48

External Script ..................................................................................... 49

Plugins ................................................................................................ 50

Plugin .................................................................................................. 51

Privileges ............................................................................................. 51

Privilege .............................................................................................. 52

Queues ................................................................................................ 54

Queue ................................................................................................. 54

Preface

Data Definition vi

Schemas ............................................................................................. 55

Schema ............................................................................................... 56

Script Environments............................................................................. 56

Script Environment .............................................................................. 57

SecClasses ......................................................................................... 58

SecClass ............................................................................................. 58

Sessions .............................................................................................. 59

Session................................................................................................ 60

Tables ................................................................................................. 61

Table ................................................................................................... 62

Users ................................................................................................... 63

User ..................................................................................................... 64

Views ................................................................................................... 65

View .................................................................................................... 65

3 Macro Elements ................................................................................................67

wx2macro ............................................................................................ 67

actiontext ............................................................................................. 69

dockable .............................................................................................. 69

kogscript .............................................................................................. 72

menu ................................................................................................... 74

name ................................................................................................... 75

objects ................................................................................................. 76

object ................................................................................................... 78

report ................................................................................................... 79

requiredserverversion .......................................................................... 82

script .................................................................................................... 83

sql ........................................................................................................ 87

<widget type=“button”> ........................................................................ 90

<widget type=“chart”> .......................................................................... 94

<widget type=“checkbox”> ................................................................... 95

<widget type=“combobox”> ................................................................. 96

<widget type=“groupbox”> ................................................................... 99

<widget type=“chart”> .......................................................................... Error! Bookmark not defined.

<widget type=“grid”> ............................................................................ 101

<widget type=“hbox”> .......................................................................... 101

<widget type=“image”> ........................................................................ 102

<widget type=“meter”> ......................................................................... 102

<widget type=“piechart”> ..................................................................... 107

Data Definition vii

<widget type=“radiobutton”> ................................................................ 108

<widget type=“server”> ........................................................................ 109

<widget type=“slider”> ......................................................................... 110

<widget type=“stretch”> ....................................................................... 111

<widget type=“table”> .......................................................................... 112

<widget type=“username”> .................................................................. 114

<widget type=“vbox”> .......................................................................... 115

4 Using KogScript In Macros ............................................................................. 118

A Quick Introduction To Lua ................................................................ 118

Kog Script Extensions ......................................................................... 121

Kog Script Built-in Functions ................................................................ 122

5 Using Old Style SQL Scripts In Macros ......................................................... 123

Variables ............................................................................................. 123

Assignment .......................................................................................... 124

Connect statement .............................................................................. 124

Describe Command ............................................................................. 124

Disconnect Statement ......................................................................... 124

Edit Command ..................................................................................... 124

Errorcode Command ........................................................................... 124

Errorcodenot Command ...................................................................... 125

Export Command ................................................................................. 125

Goto Command ................................................................................... 125

Help Command ................................................................................... 125

If Statement ......................................................................................... 125

Include Command ............................................................................... 126

Results Command ............................................................................... 126

Returncode Command......................................................................... 126

Set Statement ...................................................................................... 126

Setvar Command ................................................................................. 127

Shell Command ................................................................................... 127

Show Command .................................................................................. 128

Whenever Statement ........................................................................... 128

Quit Command .................................................................................... 128

Script variables .................................................................................... 129

Example 1: .......................................................................................... 130

Preface

Data Definition viii

6 Putting It All Together ......................................................................................132

How Macros Are Used ......................................................................... 132

Macro Directories ................................................................................ 134

Writing effective macros ...................................................................... 135

QuickViz - Creating macros the easy way ............................................ 135

A............................................................................................................................137

Index .....................................................................................................................137

Data Definition ix

1

Kog Scripting

In this Chapter we describe the Kognitio Scripting language (shortened to Kog Script). It is based on Lua 5.2, but has a number of extensions

1.1 Getting Started

Kog scripting is turned off by default in Console. It may be turned on in the Configuration dialog.

Preface

Data Definition x

Then the SQL Script button will create a Kog script. Now a Kog script may be entered and run with similar debugging facilities to the old SQL scripts.

Pure Lua scripts (i.e. without any Kognitio extensions) may be created by changing the “Script:” combo box to “Lua”.

1.2 Naked SQL

The main way that Kog scripts differ from Lua is that they may contain SQL statements, without having to be enclosed in quotation marks. This ‘Naked’ SQL may also include Lua variables and expressions.

SQL Statements return a Lua table holding the statement status and resultset from select statements. A few Lua global variables are also set, mainly for compatibility with old style SQL scripts. Let us start with a simple one line Kog script containing naked SQL.

select * from sys.ipe_user;

Click here to create a Kog script

This Combo box allows the script type to be changed.

Data Definition xi

This performs the select statement and sets some global variables. Note that all naked SQL must end with a ‘;’, this is different from Lua where terminating statements with ‘;’ is optional. Unlike Lua statements, SQL statements are case-insensitive. So the above script could have been written:

SELECT * FROM sys.ipe_user;

As well as select the following SQL keywords may also start SQL statements in Kog scripts: alter, commit, connect, create, defrag, delete, diagnose, disconnect, drop, explain, export, grant, insert, import, lock, merge, picture, reclaim, redistribute, rename, repack, revoke, rollback, set, truncate, update and with.

Global Variables

When a naked SQL statement is executed the following global variables are set:

variable value

cliver String, client version e.g.“7.09.01-s121122”

sysver String, system version e.g. “07.09.0002”

SQLState “OK”, or error string

WCSerror “OK” or error string

CompileTime Integer, milli-seconds

ExecuteTime Integer, milli-seconds

FirstRowTime Integer, milli-seconds

TotalTime Integer, milli-seconds

NumRows Integer, number of rows returned

NumColumns Integer, number of columns returned

QueryNumber Integer, number of queries performed in this script run.

Col1 String, Contents of row=1, column=1




Preface

Data Definition xii




There are also some global variables that are used to control how scripts are run, and what to do when errors are encountered.

Variable Contents

error_mode String, contents of “On server error” combo box. Set this to “continue”, “debug”, “stop” to change the action when an SQL error is encountered.

fail_mode String. Set this to “continue”, “debug”, “stop” to change the action when an error is encountered during testing.

NOTE: for Kognitio testing purposes, may change in future releases.

script_fail_mode String, contents of “On script fail” combo box. Set this to “continue”, “debug”, “stop” to change the action when a script fails.

history_mode String, contents of the “History mode:” combo box.

history_group String, contents of the “History group” text box. Controls the section in the query history following statements are placed in.

sqldebug Integer: Controls output to Console logs pane:

nil => no output 0 => no output 1 => “OK”, or “error” + error string, rows affected 2 => + times 3 => + resultset

SQL statements returning a table

Naked SQL Statements may also return a Lua table containing data about the query.

t = select * from sys.ipe_user;

Data Definition xiii

This table contains several values:

Table Variable Value

numRows Integer, Number of rows in the resultset.

numCols Integer, Number of columns in the resultset.

status Integer, 0=OK

colNames Table

rows Table

The colNames table contains an array of the column names, Lua uses tables indexed from 1 and so t.colnames[1] is the name of the first column.

The rows table contains an array of rows (which are tables), Lua uses tables indexed from 1 and so t.rows[1] is contents of the first row.

Each row is a Lua table which is indexed by the column names. So t.rows[1].id is the user id in the first row.

Here is a script to show all the output from a query:

t = select * from ipe_user; print("table\n") for i,v in pairs(t) do print(" ", i, v, " \n"); end; print("column names\n") for i,v in pairs(t.colNames) do print(" ", i, v, " \n"); end; print("rows\n") for i,row in pairs(t.rows) do print(" row "..i, " \n") for j, k in pairs(row) do print(" ", j, "=", k, " \n"); end; end; print("globals\n") for i,v in pairs(_G) do print(" ", i, v, " \n"); end;

Preface

Data Definition xiv

Using $ substitution within SQL statements

Kog scripts use ‘$’ to perform substitution with Lua variables and expressions within naked SQL.

$<variable>[ ( <some text> ) ] [ <space> | ‘ | $ | ; ]

A variable or Lua function call may end with a space, a single or double quote or a $

More complex Lua expressions need to be enclosed in matching ( ) .

$( <expression> ) [ <space> | ‘ | $ | ; ]

Example 1:

names = {'ipe_user', 'ipe_schema'} for i,v in pairs(names) do select * from sys.$v; end;

Example 2:

function name() return 'ipe_user' end t = select * from sys.$name();

Example 3:

1.3 KogScript command line tool

This is installed by the Kognitio Console installer on Windows, and is found in

C:\Program Files (x86)\Kognitio Ltd\wx2clients32\kogscript.exe (32 bit)

C:\Program Files\Kognitio Ltd\wx2clients64\kogscript.exe (64 bit)

The usage is:

kogscript.exe [options] [script [args]]

Available options are:

-e stat execute string "stat " -i enter interactive mode after executing "script"

Data Definition xv

-l name require library "name" -v show version information -E ignore environment variables -- stop handling options - stop handling options and execute stdin

On windows kogscript includes line editing and line history.

As for the Console version a variable called sqldebug controls the amount of info which is output after each SQL statement.

Kogscript may be exited by either ctrl-z or using os.exit().

Example 1:

>"C:\Program Files (x86)\Kognitio Ltd\wx2clients32\kogscript.exe" Kog Scripting - version: 7.02.01-s120808-michaela1 (32 bit) Lua 5.2.1 Copyright (C) 1994-2012 Lua.org, PUC-Rio > connect to latest user sys using albatros; > t = select * from >> ipe_user; > for i,v in pairs(t.rows) do print(v.name) end SYS GRP_DBG GRP_DISKUSAGE U1 U3 USER4 U GRP_MONITOR GRP_LOG ODBC U2 U4 U5 MIKE PUBLIC > ^Z

Example 2:

The following example runs the script listusers.kog:

print("Finding Users:")

Preface

Data Definition xvi

connect to latest user sys using albatros; t = select * from ipe_user; for i,v in pairs(t.rows) do print(v.name) end

Using kogscript like this:

>"C:\Program Files (x86)\Kognitio Ltd\wx2clients32\kogscript.exe" –i listusers.kog Kog Scripting - version: 7.02.01-s120808-michaela1 (32 bit) Lua 5.2.1 Copyright (C) 1994-2012 Lua.org, PUC-Rio Finding Users: SYS GRP_DBG GRP_DISKUSAGE U1 U3 USER4 U GRP_MONITOR GRP_LOG ODBC U2 U4 U5 MIKE PUBLIC > os.exit()

1.4 Using require in Kog scripts

Kog scripting is based on Lua 5.2 which has changed the way that require works from previous Lua versions. When a statement like:

require ‘called’

is used then the package path is searched for *.kog and *.lua files, so either called.kog or called.lua may match.

So if we had created a file C:\Users\Michael.Atkinson\.wxconsole\lua\called.lua with the single line:

print(‘hello mike’)

Then that statement would have been executed and "hello mike" output to the log.

Data Definition xvii

Package Path

The package path may be seen by

print(_G.package.path);

Which will have contents like:

;C:\Users\Michael.Atkinson\.wxconsole\kog\?.kog;C:\Users\Michael.Atkinson\.wxconsole\lua\?.lua;C:\wc2c\src\wx2console\build\wxconsole\debug\lua\?.lua;C:\wc2c\src\wx2console\build\wxconsole\debug\lua\?\init.lua;C:\wc2c\src\wx2console\build\wxconsole\debug\?.lua;C:\wc2c\src\wx2console\build\wxconsole\debug\?\init.lua;.\?.kog;.\?.lua

It is possible to alter the package path to add more locations and then require script from those locations. So suppose there is a file C:\kogscripts\queries\

getmytable.kog

local t= select * from mytable; return t;

Then

_G.package.path = "C:/kogscripts/?.kog;" .. _G.package.path; contents = require "queries.getmytable"

will load that file and set the contents table to the result of the select, so that contents.rows[1] will be the first row of the resultset.

In the above example the getmytable.kog file is executed once when it is first required. Subsequently it may be required again but the value returned will be the same table. In the example below both contents and contents2 are the same table.

_G.package.path = "C:/kogscripts/?.kog;" .. _G.package.path; contents = require "queries.getmytable" contents2 = require "queries.getmytable"

Lua is very flexible and there are several ways to be able to create libraries that contain queries that may be run several time, the following example shows one method. Say we have a file C:\kogscripts\queries\ getview.kog

local t = {} function t.getView()

mydata = select * from myview; return mydata

end return t

Preface

Data Definition xviii

now if we call it with:

_G.package.path = "C:/kogscripts/?.kog;" .. _G.package.path; getter = require "queries.getview"

v1 = getter.getView() v2 = getter.getView()

v1 and v2 will be different Lua tables, holding the results of two queries.

LUA_PATH

The LUA_PATH environment variable may be used to add extra elements to the search path for *.lua and *.kog files.

This is used for the Linux server installation to add

“/opt/Kognitio/wx2/<version>/lib/lua/?.lua;/opt/Kognitio/wx2/<version>/lib/kog?.kog;”

to the search path.

Standard Library Location

Linux server install ( linux-install-<version>.sfx ):

/opt/Kognitio/wx2/<version>/lib/lua/std

Linux client tools install ( wx2-linux-clients.tar.gz ):

<install path>/lib/lua/std

Windows install:

C:\Program Files (x86)\Kognitio Ltd\wx2clients32\lua\std

C:\Program Files\Kognitio Ltd\wx2clients64\lua\std

1.5 What Happens “under the hood”

The Kognitio extension for naked SQL is implemented by the sql(String, …) function. This takes one or more strings and executes them one at a time as SQL statements.

Data Definition xix

When the Lua parser encounters a SQL keyword (case insensitive) it checks if it is in Kog script mode, if it is then it does several things.

1. Reads the script text up to the next ‘;’ (outside of quotes).

2. It interprets the text using the rules of SQL and builds up a string.

3. When it encounters a ‘$’ it tries to interpret the following text as a Lua variable or expression. The expression is concatenated with the string encountered up to the $.

4. When the text is fully read it compiles the code to place the string (with concatenation) onto the stack and call the sql(String,..) function.

This means that an SQL expression like:

x = 'name' y = 'hello' z = 2 select $x, '$y ', $(z+1) from sys.ipe_user;

Will compile to :

sql([[select ]] .. x .. [[,']] .. y .. [[', ]] .. (z+1) .. [[ from sys.ipe_user]])

where the Lua [[ ]] string operator is used to enclose strings ensuring that single and double quotes within the naked SQL are handled correctly.

1.6 Other Kognitio Extensions

Although Naked SQL is the major extension, Kognitio have added a few other features.

Note: Lua scripts are pure 5.2 Lua - the select keyword has the standard Lua select meaning.

Shell

The shell function has been added to call out into the operating system command shell.

Preface

Data Definition xx

Table __toString()

Standard Lua does not have a __toString() method defined for tables. This makes it impossible to override to add more functionality (e.g. pretty printing nested tables).

Mixed Lua and Kog scripts

It is possible to call Kog scripts from Lua scripts and call Lua scripts from Kog scripts.

Lua Lanes

An experimental version of Lua Lanes is built in. It shows up in the global variables as “lanes.core”, This is not usable at the current time.

Data Definition 21

2

Kog Script Libarary

In this Chapter we describe the Kog Script standard library (shortened to ‘std’).

Note that this library is currently EXPERIMENTAL, and modules and functions may change over the next few releases.

2.1 Lua builtin library functions

Xxx

2.2 Kog Script std library

string.format

This has been extended to work better with one argument, i.e. no formatting is attempted and it returns that argument.

Example

--print(string.format("%#.2e").."\n") -- gives an error print(string.format("%#.2e",12.34567).."\n") require 'std.string' print(string.format("%#.2e").."\n")

sub

Chapter 2 - Data Definition Public

Data Definition 22

std.base

std.assert

Extend to allow formatted arguments. std.assert(v, f, ...)

v value to assert f format … arguments to format returns value v

Example

std = require 'std.base' std.assert(5 == fn(1), 'expected 5, got %d', fn(1)); function fn(a,b,c) return a*100+b*10+c; end

std.bind

Partially apply a function.

std.bind(f, ...) f function to apply partially … arguments to bind returns function with arguments already bound

Example

std = require 'std.base' function fn(a,b,c) return a*100+b*10+c; end fn1 = std.bind(fn, 1) fn2 = std.bind(fn, 1,2) fn3 = std.bind(fn, 1,2,3) print(fn1(2,3).. '\n') -- 123 print(fn2(3).. '\n') -- 123 print(fn3().. '\n') -- 123

std.collect

Collect the results of an iterator.

std.collect(x, i, ...) x table to hold results

Public Chapter 2 - Data Definition

Data Definition 23

i iterator … parameters to iterator returns results of running the iterator on its arguments

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } print(std.tostring(std.collect({}, std.leaves, t)) .. '\n') -- {1=a,2=b,3=c,4=d}

std.compose

Compose functions (fn applied first).

std.compose(...) … functions f1 … fn to compose returns composition of f1 … fn

Example

std = require 'std.base' fn1 = function(a) return a*a; end fn2 = function(a) return a+a; end fn3 = function(a) return a..a; end print(std.compose(fn1,fn1)(2) .. "\n") -- 16 print(std.compose(fn1,fn2)(3) .. "\n") -- 36 = (3+3) * (3+3) print(std.compose(fn3,fn3)("ab") .. "\n") -- abababab

std.concat

Concatenate lists.

std.concat(...) … lists returns table containing concatenated lists

Example

std = require 'std.base' print(std.tostring(std.concat({1,'a'},{3},{4}))) -- {1=1,2=a,3=3,4=4}

std.curry

Curry a function.

std.curry(f, n) f function to curry

n number of arguments


Data Definition 24

returns curried version of f

Example

std = require 'std.base' function fn(a,b,c) return a*100+b*10+c; end fn1 = std.curry(fn, 1) fn2 = std.curry(fn, 2) fn3 = std.curry(fn, 3) fn2a = fn2(1) fn3a = fn3(1) fn3b = fn3a(2) print(fn1(1,2,3) .. '\n' ) -- 123 print(fn2(1)(2,3) .. '\n') -- 123 print(fn2a(2,3) .. '\n') -- 123 print(fn3(1)(2)(3) .. '\n') -- 123 print(fn3a(2)(3) .. '\n') -- 123 print(fn3b(3) .. '\n') -- 123

std.die

Print out warning with the name of program and file (if any), then die.

std.die(...)

… arguments for warning

Example

std = require 'std.base' std.die(Error: ', 'should not occur' )

std.eval

Evaluate a string. The opposite of std.pickle().

std.eval(s) s string returns value of string

Example

std = require 'std.base' print(std.eval("1+2+3") .. "\n") -- 6

std.filter

Filter an iterator with a predicate.


Data Definition 25

std.filter(x, p, i, ...) x table to hold results p predicate i iterator … parameters to iterator returns results of running the iterator on its arguments

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } function fn1(a) return a=='b' end print(std.tostring(std.filter({}, fn1, std.leaves, t)) .. '\n') -- {1=b}

std.fold

Fold a binary function into an iterator.

std.fold(f, d, i, ...) f function d initial value i iterator … parameters to iterator returns results of running the iterator on its arguments

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } function fn1(a,b) return a..b end print(std.tostring(std.fold(fn1, '', std.leaves, t)) .. '\n') -- 'abcd'

std.id

Identity function

std.id(...) … tuple returns tuple

std.ileaves

Tree iterator which returns just numbered leaves, in order.

std.ileaves(tr) tr tree to iterate over returns iterator function returns tree

Example


Data Definition 26

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } for n in std.ileaves(t) do print(n .. ' ') end -- a c d

std.inodes

Tree iterator over numbered nodes, in order.

std.inodes (tr) tr tree to iterate over returns iterator function returns tree

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } for x,p,n in std.inodes(t) do if x == 'leaf' then print(n .." " ) end end -- a c d

std.leaves

Tree iterator which returns all leaves.

std.leaves(tr) tr tree to iterate over returns iterator function returns tree

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } for n in std.leaves(t) do print(n .. ' ') end -- a b c d

std.map

Map a function over an iterator.

std.map(x, f, i, ...) x table to hold results f function i iterator … parameters to iterator


Data Definition 27

returns results of running the iterator on its arguments

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } function fn1(a) return a..a end print(std.tostring(std.map({}, fn1, std.leaves, t)) .. '\n') -- {1=aa,2=bb,3=cc,4=dd}

std.menoize

Memoize a function, by wrapping it in a functable.

std.memoize(fn) fn function that returns a single result returns memoized function

Example

std = require 'std.base' t = std.memoize( function(a) return a*a; end ) print(t(3) .. "\n" ) -- 9

std.metamethod

Return given metamethod, if any, or nil. std.metamethod(x, n)

x object to get metamethod of n name of metamethod to get returns metamethod function or nil if no metamethod or not a

function

std.nodes

Tree iterator; return all the nodes in a tree

std.nodes(tr) tr tree to iterate over returns iterator function returns tree

Example

std = require 'std.base' t = { { { 'a', e='b' }, {'c'} }, 'd' } for x,p,n in std.nodes(t) do if x == 'leaf' then print(n .." " )


Data Definition 28

end end -- a b c d

std.op

Array containing various operators.

std.op ["[]"] -- index std.op ["+"] -- Addition std.op ["-"] -- Subtraction std.op ["*"] -- Multiplication std.op ["/"] -- Division std.op ["and"] -- Boolean and std.op ["or"] – Boolean or std.op ["not"] -- Boolean negation std.op ["=="] -- Equality std.op ["~="] -- Not equals

Example

std = require 'std.base' print(std.op["[]"]({1,2,3},2) .. '\n') -- 2

std.pack

Turn a tuple into a list.

std.pack(...) … tuple returns table containing tuple values

Example

std = require 'std.base' t = std.pack(1, 'a') -- t = { 1, ‘a’ }

std.pickle

Convert a value to a string.

The string can be passed to std.eval to retrieve the value.

std.pickle(x) x object to pickle returns string such that eval (s) is the same value as x

Example


Data Definition 29

std = require 'std.base' s = std.pickle({ 1, 'a' }) v = std.eval(s) -- v = { 1, ‘a’ }

std.prettytostring

Pretty-print a table.

std.prettytostring(t, indent, spacing) t table to print indent indent between levels ["\t"] spacing space before every line returns pretty printed string representation of t

Example

std = require 'std.base' t = { 1, { 2, 3} } t2 = { t, { 4}, t } table.insert(t, t2) print(std.prettytostring(t)) – pretty printed table over several lines

-- { -- [1] = 1, -- [2] = -- { -- [1] = 2, -- [2] = 3, -- }, -- [3] = -- { -- [1] = table: 02E7E430, -- [2] = -- { -- [1] = 4, -- }, -- [3] = table: 02E7E430, -- }, -- }

std.render

Turn tables into strings with recursion detection.

std.render(x, open, close, elem, pair, sep, roots) x object to convert to string open open table renderer close close table renderer


Data Definition 30

elem element renderer pair pair renderer sep separator renderer returns string representation

Example

std = require 'std.base' t = { 1, { 2, 3} } t2 = { t, { 4}, t } table.insert(t, t2) print(std.render (t, function () return "{" end, function () return "}" end, _G.tostring, function (t, _, _, i, v) return i .. "=" .. v end, function (_, i, _, j) if i and j then return "," end return "" end)) -- {1=1,2={1=2,2=3},3={1=table: 02E7ABF0,2={1=4},3=table: 02E7ABF0}}

std.ripairs

Turn tables into strings with recursion detection.

std.ripairs(t) t table to iterate over returns iterator function returns the table, as above returns #t + 1

Example

std = require 'std.base' t = {'a','b','c'} t2= {} for i,v in std.ripairs(t) do table.insert(t2,v) end -- t2 = {'c', 'b', 'a'}

std.tostring

Extend tostring to work better on tables.

std.tostring(x) x object to convert to string returns string representation


Data Definition 31

Example

std = require 'std.base' t = { 1, { 2, 3} } t2 = { t, { 4}, t } table.insert(t, t2) print(std.tostring(t)) -- {1=1,2={1=2,2=3},3={1=table: 02E7AE48,2={1=4},3=table: 02E7AE48}}

std.totable

Turn an object into a table according to __totable metamethod.

std.totable(x) x object to turn into a table returns table or nil

Example

std = require 'std.base' getmetatable ("").__totable = function (s) t = {} for i = 1,#s do table.insert(t, s[i]) end return t; end t = std.totable("hello") print( std.tostring(t)) -- {1=h,2=e,3=l,4=l,5=o}

std.warn

Give warning with the name of program and file (if any).

std.warn(...) … arguments for warning

Example

std = require 'std.base' std.warn('Warning: ', 'should not occur' )


Data Definition 32

std.class

This enables classes to be created

Example

require 'std.class' Animal = class(function(a,name)

a.name = name end) function Animal:__tostring()

return self.name..': '..self:speak() end Dog = class(Animal) function Dog:speak()

return 'bark' end Cat = class(Animal, function(c,name,breed)

Animal.init(c,name) -- must init base! c.breed = breed

end)

function Cat:speak() return 'meow'

end Lion = class(Cat) function Lion:speak()

return 'roar' end fido = Dog('Fido') felix = Cat('Felix','Tabby') leo = Lion('Leo','African') if leo:is_a(Cat) then print ("lions are big Cats\n") end print(fido:speak() .. "\n") print(felix:speak() .. "\n") print(leo:speak() .. "\n")


Data Definition 33

std.list

std.strbuf

This module is used to add string buffer functionality for performance. Using a string buffer may avoid lots of string concatenations, giving a performance improvement.

Constructor

Constructor StrBuf(param) Create a Table.

param a string, or value which is converted to a string return new StrBuf

__concat(s)

Concatenation operation

Example

require 'std.strbuf' buf = StrBuf("this") buf = buf .. " is" .. " a" .. " strbuf" .. " string" -- each .. is call to __concat() print(buf)

__tostring()

Converts the concatenation buffer into a string

Example

require 'std.strbuf' buf = StrBuf("this") buf = buf .. " is" .. " a" .. " strbuf" .. " string" print(buf) –- call to __tostring()

std.string

This module adds extra string functions to _G.string


Data Definition 34

..

Concat method, this converts the second parameter to a string.

Example

require 'std.string' t = {1, 'a'} print("table= " .. t.. "\n " )

[ ]

Concat method, this converts the second parameter to a string.

Example

require 'std.string' s = "abc" print("b= " .. s[2].. "\n ")

caps

Capitalise each word in a string

Example

require 'std.string' s = "a string to capitalise" print(s:caps())

chomp

Remove any final newline from a string.

Example

require 'std.string' s = "remove newline\n" print(s:chomp()=="remove newline ", " \n")

escapePattern

Escape a string to be used as a pattern.

Example

require 'std.string' s = "%me"


Data Definition 35

print(s:escapePattern() .. "\n")

escapeShell

Escape a string to be used as a shell token.

Quotes spaces, parentheses, brackets, quotes, apostrophes and whitespace.

Example

require 'std.string' s = [[% in mike's "string" indexed by [] is (very) complex]] print(s:escapeShell(), " \n")

find_as_list

Do find, returning captures as a list.

Where: s target string p pattern init start position (default: 1) plain inhibit magic characters (default: nil)

returns: start of match, end of match, table of captures

Example

require 'std.string' require 'std.table' from,to,t = string.find_as_list("a string to pack","(%w+)", 4) print(from, to, std.tostring(t))

finds

Do find, returning captures as a list.

Where: s target string p pattern init start position (default: 1) plain inhibit magic characters (default: nil)

returns: list of {from, to, capt = {captures}}

Example


Data Definition 36

require 'std.string' require 'std.table' t = string.finds("a string to pack", "(%w+)", 4) print(std.tostring(t).. "\n" ) for i,v in pairs(t) do print(v.capt[1].."\n") end

gsubs

Perform multiple calls to gsub.

Where: s string to call gsub on sub {pattern1=replacement1 ...} n upper limit on replacements (default: infinite)

returns: result string, number of replacements made

Example

require 'std.string' s = "abcdabebabc" print(s:gsubs({ab='xx', c='yy'} ) )

ltrim

Trims of leading whitespace from the left of a string

Example

require 'std.string' s = " string with trailing " print('"' .. s:ltrim() .. '"\n')

numbertosi

Write a number using SI suffixes. The number is always written to 3 significant figures.

Example

require 'std.string' print(string.numbertosi(1.23456))

ordinalSuffix

Return the English suffix for an ordinal.

Example


Data Definition 37

require 'std.string' for i=1,30 do print(i .. string.ordinalSuffix(i) .."\n"); end

pad

Justify a string.

When the string is longer than w, it is truncated (left or right according to the sign of w).

Example

require 'std.string' s = "y" print( '"' .. s:pad(5) .. '"' ..string.pad("1234567" ,3) .. s:pad(5, '.') .. s:pad(-5,'-') .. "\n")

rep

Repeat a string

Example

require 'std.string' print(string.rep("abc",5) .. "\n")

rtrim

Trims of trailing whitespace from the right of a string

Example

require 'std.string' s = " string with trailing " print('"' .. s:rtrim() .. '"\n')

trim

Trims of leading and trailing whitespace from a string

Example

require 'std.string' s = " string with trailing " print('"' .. s:trim() .. '"\n')

wrap

Wrap a string into a paragraph


Data Definition 38

Example

require 'std.string' s = "Wrap a string into a paragraph. string.wrap(s, w, ind, ind1). Where s string to wrap, w width to wrap to (default: 78), ind indent (default: 0) and ind1 indent of first line (default: ind) returning the wrapped paragraph" print(string.wrap(s, 50, 5, 10))

std.Table

Table extends built-in table support with a few common functions. These are both class based (Table) and part of the table package

Constructor

Constructor Table(param) Create a Table.

param a Table, table or value return new Table with values set to those of the Table or table or the value

clone

function Table:clone() function table.clone(t) Returns a new table (with the same metadata) containing the same index, value pairs as the original table.

t table return table containing a cloned version of t

Table = require 'std.table' t = { a=1, b='x', c='zz'} x = Table(t) t2 = table.clone(t) x2 = x:clone() print("t=" .. t .. ", t2=" .. t2 .. "\n") print("x=" .. x .. ", x=" .. x2 .. "\n")

clone_rename

function Table:clone_rename(map) function table.clone(t,map) Returns a new Table (with the same metadata) containing the same index, value pairs as the original table, except that the map is used to rename values to new indexes.

Table = require 'std.table'


Data Definition 39

map = { 1=2, 2=3, 3=4, 4=1 } x = Table({'a', 'b', 'c', 'd'}) print("x=" .. x .. ", x=" .. x:clone_rename(map) .. "\n") map = { p='w', q='x', r='y', s='z'} x = Table({ p='a', q='b', r='c', s='d'}) print("x=" .. x .. ", y=" .. x:clone_rename(map) .. "\n")

empty

function Table:empty() function table.empty(t) Returns true if the table contains no entries

t table return boolean true if table is empty

Example Table = require 'std.table' t = { 3, 2, 3, 5, 1} t2 = { } x = Table(t) print("t empty=" .. table.empty(t) .. ", t2 empty=" .. table.empty(t2) .. "\n") print("x empty=" .. x:empty() .. "\n")

indices

function Table:indices() function table.indices(t) Returns a new table (with the same metadata) containing the indices of the original table.

t table return table containing indices of table parameter

Example Table = require 'std.table' t = { a=1, b=’x’, c=’zz’} x = Table(t) print("t indices=" .. table.indices(t) .. "\n") print("x indices=" .. x:indices() .. "\n")

insert

function Table:insert(v) function table.insert(t,v) Returns the table with the value

t table v value to insert into table t return table t

Example Table = require 'std.table'


Data Definition 40

t = { 1, 2, 3 } x = Table(t) print("t.insert(4)=" .. table.insert(t,4) .. "\n") print("x.insert(4)=" .. x:insert(4) .. "\n")

invert

function Table:invert() function table.invert(t) Returns a new table (with the same metadata) containing v=i, for all i=v in the original table.

t table return table containing inverted t

Example Table = require 'std.table' t = { a=1, b=’x’, c=’zz’} x = Table(t) print("t invert=" .. table.invert(t) .. "\n") print("x invert=" .. x:invert() .. "\n")

merge

function Table:merge(u) function table.merge(t, u) Merge the values of table u into table t, if the index of a value in u exists in t then the value in t is overwritten.

t table u second table return first table

Example Table = require 'std.table' t = { 3, 2, 3, 5, 1} t2 = {6, 5, 'b'} x = Table(t) x2 = Table(t2) print("merged table=" .. table.merge(t,t2) .. "\n") print("merged table=" .. x:merge(x2) .. "\n")

pack

function Table:pack(…) function table.pack(t,…) Returns a new table (with the same metadata) containing v=i, for all i=v in the original table.

t table … more tables return table containing all the table parameters and ‘n’ the number of

tables


Data Definition 41

Example Table = require 'std.table' t = { a=1, b=’x’, c=’zz’} t2 = { a=1, b=’x’, c=’zz’} x = Table(t) print("pack(t,t2,t2)=" .. table.pack(t,t2,t2) .. "\n") print("x:pack(t2,x)=" .. x:pack(t2,x) .. "\n")

remove

function Table:remove(i) function table.remove(t,i) Returns the table with the value at index i removed.

t table i index to remove return table t with index i removed.

Example Table = require 'std.table' t = { ‘a’, ‘b’, ‘c’} x = Table(t) print("remove(t,2)=" .. table.remove(2) .. "\n") print("x:remove(2)=" .. x:remove(2) .. "\n")

sort

function Table:sort(c) function table.sort(t, c) Sort the Table

t table c comparator function return sorted table

Example

Table = require 'std.table' t = { 3, 2, 3, 5, 1} x = Table(t) print("sorted table=" .. table.sort(t) .. "\n") print("sorted table=" .. x:sort() .. "\n") print("rsorted table=" .. x:sort(function(a,b) return a > b end) .. "\n")

values

function Table:values() function table.values(t) Returns a new table (with the same metadata) containing the values of the original table.

t table return table containing values of table parameter

Example Table = require 'std.table'


Data Definition 42

t = { a=1, b=’x’, c=’zz’} x = Table(t) print("t values=" .. table.values(t) .. "\n") print("x values=" .. x:values() .. "\n")

Example


Data Definition 43

3

Data Definition

In this Chapter we describe the types of data that can be used within the macro system.

3.1 Data Items

Data Item

Usage

The basic type for metadata tree elements.

A DataItem consists of a row of data and an array of child DataItems.

When representing a resultset returned from a SQL query or a general table, the DataItem row of data is the column headings and each child is one row of the resultset/table.

When representing a tree, the DataItem row of data is not used (although it may contain data). Its children are the sub-elements of the DataItem in the tree.


Data Definition 44

Properties

Each DataItem contains a set of properties.

“name”

“id” - integer identifier of the item

“text” - value displayed to the user in the Metadata tree

DataItems that are part of the metadata tree (and a few others); will also have:

“objectname” - the type of the object, this is the Qt QObject objectName property.

e.g. a table in the metadata tree with table_id of 1234, table name of “my_table”will have properties

“name”=>”my_table”,

“id”=>”1234”,

“text”=>”my_table”

“objectname”=>”table”.

e.g. a resultset from the query “select * from ipe_schema where id<2” returns a data item:

data = “NAME”, “ID”, “USER_ID”, “DEFAULT_CHARSET”

properties: “itemText”=>”Results”

children:

DataItem:

data = “SYS”, “0”, “0”, “-1”

properties: “itemText”=>”1”

DataItem:

Data = “ODBC”, “1”, “5”, “-1”

properties: “itemText”=>”2”


Data Definition 45

Column

Usage

The Column DataItem contains data about a table or view column.

Properties

Name Value Notes

“objectname” “column”

“seq” Id of the column

Data

Name Value Notes

“SEQ” Id of the column

“NAME” String

“DATATYPE”

“NUMTYPE”

“LENGTH”

“START”

“SCALE”

“PRECISION”

“NULLS”


Data Definition 46

Connectors

Usage

Connectors have children containing all the connectors visible to the current user.

Properties

Name Value Notes

“objectname” “connectors”

Data

This holds a set of Connector objects in its children.

Connector

Usage

This holds data for a connector obtained from SYS.IPE_ALLEXTERNAL_CONNECTOR

Properties

Name Value Notes

“objectname” “connector”

“id” Integer Connector identifier

“source”

“command”

“target”

“foreground”


Data Definition 47

“tooltip”

“active”

“externaltables”

“objectprivtext”

Data

A Connector has no children and does not contain row data.

Domains

Usage

Domains have children containing all the privilege domains in the Kognitio Application Platform.

Note: more privilege domains may be included in future versions of the Kognitio Application Platform.

Properties

Name Value Notes

“objectname” “domains”

Data

The children are Domain DataItems.


Data Definition 48

Domain

Usage

This holds data about a particular Kognitio Application Platform privilege domain.

Properties

Name Value Notes

“id” Domain identifier

“text” Domain name

“objectname” “domain”

Data

A Domain has Privilege DataItem children; they are added to the Domain the first time the Privileges DataItem is updated.

A Domain DataItem has no row data.

External Scripts

Usage

External Scripts have children containing all the external scripts in a schema that are visible to the user.

Since KAP 7.9

Properties

Name Value Notes


Data Definition 49

“objectname” “extscripts”

“text” “ExtScripts”

Data

The children are ExtScript data items.

External Script

Usage

The External Script DataItem holds known information about an external script.

Since KAP 7.9

Properties

Name Value Notes

“objectname” “extscript”

“text” External script name

“id” Integer External Script identifier

“tooltip” “external script”

“qualifiedName” Schema qualified name

“schemaId” Integer Schema Identifier

“numInputs” See SQL for creating the external script

“outputColumns” See SQL for creating the external script

“scriptEnvId” See SQL for creating the external script

“scriptEnvSeq” See SQL for creating the external script

“partitionMode” See SQL for creating the external script


Data Definition 50

“maxThreads” See SQL for creating the external script

“maxLocalThreads” See SQL for creating the external script

“ramRequired” See SQL for creating the external script

“onNodes” See SQL for creating the external script

“notOnNodes” See SQL for creating the external script

“scriptText” See SQL for creating the external script

“outputHandle” See SQL for creating the external script

“outputAttrs” See SQL for creating the external script

Data

Properties obtained from SYS.IPE_ALLEXTERNAL_SCRIPT so this must be visible to the user for external scripts to be shown.

Plugins

Usage

Plugins have children containing all the plugins that are visible to the user.

Properties

Name Value Notes

“objectname” “plugins”

“text” “Plugins”

Data

Children of Plugins contain data on each plugin visible to the user.


Data Definition 51

Plugin

Usage

The Plugin DataItem has properties containing information about a plugin to the Kognitio Application Platform.

Properties

Name Value Notes

“objectname” “plugin”

“text” String Plugin name

“id” Integer Plugin identifier

“objectprivtext” String Plugin name

“state”

“filename”

Data

Properties obtained from SYS.IPE_PLUGIN (or SYS.IPE_ALLPLUGIN on older systems) so this must be visible to the user for external scripts to be shown.

Privileges

Usage

Privileges have children containing all the privileges that are available for a particular domain.


Data Definition 52

The first time that the Privileges DataItem is updated the privileges found are added to the relevant Domain DataItem.

Properties

Name Value Notes

“objectname” “privileges”

“text” “Privileges”

“hasPrivileges” “true” or “false” Set initially to “false”, set to “true” after the privileges have been updated.

Data

The Privileges DataItem has neither children nor row data.

Privilege

Usage

The Privilege DataItem holds information about a particular privilege. This information may be used to construct the SQL to alter privileges.

Properties

Name Value Notes

“objectname” “privilege”

“text” String Privilege name

“name” String Privilege name

“domainid” Integer Domain identifier


Data Definition 53

“privilege” String See below

“privilegeNumber” Integer See SQL Guide

“domain” String See below

“ondomain” String See below

“objectName” String See below

Data

Domain Id Object Name Domain On Domain

1 “systempriv” “system” “system”

2 “schemapriv” “schema” “schema”

3 “tablepriv” “table” “table”

4 “columnpriv” “column” “column”

5 “userpriv” “user” “user”

6 “grouppriv” “group” “group”

7 “pluginpriv” “plugin” “module”

8 “queuepriv” “queue” “queue”

9 “connectorpriv” “connector” “connector”

10 “scriptenvpriv” “scriptenv” “script environment”

11 “systemwidepriv” “systemwide” “system”

12 “schemawidepriv” “schemawide” “schema”

13 “extscriptpriv” “extscript” “external script”

The “privilege” property is usual set to the privilege name; but has the following exceptions.


Data Definition 54

DomainId PrivilegeNumber “privilege” property

3 16 “ref”

3 512 “drop”

5 65536 “add key”

5 131072 “drop key”

Queues

Usage

Queues have children containing all the queues that are visible to the user.

Properties

Name Value Notes

“objectname” “queues”

“text” “Queues”

Data

The children of the Queues DataItem are Queue DataItem holding information about all queues visible to the user.

Queue

Usage

The Queue DataItem holds information about a particular queue.


Data Definition 55

Properties

Name Value Notes

“objectname” “queue”

“text” String Queue name

“name” String Queue name

“id” Integer Queue identifier

Data

This contains data from SYS.IPE_QUEUES so the user needs to have select privilege on that table.

Schemas

Usage

The Schema DataItem children are Schema DataItems holding data about schemas visible to the user.

Properties

Name Value Notes

“objectname” “schemas”

“text” “Schemas”

Data

This contains data from SYS.IPE_TBL_VIEW_COLUMNS3 which is obtained when the metadata tree is first opened. Later updates get data from SYS.IPE_SCHEMA.

The Schema DataItem children are Schema DataItems holding data about schemas visible to the user.


Data Definition 56

Schema

Usage

The Schema DataItem has children for tables, views, temporary tables and external scripts.

Properties

Name Value Notes

“objectname” “schema”

“text” String Schema name

Data

There are children for:

Tables

Temporary Tables

Views

External Scripts

Script Environments

Usage

Script Environments have children containing all the script environments that are visible to the user.

Properties

Name Value Notes

“objectname” “scriptenvs”


Data Definition 57

“text” “ScriptEnvs”

Data

The children of the ScriptEnvs DataItem are ScriptEnv DataItem holding information about all script environments visible to the user.

Script Environment

Usage

ScriptEnv DataItems holds data about a single script environment.

Properties

Name Value Notes

“objectname” “scriptenv”

“id” Integer Script environment identifier

“text” String Script environment name

“command” String See SQL for creating the script environment

“input” String See SQL for creating the script environment

“maxthreads” Integer See SQL for creating the script environment

“maxlocalthreads” Integer See SQL for creating the script environment

“ramrequired” Integer See SQL for creating the script environment

“onnodes” String See SQL for creating the script environment

“notonnodes” String See SQL for creating the script environment

“numexternalscripts” Integer See SQL for creating the script environment


Data Definition 58

Data

This DataItem holds data from SYS.IPE_ALLSCRIPT_ENVIRONMENT so the user needs select privileges on that table.

SecClasses

Usage

SecClasses have children containing all the security classes that are visible to the user.

Properties

Name Value Notes

“objectname” “secclasses”

“text” “Security Classes”

Data

Children of the SecClasses DataItem are SecClass DataItems holding information about individual security classes.

SecClass

Usage

The SecClass DataItem holds information about a security class.

Properties

Name Value Notes

“objectname” “secclass”


Data Definition 59

“name” Security class name

“text” Security class name

“id” Integer Security Class Identifier

“secclass” Integer Security Class Identifier

“passwordminlength” String

“passwordstyle” String

“passwordrepeatperiod” String

“passwordchangeperiod” String

“loginfailmax” String

“userinactivemax” String

“sessioninactivemax” String

Data

This SecClass data is obtained from SYS.IPE_SEC_CLASS, so the user needs select privileges on that table.

Sessions

Usage

Sessions have children containing all the sessions that are visible to the user.

Properties

Name Value Notes

“objectname” “sessions”

“text” “Sessions”


Data Definition 60

Data

Children of the Sessions DataItem are Session DataItems holding information about individual sessions.

Session

Usage

The Session DataItem holds information about a session.

Properties

Name Value Notes

“objectname” “session”

“id” Integer Session Identifier

“text” String Username + “(session “ + id “)”

“username” String

“connecttime” String

“commandrunning” Integer 0 = idle 1 = running 2 = statement rollback 3 = transaction rollback 4 = queued 5 = compiling query

“status” String One of:

“Idle” “Running” “Statement Rollback” “Transaction Rollback” “Queued” “Compiling Query”

“clientname” String

“netaddress” String


Data Definition 61

“clientport” String

“duration” String For servers > 7.9.1

“workram” String For servers > 7.9.1

“lastcommand” String

Data

The Session DataItem contains data from SYS.IPE_CURSESSIONS so the user needs select privileges on that table.

Tables

Usage

The group of tables that are contained within a schema. Temporary tables are contained within their own Tables DataItem.

Properties

Name Value Notes

“objectname” “tables”

“text” “Tables”

“schemaId” Integer The identifier of the schema that holds this group of tables.

“isTempTable” “true” or “false” If “true” then this is the group of temporary tables within the schema.

Data

Children of the Tables DataItem are Table DataItems containing data about the tables visible to the current user in a schema.


Data Definition 62

Table

Usage

The Table DataItem holds information about tables, including system and temporary tables.

Properties

Name Value Notes

“objectname” “table”

“text” “Table”

“id” Integer The Table identifier.

“schemaId” Integer The identifier of the schema that holds this table.

“ishorizontallyfragmented” “true” or “false” If “true” then this table has a horizontally fragmented image.

"isverticallyfragmented" “true” or “false” If “true” then this table has a vertically fragmented image.

“type” String “T” = table “S” = system table “X” = external table

“distribution” Integer 0 = default 1 = random 2 = replicated 3 = hashed 4 = hashed replicated 5 = hashed random

“predicate” String Horizontally fragmented table predicate

“createTime” String

“qualifiedName” String “\”” + Schema name + “.” + table name + “\””.

objectprivtext String Schema name + “.” + table name

isimage “true” or “false” Set to “true” if the table has an


Data Definition 63

image.

“foreground” String Colour name.

“owner” String User who owns the table

“uniqueCount” String

“fragmentation” Integer 0 = not in ram

“primarygroup”

“istemptable” “true” or “false” Set to “true” if this is a temporary table.

Data

The Table DataItem contains data from SYS.IPE_TABLE , SYS.IPE_BASE and SYS.IPE_COL_IMG so the user needs select privileges on those tables.

It also uses SYS.IPE_FRAGMENTING_PREDS, if that table is not available or the user does not have select privileges on it then the “ishorizontallyfragmented” may not be set.

Users

Usage

Users have children containing all the users that are visible to the current user.

Properties

Name Value Notes

“objectname” “users”

“text” “Users”


Data Definition 64

Data

Children of the Users DataItem are User DataItems holding information about individual users.

User

Usage

The User DataItem holds information about a user or group.

Properties

Name Value Notes

“objectname” “user”

“text” “User”

“name” String Group or User’s name

“queuePriority” Integer -1 by default.

“defaultschema” Integer The identifier of the default schema for the group or user.

“secclass” Integer

“schClass” Integer

“status” Integer (status & 8) == 8 means this is for a group.

“objectprivtext” String Group or User’s name

Data

User DataItems that are for a user do not have children; User DataItems that are for groups have User DataItem children consisting of each user in that group.

The User DataItem contains data from SYS.IPE_USER so the user needs select privileges on that table. If the User DataItem is for a group then the SYS.IPE_GROUP_MEMBERS table is used as well.


Data Definition 65

Views

Usage

The group of views that are contained within a schema.

Properties

Name Value Notes

“objectname” “views”

“text” “Views”

“schemaId” Integer The identifier of the schema that holds this group of views.

Data

Children of the Views DataItem are View DataItems containing data about the views visible to the current user in a schema.

View

Usage

The View DataItem holds information about views, invalidated views.

Properties

Name Value Notes

“objectname” “view”


Data Definition 66

“text” “view”

“id” Integer The View identifier.

“schemaId” Integer The identifier of the schema that holds this view.

“ishorizontallyfragmented” “false”

"isverticallyfragmented" “false”

“type” String “I” = invalidated view “V” = view

“distribution” Integer 0 = default 1 = random 2 = replicated 3 = hashed 4 = hashed replicated 5 = hashed random

“createTime” String

“qualifiedName” String “\”” + Schema name + “.” + view name + “\””.

objectprivtext String Schema name + “.” + view name

isimage “true” or “false” Set to “true” if the view has an image.

“foreground” String Colour name.

“owner” String User who owns the view

Data

The View DataItem contains data from SYS.IPE_TABLE and SYS.IPE_VIEW_IMG so the user needs select privileges on those tables.

Data Definition 67

4

Macro Elements

Macros are based on XML and this chapter describes the various elements and their attributes that

wx2macro

The <wx2macro> element is the root element of a macro.

Attibutes

attibute values notes

type

“objectaction” An action (e.g. from a menu)

“objectview” A report or monitor

“quickviz” A quick visualisation generated

macro.

“obsolete” Use this to prevent a macro

being shown

id … Any string

debug “true” Debug the macro, output to a

log pane in Console.

Child Elements

<actiontext>

<dockable>

<iconfilepath>

<menu>

Chapter 4 - Macro Elements Public

Data Definition 68

<name>

<objects>

<report>

<requiredserverversion>

<beforeserverversion>

<script>

Notes

wx2macro is the root element for all macros.

A macro may be activated in one of several places:

1. Be shown in a sub-menu of the “view” menu.

When a <menu> element is present.

2. Be shown in a popup (right-click) menu.

The <objects> element contains one or more <object> elements specifying which metadata tree objects must be selected.

When the macro is activated, it may do one of several things:

1. Be Run as a script without creating a new pane.

2. Be shown as a tab in the Console object view.

3. Be shown in a dockable window

When the <report> element is contained in a <dockable>

Example

This example shows the outline of a <wx2macro>, it

<?xml version="1.0" encoding="UTF-8"?>

<wx2macro type="objectaction">

<name>Dashboard</name>

<menu position="1">Reports</menu>

<actiontext>Dashboard</actiontext>

<objects/>

<report>

…

</report>

</wx2macro>

Public Chapter 4 - Macro Elements

Data Definition 69

actiontext

The <actiontext> element sets the display name of the macro.

Attibutes


Child Elements

none

Parent Elements

wx2macro

Notes

The name of the Macro to be displayed to the user.

Example

This example shows the “Dashboard” macro in the “Reports” sub-menu of the “View” menu of Console.






<objects/>

<report>

…

</report>

</wx2macro>

beforeserverversion

The <beforeserverversion> is used to set the maximum Kognitio Application Platform version for which the macro will be enabled.

The Kognitio Application Platform has a version number of the format:

major ‘.’ minor ‘.’ increment ‘rel’ patch


Data Definition 70

Example: 07.02.01rel120813

Attibutes


major

An integer

minor An integer optional

increment An integer optional

patch A String optional

Child Elements

none

Parent Elements

wx2macro

Notes

If the patch attribute is not included then any patch string will match.

Similarly, if the increment attribute is not included any increment will match.

Similarly if the minor attribute is not included any minor with match.

Example

This example shows the “Locks Report” macro in the “Reports” sub-menu of the “View” menu of Console.



<name>Locks Report</name>


<actiontext>Locks Report</actiontext>

<beforeserverversion major="7" minor="9" increment="0"/>

<objects>

</objects>

<report>

…

</report>

</wx2macro>


Data Definition 71

chartformat

The <chartformat> element is used to define the type of chart which is to be displayed.

Attibutes


type

string “column”, “line”, “point”, “scatter”,

“xy”, “stack”

subtype String Optional, “3d”, “3-d”, “point”

angle Integer Optional, angle in degrees

depth Integer(%) Optional, depth of 3d graph as a % of

height.

mindepth Integer Optional, minimum depth in pixels

mincolwidth Integer Optional, minimum width of each

column in pixels

maxcolwidth Integer Optional, maximum width of each

column in pixels

seriesgap Integer Optional, width in pixels between

series data.

Child Elements

none

Parent Elements

<widget type=”chart”>

Notes

Example

dockable

The <dockable> element creates a report in its own dockable pane.

Attibutes



Data Definition 72

Child Elements

<report>

Parent Elements

wx2macro

Notes

This allows a dockable pane to be shown to the user.

Note that macros that are shown as a tab within the Console main window may also be made dockable by right-clicking on the tab and selecting “Make dockable”.

Example

This example shows the “RAM Usage for user(s)” which is shown in the pop-up menu when one or more users are selected in the metadata tree. It then shown the report in its own dockable pane.



<name>RAM Usage for user(s)</name>

<actiontext>RAM Usage for user(s)</actiontext>

<objects>

<object option="1">user</object>

</objects>

<script id="getuser">

<foreach objectname="user" id="t">

<property id="userReport" property="text">

<value id="t" property="name"/>

</property>

</foreach>

</script>

<dockable>

<report id="userReport">

…

</report>

</dockable>

</wx2macro>

kogscript

The <kogscript> element is used to run a Kog script (based on Lua) .

It is used in three circumstances:

1. As the action to be performed in action macros (child of <wx2macro>).


Data Definition 73

2. As a way of getting data or performing actions when the macro is loaded (child of <report> or <widget> with the execute attribute set to “immediate”).

3. Performing an action in response to a user generated event (child of <report> or <widget>).

Attibutes


param

String Parameter name

execute “immediate” Execute the script when first

encountered. If not present macros

which are children of <report> and

<widget> will only be executed when

Child Elements

<sql>

<data>

<property>

<foreach>

Parent Elements

<wx2macro>

<report>

<widget>

Signals

destroyed destroyed(QObject*) done itemChanged(DataItem*)

Slots

deleteLater execute execute(bool) executenot(bool) execute(int) execute(DataItem*)


Data Definition 74

Notes

The <script> element is similar, but designed to run SQL Scripts.

Scripts may be activated by various slots:

execute - always execute the script.

execute(bool) - only execute the script if the parameter is true.

executenot(bool) - only execute the script if the parameter is false.

execute(int) - set the script’s property “param” to the int value and execute the script.

execute(DataItem*) - set the script’s property “param” to the DataItem value and execute the script.

menu

The <menu> element indicates which Console sub-menu of the Console “view” menu to place the macro in. It uses the <actiontext> as the menu item text to show to the user.

Attibutes


position

An integer Position of the

item within the

menu. Currently

ignored.

Child Elements

none

Parent Elements

wx2macro


Data Definition 75

Notes

The place to put the macro within the Console menu tree.

Example







<objects/>

<report>

…

</report>

</wx2macro>

name

The <name> element sets the name of the macro.

Attibutes


id A String Unique identifier

within the macro

Child Elements

none

Parent Elements

wx2macro

Notes

The name of the Macro


Data Definition 76

Example

This example shows the macro name being set to “Dashboard”






<objects/>

<report>

…

</report>

</wx2macro>

objects

The <objects> element is used to define in which circumstances the macro is enabled. The <object> sub-element specify which DataItems within the Console metadata tree need to be selected for the macro to be activated.

Attibutes


Child Elements

<object>

Parent Elements

<wx2macro>

Notes

A macro may be activated in one of several places:

1. Be shown in a sub-menu of the “view” menu.

When a <menu> element is present.

2. Be shown in a popup (right-click) menu.


Data Definition 77

The <objects> element contains one or more <object> elements specifying which metadata tree objects must be selected.

Example 1

This example shows the “Ram Usage” macro is shown as a tab on the object view when one view is activated which is not invalidated (in which case tabletype would be “I”).



<name>RAM Usage</name>

<actiontext>RAM Usage</actiontext>

<objects>

<object option="1" objectname="view">

<test property="tabletype" match="!=" value="I"/>

</object>

</objects>

<report>

…

</report>

</wx2macro>

Example 2

This example shows the “Apply table privileges to users” macro is shown as a popup menu item when one or more users are selected, a table privilege is selected and a table is selected.



<name>UserPrivileges</name>

<actiontext>Apply table privileges to users</actiontext>

<objects>

<object option="1+">user</object>

<object>tablepriv</object>

<object>table</object>

</objects>

<script>

<foreach objectname="user" id="u">

<foreach objectname="tablepriv" id="tp">

<foreach objectname="table" id="t">

GRANT <value id="tp" property="privilege" /> ON

<value id="tp" property="domain" /><![CDATA[ ]]>

<value id="t" property="qualifiedname"/> TO

<value id="u" property="name"/>;

</foreach>

</foreach>

</foreach>

</script>

</wx2macro>


Data Definition 78

object

The <object> element specify which DataItems within the Console metadata tree need to be selected for the macro to be activated.

Attibutes


option Number

Number +

Number - Number

The number of

objects that must

be activated.

The ‘+’ means or

more than that

number.

When two numbers

are given this is

a range of

activated objects.

objectname A String

Child Elements

<test>

Parent Elements

<objects>

Notes

Multiple <object> elements may define several different object types that must be activated.

The <object> CDATA may be used as an alternative to the objectname attribute.

Example

This example shows the “Update statistics” macro is shown as an item on the pop-up menu when one or more views are selected in the Console metadata tree.



<name>UpdateStatistics</name>

<actiontext>Update statistics</actiontext>

<objects>

<object option="1+">view</object>

</objects>

<script>


Data Definition 79

<foreach objectname="view" id="t">

UPDATE STATISTICS FOR <![CDATA[ ]]><value id="t" property="qualifiedname"/>;

</foreach>

</script>

</wx2macro>

properties

The <properties> element is used to define additional properties for a chart or pie chart.

At present it is just used to format the legend (key) for a chart or pie chart.

Attibutes


radius Integer Radius of the pie chart in pixels

legendStyle

String The stylesheet for the legends.

legendTitle String

legendTitleStyle String

showLegends Boolean

showLegendsBox Boolean

legendsOffsetX Integer Pixels from top right

legendsOffsetY Integer Pixels from top right

Child Elements

None

Parent Elements


<widget type=”piechart”>


Data Definition 80

Notes

Example

report

The report element is used to enclose the main body of a report macro and acts as the main container for child widgets.

Attibutes


id String Unique identifier within the macro

minwidth Integer Minimum width of the element in

pixels

minheight Integer Minimum height of the element in

pixels

width Integer Preferred/Initial width of the

element in pixels

height Integer Preferred/Initial height of the

element in pixels

style String Style sheet, a subset of HTML

cascading Style sheets (CSS), see

http://qt-project.org/doc/qt-

4.8/stylesheet.html

Child Elements

<connection>

<kogscript>

<property>

<script>

<sql>

<widget>

Parent Elements

<dockable>

<wx2macro>

Signals

customContextMenuRequested(QPoint) destroyed() destroyed(QObject*)

http://qt-project.org/doc/qt-4.8/stylesheet.html



Data Definition 81

Slots

close deleteLater hide lower onActivated(MacroComboBox*,int) onClicked(MacroButton*) onStateChanged(MacroCheckBox*,int) onToggled(MacroRadioButton*,bool) onValueChanged(MacroSlider*,int) raise repaint setDisabled(bool) setEnabled(bool) setFocus setHidden(bool) setPropertyFromValue(const char*,QString) setShown(bool) setStyleSheet(QString) setupViewport(QWidget*) setVisible(bool) setWindowModified(bool) setWindowTitle(QString) show showFullScreen showMaximized showMinimized showNormal update updateMicroFocus

Notes

Example


Data Definition 82

requiredserverversion

The <requiredserverversion> is used to set the minimum Kognitio Application Platform version for which the macro will be enabled.

The Kognitio Application Platform has a version number of the format:

major ‘.’ minor ‘.’ increment ‘rel’ patch

Example: 07.02.01rel120813

Attibutes


major

An integer

minor An integer optional

increment An integer optional

patch A String optional

Child Elements

none

Parent Elements

wx2macro

Notes




Example



Data Definition 83

requiredtableaccess

The <requiredtable> is used to ensure that tables within the database are available for select access before the macro is made available to the user.

Attibutes


table

String Qualified table or view name

Child Elements

none

Parent Elements

wx2macro

Notes

One of these should be present for each table/view that is accessed by the macro.

Example


<?xml version="1.0" encoding="UTF-8"?> <wx2macro type="objectaction">

<name>Full Ram Usage Monitor</name>


<actiontext>Ram Usage Monitor</actiontext>

<requiredserverversion major="7" minor="0"/><objects>

<objects/>

<report>

…

</report>

</wx2macro>

scalemarks

The <scalemarks> element is used to define the scale indications on a graph.


Data Definition 84

Attibutes


majorxticks

Double Optional, display a long tick on the x

axis every majorxticks values apart.

majoryticks

Double Optional, display a long tick on the y

axis every majoryticks values apart.

minorxticks

Double Optional, display a short tick on the

x axis every minorxticks values apart.

minoryticks


y axis every minoryticks values apart.

majorxgrid

Double Optional, display a vertical line

every majorxticks values apart.

majorygrid

Double Optional, display a faint horizontal

line every majorxticks values apart.

minorxgrid


every minorxticks values apart.

minorygrid



Child Elements

none

Parent Elements


Notes

Example

script

The <script> element is used to run a sequence of SQL commands.

It is used in three circumstances:

4. As the action to be performed in action macros (child of <wx2macro>).

5. As a way of getting data or performing actions when the macro is loaded (child of <report> or <widget> with the execute attribute set to “immediate”).

6. Performing an action in response to a user generated event (child of <report> or <widget>).


Data Definition 85

Attibutes



param

String Parameter name

execute “immediate” Execute the script when first

encountered. If not present macros

which are children of <report> and

<widget> will only be executed when

Child Elements

<sql>

<data>

<property>

<foreach>

Parent Elements

<wx2macro>

<report>

<widget>

Signals

destroyed destroyed(QObject*) done itemChanged(DataItem*)

Slots

deleteLater execute execute(bool) executenot(bool) execute(int) execute(DataItem*)

Notes

The <kogscript> element is similar, but designed to run Kognitio Scripts based on the Lua language with extensions.

Scripts may be activated by various slots:

execute - always execute the script.


Data Definition 86

execute(bool) - only execute the script if the parameter is true.

executenot(bool) - only execute the script if the parameter is false.

execute(int) - set the script’s property “param” to the int value and execute the script.

execute(DataItem*) - set the script’s property “param” to the DataItem value and execute the script.

Example 1

This example shows a script being created which has a sequence of ALTER MODULE .. statements (one for each plugin selected in the metadata tree). After the script is created it is then run.



<name>ActivatePlugin</name>

<actiontext>Activate Plugin</actiontext>

<objects>

<object option="1+">plugin</object>

</objects>

<script>

<foreach objectname="plugin" id="p">

ALTER MODULE <value id="p" property="name"/> SET MODE ACTIVE;

</foreach>

</script>

</wx2macro>

Example 2

This example shows a script used being used to execute a query when the macro is first loaded and the result of the query used to set the “ymax” property of the “findymax” script object. The result of the query may be used multiple times using <value id=”findymax” property=”ymax”/>






<objects/>

<report>

<script id="findymax" execute="immediate">

<sql property="ymax">

select min(RAM_SIZE/1024) from SYS.IPE_PROCESS where TYPE='rs'</sql>

</script>


Data Definition 87

…

</report>

</wx2macro>

Example 3

This example shows a fragment of XML, which changes a label from “Ram Stores” to “Disk Stores” depending on which RadioButton is selected.

<widget type="groupbox" row="1" column="1" title="Radio Buttons"

style="color:green;">

<property name="store" value="'rs'"/>

<connection from="rsRadio" signal="toggled(bool)" to="setRamStore"

slot="execute(bool)"/>

<connection from="dsRadio" signal="toggled(bool)" to="setDiskStore"

slot="execute(bool)"/>

<script id="setRamStore" >

<property id="storeType" property="text" value="Ram Stores"/>

</script>

<script id="setDiskStore" >

<property id="storeType" property="text" value="Disk Stores"/>

</script>

<widget type="hbox" style="color:black">

<widget type="vbox" row="0" column="0">

<widget id="storeType" type="label" align="left">Ram Stores</widget>

<widget type="stretch"/>

</widget>

<widget type="vbox" row="0" column="0">

<widget id="rsRadio" type="radiobutton" align="left" selected="true">

Ram Stores<ontoggled id="report" property="store" value="'rs'"/>

</widget>

<widget id="dsRadio" type="radiobutton" align="left" >Disk Stores

<ontoggled id="report" property="store" value="'ds'"/>

</widget>


</widget>


</widget>

</widget>

sql

The sql element is used to hold SQL.

Attibutes



Data Definition 88


target

String Id of elment to hold results of

query.

property String Property to write results of query

into.

Child Elements

The widget common child elements, see <widget> common.

Parent Elements

<script>

<widget>

Notes




Example 1

This example is taken from the “Dashboard” macro in the “Reports” sub-menu of the “View” menu of Console. The “ysum” property of the “findysum” script element is set to the result of the query.

<script id="findysum" execute="immediate">

<sql property="ysum">

select sum(RAM_SIZE/1024) from SYS.IPE_PROCESS where TYPE='rs'</sql>

</script>

Example 2

This example is taken from the “Dashboard” macro in the “Reports” sub-menu of the “View” menu of Console. The “y/rangemax” property of the “maxchart” chart widget is set to the result of the query.

<script execute="immediate" id="findymax">

<sql target="maxchart" property="y/rangemax">

select min(RAM_SIZE) from SYS.IPE_PROCESS where TYPE='rs'</sql>

</script>


Data Definition 89

title

The <title> element is used to define the title of a graph.

Attibutes


style

String The stylesheet for the title.

Child Elements

The child nodes are evaluated to obtain the title text. Potential child elements are shown in section “<widget> common” (on page 90), but mainly just a text node will be present in the XML.

Parent Elements


Notes

Example

update

The <update> element is used to define how often a chart or table is refreshed.

Attibutes


timeseries boolean If true then refresh will

add point(s) to those

already displayed in the

graph. If false the refresh

will replace the points.

refresh

Integer, milli-sec Refresh rate

refreshmax Integer, milli-sec

refreshmin Integer, milli-sec


Data Definition 90

Child Elements

none

Parent Elements

<widget>

Notes

Example 1

This example is taken from the “Ram Usage Monitor” macro in the “Reports” sub-menu of the “View” menu of Console. The table is being refreshed every 10 seconds.

<widget type="table" row="3" column="0" minwidth="250" minheight="150"> <update refresh="10000" refreshmin="200" refreshmax="600000" /> <sql>select name "Schema", coalesce(sum(numrecs), 0) "Number of records", coalesce(sum(ram_used / (1024.00 * 1024 * 1024)), 0) "Ram Used (GB) " from ((select s.name, r.numrecs, r.ram_used from sys.ipe_schema s left join sys.ipe_table t on (s.id = t.schema_id and t.type in ('S','T')) left join sys.ipe_ram_images r on (t.id = r.table_id)) union all (select s.name, r.numrecs, r.ram_used from sys.ipe_schema s left join sys.ipe_table t on (s.id = t.schema_id and t.type = 'V') left join sys.ipe_view_img v on (t.id = v.table_id) left join sys.ipe_ram_images r on (v.image_id = r.table_id))) dt (name, numrecs, ram_used) group by 1 order by 3 desc nulls last,2 desc</sql> </widget>

<widget> common

The <widget> element is used to create widgets within a report. There are three basic types:

1. Layout – e.g. grid, hbox, vbox, strectch

2. Qt Widgets – e.g. checkbox, lineedit

3. Custom Widgets – e.g. chart, meter, table,piechart

Attibutes

All widgets share a common set of attributes. Some may also have widget specific attributes.


Data Definition 91



minwidth Integer Minimum width of the element in

pixels

minheight Integer Minimum height of the element in

pixels

Width Integer Preferred/Initial width of the

element in pixels

height Integer Preferred/Initial height of the

element in pixels

style String Style sheet, a subset of HTML

cascading Style sheets (CSS), see

http://qt-project.org/doc/qt-

4.8/stylesheet.html

row Integer If parent is a <report> or <grid>

column Integer If parent is a <report> or <grid>

rowspan Integer If parent is a <report> or <grid>

colspan Integer If parent is a <report> or <grid>

stretch Integer If parent is a <hbox> or <vbox>

align “left”

“right”

“center”

“top”

“Bottom”

“justify”

“hcenter”

“vcenter”

If parent is a <hbox> or <vbox>

Child Elements

Widgets share a set of common child elements. Some of these elements add to the text, others perform processing. The text is initialised to the value of the value attribute if present, then the value of the text attribute is appended to that.

<rowcolumn>

For a dataitem get its child row, and then get the data in a column for that row. The dataitem is specified by source attribute or if not present is the parent object. The row attribute specifies the child dataitem index. The column within the child data item is specified either by the name or index attributes. Using name assumes that the data item has metadata associated with it - in practice this means that it must be the result of a SQL query (including the metadata tree).

<column>

For a data item get the value of one of its columns. The column within the data item is specified either by the name or index attributes. Using name assumes that the data item has metadata associated with it - in practice this means that it must be the result of a SQL query (including the metadata tree).




Data Definition 92

<currentuser>

This adds the current user name to the text.

<data>

Update an object based on data from a source (specified by the source attribute). If the target attribute is defined then update that object, other wise update the parent object. Sources may be “sql” where child nodes are evaluated to create a sql query; “object” where the “dataitem” attribute specifies a data item as the source; or “dataitem” which evaluates the child nodes as in <dataitem> below.

<dataitem>

The text is used to create a data item, with ‘,’ separating columns and ‘;’ separating rows. E.g. “a,b,c” – 1 row of 3 columns, “a,b;c,d;e,f” – 3 rows of 2 columns

<datenow>

This adds the current date to the text.

<foreach>

Evaluate the enclosed text and elements for an each object in specified by <objects> (see above). The objectname attribute name from the set of objects. The id attribute gives an identifier being processed. See the scalemarks

The <scalemarks> element is used to define the scale indications on a graph.

Attibutes


majorxticks

Double Optional, display a long tick on the x

axis every majorxticks values apart.

majoryticks

Double Optional, display a long tick on the y

axis every majoryticks values apart.

minorxticks


x axis every minorxticks values apart.

minoryticks


y axis every minoryticks values apart.

majorxgrid


every majorxticks values apart.

majorygrid



minorxgrid


every minorxticks values apart.

minorygrid Double Optional, display a faint horizontal


Data Definition 93


Child Elements

none

Parent Elements


Notes

Example

script examples from page 83.

<metadata>

This allows selection of DataItem(s) from the metadata tree using xpath specifier.

<property>

This allows a property (identified by the name attribute) of the object (identified by the target attribute, or the parent object if target not present) to be set to a value (the value attribute, or results of evaluating child nodes).

<sql>

Update a property with the results of an SQL query. The target attribute specifies the object to change or the parent object if target not present. The results of the SQL query should be one value, this is used to set the property identified by the property attribute in the target object.

<timenow>

This adds the current time to the text

<value>

Obtain the value of some property (identified by the property attribute) for an object (identified by the source attribute) or from the set of <objects> (identified by the objectname attribute).

Parent Elements

All widgets share a common set of parent elements. Layout widgets may contain other widgets.

<report>


Data Definition 94

<widget>

Signals

All widgets share a common set of signals, most widgets add several more signals which are fired on events specific to that widget.


Slots

All widgets share a common set of slots. Use the <connection> element to connect signals to slots.

clear close deleteLater hide lower raise repaint setDisabled(bool) setEnabled(bool) setFocus setHidden(bool) setShown(bool) setStyleSheet(QString) setVisible(bool) setWindowModified(bool) setWindowTitle(QString) show showFullScreen showMaximized showMinimized showNormal update updateMicroFocus

<widget type=“button”>

The buttot widget is used to create push buttons (QPushButton)


Data Definition 95

Attibutes

For common attributes see section “<widget> common” (on page 90)


Signals

Common signals are shown in section “<widget> common” (on page 90)

clicked

clicked(bool)

clicked(MacroButton*)

pressed

released

toggled(bool)

Slots

Common slots are shown in section “<widget> common” (on page 90)

animateClick

animateClick(int)

click

setChecked(bool)

toggle

update(DataItem*)

Example

<widget type=“chart”>

The chart widget is used to show 2D and 3D charts.

Attibutes




Data Definition 96

Child Elements

<chartformat>

<connection>

<data>

<kogscript>

<property>

<scalemarks>

<script>

<title>

<update>

<x>

<y>

Parent Elements, Signals and Slots

Parent elements, signals and slots are shown in section “<widget> common” (on page 90)

Notes

Example

<widget type=“checkbox”>

The checkbox widget is used to create checkboxes (QCheckBox)

Attibutes



checked Boolean Set “true” if the checkbox is to be

initially checked.

Child and Parent Elements

Child and parent elements are shown in section “<widget> common” (on page 90)


Data Definition 97

Signals

Common signals are shown in section “<widget> common” (on page 90)

clicked

clicked(bool)

pressed

released

stateChanged(int)

stateChanged(MacroCheckBox*,int)

toggled(bool)

Slots

Common slots are shown in section “<widget> common” (on page 90)

animateClick

animateClick(int)

click

onStateChanged(int)

setChecked(bool)

toggle

update(DataItem*)

Example

<widget type=“combobox”>

The combobox widget is used to make a selection from a list of options (QComboBox)

Attibutes



index Integer Index of the element which is

initially selected.

col Integer Column in dataitem to be used for the

list data.


Data Definition 98

Child Elements

For common child elements see section “<widget> common” (on page 90)

<onactivated>

When a selection is made from the combo box then the onactivated element may be used to set a property of the element identified by the “id” attribute from the selected value.

Parent Elements

For common parent elements see section “<widget> common” (on page 90)

Signals

activated(int) activated(MacroComboBox*,int) activated(QString) currentIndexChanged(int) currentIndexChanged(QString) editTextChanged(QString) highlighted(int) highlighted(QString) selected(DataItem*)

Slots

clearEditText onActivated(int) setCurrentIndex(int) setEditText(QString) update(DataItem*)

Examples

The following examples give the UI shown below. To avoid clutter some “hbox” and “vbox” container widgets are not shown.


Data Definition 99

Example 1

This example shows choosing between London, Paris and NewYork. This uses the onActivated element to set the “text” property of a label with the selected value of the ComboBox.

<widget type="groupbox" row="1" column="3" title="Combo Boxes"

style="color:green">

…

<widget type="hbox" row="0" column="0" style="color:black">

<widget id="combo1Lab" type="button" align="left">Paris</widget>

<widget id="combo1" type="combobox" align="left" index="1">

<dataitem>London,Paris,New York</dataitem>

<onactivated id="combo1Lab" property="text"/>

</widget>

</widget>

…

</widget>

Example 2

This example shows choosing between Red, Blue and Green. This uses a connector to connect up the ComboBox selected(DataItem*) signal with a script (id=“setColour”) which sets the “text” property of a label to the colour name which is also coloured in that colour using a CSS-like style.

<widget type="groupbox" row="1" column="3" title="Combo Boxes" style="color:green"> …

<connection from="combo2" signal="selected(DataItem*)" to="setColour"

slot="execute(DataItem*)"/>

<script id="setColour" param="row">

<property id="combo2Lab" property="text"> <html><head><meta

name=\"qrichtext\" content=\"1\" /></head><body>

<span style="color:<column id="row" index="0"/>"><column id="row"

index="0"/></span></property>

</script>


<widget id="combo2Lab" type="label"

align="left"><html><head><meta

name=\"qrichtext\"

content=\"1\" /></head><body><span

style="color:red">Red</span></widget>

<widget id="combo2" type="combobox" align="left" column="0">

<dataitem>Red,Blue,Green </dataitem></widget> </widget>

…


Data Definition 100

</widget>

Example 3

This example shows choosing an animal name from a DataItem containing names and types. This uses a connector to connect up the ComboBox selected(DataItem*) signal with a script (id=“setAnimal”) which sets the “text” property of a label to the animal type which is obtained from the DataItem passed to the script from the connection. The ComboBox uses a DataItem with three children, one child for each of the type, name pairs.

<widget type="groupbox" row="1" column="3" title="Combo Boxes 3" style="color:green">

…

<connection from="combo3" signal="selected(DataItem*)" to="setAnimal"

slot="execute(DataItem*)"/>

<script id="setAnimal" param="row">

<property id="combo3Lab" property="text"><column id="row" index="0" />

</property>

</script>


<widget id="combo3Lab" type="label" align="left">Bear</widget>

<widget id="combo3" type="combobox" align="left" headers="Animal,Name"

column="1"> <dataitem>Bear,Poo;Bear,Yogi;Dog,Lassie </dataitem> </widget>

</widget>

…

</widget>

<widget type=“groupbox”>

The groupbox widget is used to group other widgets (QGroupBox) and provide a border and title for that group.

Attibutes



title String

Child Elements

For common child elements see section “<widget> common” (on page 90)

<connection>

<kogscript>

<script>

<sql>

<widget>


Data Definition 101

Parent Elements

For common parent elements see section “<widget> common” (on page 90)

Signals

For common signals see section “<widget> common” (on page 90)

clicked clicked(bool) toggled(bool)

Slots

For common slots see section “<widget> common” (on page 90)

setChecked(bool)

Notes

Example

<widget type="groupbox" row="2" column="0" title="GroupBox" style="color:green">

<widget type="grid">

<widget type="groupbox" row="0" column="0" colspan="2" title="0,0"

style="color:blue">

<widget type="vbox">

<widget type="label" align="left" style="color:black">0,0->0,1</widget>

</widget>

</widget>

<widget type="groupbox" row="0" column="2" rowspan="2" title="0,2"

style="color:blue">


<widget type="label" align="left" style="color:black">0,2->1,2</widget>

</widget>

</widget>

<widget type="groupbox" row="1" column="0" title="0,0" style="color:blue">


<widget type="label" align="left" style="color:black">1,0</widget>

</widget>

</widget>

<widget type="groupbox" row="1" column="1" title="0,0" style="color:blue">



Data Definition 102

<widget type="label" align="left" style="color:black">1,1</widget>

</widget>

</widget>

</widget>

</widget>

<widget type=“grid”>

The grid widget is used to create a grid layout container to hold other widget elements.

Attibutes



Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“hbox”>

The hbox widget (QHBoxLayout) is used to create a horizontal layout container to hold other widgets.


Data Definition 103

Attibutes



Child and Parent Elements, Signals and Slots

The hbox widget has the common child and parent elements, signals and slots, see section “<widget> common” (on page 90)

<widget type=“image”>

The image widget is used to display bitmap images within a report. It is based on QLabel.

Attibutes



file String Path to the image, relative to the

location of the macro XML file.

Child and Parent Elements, Signals and Slots

The hbox widget has the common child and parent elements, signals and slots, see section “<widget> common” (on page 90)

Example

<widget type=“label”>

The label widget is used to include non-editable text within a report, it is based on QLabel.


Data Definition 104

Attibutes



Parent and Child Elements

The hbox widget has the common child and parent elements, see section “<widget> common” (on page 90)

Signals

The hbox widget has the common signals, see section “<widget> common” (on page 90), plus those below

linkActivated(QString)

linkHovered(QString)

Slots

The hbox widget has the common slots, see section “<widget> common” (on page 90), plus those below

clear

setNum(double)

setNum(int)

Example

<widget type=“lineedit”>

The lineedit widget is used to include a single line of editable text within a report, it is based on QLineEdit.

Attibutes




Data Definition 105

Child Elements

The hbox widget has the common child elements, see section “<widget> common” (on page 90)

<validator>

The type attribute gives the validator type which may be one of ‘date’, ‘time’, ‘regexp’, ‘int’, ‘double’. If the validator type is ‘regexp’ there is an additional regexp attribute which is a Qt regular expression. If the validator type is ‘int’ or ‘double’ there are two further attributes bottom and top these are the minimum and maximum allowed values respectively. The Date validator assumes dates are in the format yyyy-mm-dd and the time validator assumes times are in the format hh:mm:ss

Parent Elements

The hbox widget has the common parent elements, see section “<widget> common” (on page 90)

Signals

The hbox widget has the common signals, see section “<widget> common” (on page 90), plus those below

cursorPositionChanged(int,int)

editingFinished

returnPressed

selectionChanged

textChanged(QString

textEdited(QString)

Slots

The hbox widget has the common slots, see section “<widget> common” (on page 90), plus those below

clear

copy

cut

paste

selectAll

setText(QString)

update(DataItem*)


Data Definition 106

Example

<widget id="time" type="lineedit" row="2" column="1" minwidth="50" style="color:blue">23:59:59

<property id="inputMask" value="00:00:00"/> </widget>

<widget type=“meter”>

The < > is used to

Attibutes



Child Elements

<connection>

<data>

<kogscript>

<property>

<rangemax>

<rangemin>

<scale>

<script>

<update>

Parent Elements

<report>

<widget>

Signals


Slots

close deleteLater hide


Data Definition 107

lower raise refreshMeter repaint setDisabled(bool) setEnabled(bool) setFocus setHidden(bool) setPropertyFromValue(const char*,QString) setShown(bool) setStyleSheet(QString) setupViewport(QWidget*) setVisible(bool) setWindowModified(bool) setWindowTitle(QString) show showFullScreen showMaximized showMinimized showNormal update updateMeter(SQLProcessorJob*)

updateMicroFocus

Notes

Example


Data Definition 108

<widget type=“piechart”>

The < > is used to

Attibutes


Child Elements

<connection>

<data>

<kogscript>

<properties>

<property>

<script>

<title>

Parent Elements

<report>

<widget>

Signals


Slots

close deleteLater hide lower raise repaint setDisabled(bool) setEnabled(bool) setFocus setHidden(bool) setPropertyFromValue(const char*,QString) setShown(bool)


Data Definition 109

setStyleSheet(QString) setupViewport(QWidget*) setVisible(bool) setWindowModified(bool) setWindowTitle(QString) show showFullScreen showMaximized showMinimized showNormal update updateMicroFocus

Notes

Example

<widget type=“radiobutton”>

The < > is used to

Attibutes



selected Boolean Set “true” if the radio button is to

be initially selected.


Data Definition 110

Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“server”>

The <widget type=“server”> is used to display a Label showing the Kognitio Application Platform server Console is connected to.

Attibutes




Data Definition 111

Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“slider”>

The < > is used to

Attibutes




Data Definition 112

Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“stretch”>

The < > is used to

Attibutes




Data Definition 113

Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“table”>

The < > is used to

Attibutes



Child Elements

<connection>

<kogscript>

<property>

<script>

<sql>

Parent Elements

<report>

Signals

customContextMenuRequested(QPoint) destroyed()


Data Definition 114

destroyed(QObject*)

Slots

close deleteLater hide lower raise refreshTable

repaint setDisabled(bool) setEnabled(bool) setFocus setHidden(bool) setPropertyFromValue(const char*,QString) setShown(bool) setStyleSheet(QString) setupViewport(QWidget*) setVisible(bool) setWindowModified(bool) setWindowTitle(QString) show showFullScreen showMaximized showMinimized showNormal update updateMicroFocus updateTable(SQLProcessorJob*)

Notes

Example


Data Definition 115

<widget type=“username”>

The <widget type=“username”> element is used to display the user name of the connection to the Kognitio Application Platform.

Attibutes



Child Elements

Parent Elements

Signals

Slots

Example


Data Definition 116

<widget type=“vbox”>

The <widget type=“vbox”> is used to create a vertical layout container to hold other widget elements.

Attibutes



Child Elements

Parent Elements

Signals

Slots

Example


Data Definition 117


Data Definition 118

Data Definition 119

5

Using KogScript In Macros

Since October 2012 Kognitio Scripts may be used within Macros. As they are based on Lua with Kognitio extensions they can be very powerful.

At present Kognitio Scripts are not connected into the Console UI object hierarchy or into the metadata tree of DataItems. In future Kognitio Scripts may be used to manipulate UI elements and change the metadata tree. This will allow, for instance, a dialog to be show, SQL to be run based on user entered values into the dialog, then the metadata tree updated.

A Quick Introduction To Lua

Lua is a small scripting language, specifically designed to be easy to integrate into applications. It has the usual control structures, functions, tables and coroutines.

Nil

Nil is a type with a single value, nil, which is different than any other Lua value. Assigning nil to a global value deletes it.

Booleans

Booleans have values true and false. Conditionals consider false and nil as false and any other value as true.


Data Definition 120

Numbers

All numbers in Lua are double precision floats. There is no integer type.

Strings

Strings are immutable sequences of characters. Strings may contain any character (including embedded zeros), so binary data may be stored in a string.

Strings are delimited by either single (‘a string’) or double quotes (“another string”) or [[ ]] ([[ a string with new lines in it]]. C-like ‘\’ escapes may be used to include tabs (\t), new lines (\n), etc.

Tables

The basic data structure in Lua is the table. Tables are associative arrays, indexed by numbers, strings or any other value in the language. Empty tables are created with {}. Variables refer to tables by reference. When there are no references to a table it will be garbage collected.

Functions

Functions are first class values which may be stored in variables, passed as arguments to other functions and returned as results.

Lua functions may be written in C or Lua. Predefined Lua functions and Kognitio Console extensions are written in C.

Lua functions offer good support for functional programming, closures, proper tail calls, etc.

Userdata

Lua allows extensions to have their own arbitrary C data stored in the userdata type. Console uses userdata to link Lua to Qt.

Threads

Threads use coroutines within a single processor thread. Console also uses lanes to implement Linda, which uses multiple processor threads.


Data Definition 121

Metatables

Each value in Lua may have a metatable. Tables and userdata have individual metatables, values for other types share one single metatable for all values of that type.

Metatables and first class functions allow object-orientated programming.=

Expressions

Lua has the usual arithmetic (+, -, * / ^ %) operators which all act on Lua numbers (double floating point values).

Lua has the usual relational operators (>, <, >=, <=, ==) ~= is used for not equals. Lua compares table, userdata and functions by reference, that is two variables are equal only if they refer to the same object.

Lua has the and, or and not logical operators.

Concatenation of two string is performed by the .. operator.

Tables may be constructed by the {} constructor. This can create empty tables (e.g. t={} ), arrays (e.g. t={“one”, 2} ) and maps (e.g. t={x=1,y=2} ).

Statements

Asignment may include multiple assignment (e.g. a,b = 1,2)

Variables may be made local, in which case their scope is limited to the block in which they are declared.

Lua uses an if statement of the form: if … then … elseif … else … end

Lua uses a while statement of the form while … do … end

Lua uses a repeat statement of the form repeat … until …

Lua has two styles of for starements, numeric for and generic for. Numeric for statements have the form: for var=exp1,exp2[,exp3] do … end, where the loop will execute with var set to each value between exp1 and exp2 (inclusive) using the optional exp3 as the step to increment var. Generic for loops traverses all values returned from an iterator function: for i,v in iter do … end, common iterator functions are ipairs() and pairs() which iterate over the values of a table.

Functions

Lua provides a limited number of built-in functions and the Kognitio extensions adds more, these will be described later.


Data Definition 122

Functions may be defined like:

function name (params) … [return values(s)] end

or

name = function (params) … [return value(s)] end.

or as an anonymous function

function (params) … [return value(s)] end.

Functions may return multiple values.

Kog Script Extensions

Kogitio has added naked SQL to Lua. These take the form

[value =] SQL statement ;

Unlike Lua where semi-colons are optional in most circumstances a ; is required at the end of a naked SQL statement.

Within the SQL statement $ takes on a special meaning, the characters following it are treated as a variable name and the current Lua value of that variable are substituted when the statement is executed.

Naked SQL is just syntactic sugar on top of the global sql() function which takes one or more strings, executes them as SQL and returns the result of the last statement as a table. $ variables are concatenated into the string.

e.g.

v = “ipe_users” t = select * from $v;

is equivalent to:

v = “ipe_users” t = sql(“select * from” .. v)

Brackets may be used to delimit the extent of the characters that make up the variable. So this is also equivalent:

v = “ipe_users” t = select * from $(v);


Data Definition 123

table. table.rows - the resultset returned from the SQL statement (if any).

Kog Script Built-in Functions

Lanes

QtLua

Data Definition 124

6

Using Old Style SQL Scripts In Macros

Up until October 2012 old style SQL scripts where the only script implemented in Kognitio Console. Since then Kognitio Scripts (based on Lua) are also implemented and will become the default in future as they are much more powerful.

SQL scripts as implemented by Kognitio Console have a sub-set of the commands which are implemented in WxSubmit command line tool. The KogScript command line tool is primarily designed to run Kognitio Scripts (based on Lua), but may also be used to run SQL scriptsas well, it uses the same scripting engine as Kognitio Console.

The old style SQL script commands are given below. These may be run in the <script> tag.

Variables

A sequence of non-space characters starting with a letter. Variables are substituted when preceded by a ‘$’ <variable> script variable name <varref> '$'<variable> Examples:

set var x 10; if $x <20 goto loop; set var schema sys;

Public Chapter 6 - Using Old Style SQL Scripts In Macros

Data Definition 125

set var tbl ipe_user; select * from $schema.$tbl

Assignment

<variable> '=' <value> ';' Not implemented

Connect statement

'connect' 'to' <server> 'user' <username> [ 'using' | 'password' ] <password> Examples:

connect to kog_10 user sys using mySecretPassword; connect to kog_5 user john password wibble54;

Describe Command

Executes Kognitio analytics platform SQL describe syntax.

Disconnect Statement

'disconnect'

Edit Command

Not implemented, this is only useful for WxSubmit.

Errorcode Command

Not implemented, only relevant for WxSubmit

Chapter 6 - Using Old Style SQL Scripts In Macros Public

Data Definition 126

Errorcodenot Command


Export Command

'export' 'from' <something> 'export' <anything else> -- not implemented Executes Kognitio analytics platform SQL export from syntax.

Goto Command

'goto' <label> [‘:’] ; Examples:

set var n 0 loop: …. select $n + 1 set var n $col1 if $n < 10 goto loop;

Help Command

Not implemented

If Statement

'if' <varref> <cmp> <varref> <command> <cmp> '=': equality '==': equality '!=': not equals '>': greater than '<': less than '>=': greater than or equals '<=': less than or equals If both variables are integers then do an integer comparison, otherwise treat both variables as strings and do a string comparison


Data Definition 127

Include Command

'include' <filename> <filename> stringWithoutSpaces “string with spaces” ‘string with spaces’ Script variables which are set in the base script are passed to the included script. This allows simple function-like behaviour. NOTE: variables set in the included script are not visible to the base script. Example: base.scr

set var name 'john'; include included.scr; set var name 'sue'; include included.scr;

included.scr

select * from sys.ipe_user where name=$name;

Results Command


Returncode Command


Set Statement

'set {'var' | 'variable'} <variable> [<value>] ';' 'set' 'prompt' <variable> <type> <prompt> ';' 'set' 'mode' {'transaction' | 'autocommit'} ';' 'set' 'schema' <schema name> ';' 'set' 'time' 'zone' { <interval> | 'local' } <value> string (may include spaces, newlines) up to ';' <type> 'NUMBER': only allow numbers in the variable 'CHAR': the variable can be any sequence of characters <prompt> String to show to the user


Data Definition 128

Set schema and set time zone are WX2 SQL commands all the rest are script commands implemented in Kognitio Console. Examples

set var x 10; -- x == “10” set var schema sys; -- schema == “sys” set var tbl ipe_user; -- tbl == “ipe_user” set var n from sys.ipe_user; -- n == “from sys.ipe_user” set var m from $schema.$tbl; -- m == “from sys.ipe_user” set prompt x NUMBER “Enter count”; -- ask user to supply value for count set prompt tbl CHAR “Table to update”;-- ask user to supply table name set mode transaction; -- set the database into transaction mode set mode autocommit; -- set the database into autocommit mode set schema mike; -- set default schema to “mike” set time zone local; -- set the time zone to the local timezone set time zone ‘-7:00’; -- set the time zone to 7 hours behind UTC

Setvar Command

Not implemented

Shell Command

'shell' <string> ';' <string> "char sequence not including double quote" 'char sequence not including single quite' The shell command executes a string as an operating system shell script command. On MS Windows each command has to be in a separate shell command like: shell 'cmd.exe /C help'; shell 'cmd.exe /C pwd'; On MS Windows it is not possible to change the working directory by: shell 'cmd.exe /C cd C:\somepath'; -- does not work shell 'cmd.exe /C pwd'; -- working directory unchanged Instead use: set var shell_dir C:\somepath; shell 'cmd.exe /C pwd'; -- working directory set to c:\somepath Example: base_cmd.sql

shell 'cmd.exe /C pwd'; set var shell_dir C:\cygwin; set var shell_test 'test1';


Data Definition 129

include included_cmd.sql; set var shell_dir C:\program files; set var shell_test 'test2'; include included_cmd.sql;

include_cmd.sql

select $shell_test; shell "cmd.exe /C pwd";

Show Command

Not implemented. There is no need to have a command show the value of variables in Kognitio Console, the script variables pane does that.

Whenever Statement

'whenever' {'sqlerror'|'oserror'} <perform-action> [<transaction-behaviour>] <perform-action> 'continue success': don't increment error count 'continue failure': increment the error count 'continue': as 'continue' failure which is the default. 'exit success': on error, exit with code 0. 'exit failure': on error, exit with code 1. 'exit <exit-code>': on error, exit with code <exit-code>. 'exit': as 'exit success'. <transaction-behaviour> (only relevant in transaction mode) 'commit': commit the transaction. 'rollback': roll back the transaction. 'none': do not change the transaction state. this is the default if the transaction behaviour is not specified Examples

Quit Command

'quit' Stop script execution Examples

select * from sys.ipe_system if $numrows <> 1 quit;


Data Definition 130

Script variables

The Kognitio script engine creates various variables automatically. These may be used in the same places as script variables created by the set command. "SQLState" – default= "OK" set to ”” on error "WCSerror" – default= "OK" Kognitio analytics platform error code "NumRows" – default= "" number of rows returned by last query "NumColumns" – default= "" "Col1" – default= "" column names of first five columns "Col2" – default= "" "Col3" – default= "" "Col4" – default= "" "Col5" – default= "" "QueryNumber" – default= "0" "CompileTime" – default= "0" "ExecuteTime" – default= "0" "FirstRowTime" – default= "0" "TotalTime" – default= "0" "SQLStateStr" – default= "'OK'" string versions of "SQLState” "WCSerrorStr" – default= "'OK'" string version of “WCSerror” "Col1Str" – default= "''" "Col2Str" – default= "''" "Col3Str" – default= "''" "Col4Str" – default= "''" "Col5Str" – default= "''" Server version variables:

"sysver"; e.g. 07.02.0001 "sysverStr"; e.g. ’07.02.0001’ "cliver"; client (Console) version, e.g. 07.02.02-s120531 "cliverStr"; e.g. ‘07.02.02-s120531’ Script Variables used by console: "history_mode” values of "none”, "all”, "sql”, "script"; "history_group" some string used for grouping queries in the query history tab "error_mode" values of "stop, "continue, "debug" What to do on encountering an error in a SQL statement "script_fail_mode" values of "stop, "continue, "debug" What to do on encountering an error in a script statement( “if”, “goto”,

etc.) "fail_mode" values of "stop, "continue, "debug" What to do on encountering an error in a script test command ( test commonada are not implemented in Console at present).


Data Definition 131

Example 1:

This example shows a SQL script being run from the menu “My Scripts” -> “Included Script”



<name>IncludedTest</name>

<menu position="2">My Scripts</menu>

<actiontext>Included Script</actiontext>

<script>

include "some-script.sql";

</script>

</wx2macro>

Data Definition 132

Data Definition 133

7

Putting It All Together

This chapter discusses how macros are used, which directories they are placed in and how to write effective macros.

How Macros Are Used

As an action on metadata objects

The example below shows how one or more plugins may be activated:



<name>ActivatePlugin</name>

<actiontext>Activate Plugin</actiontext>

<objects>

<object option="1+">plugin</object>

</objects>

<script>

<foreach objectname="plugin" id="p">

ALTER MODULE <value id="p" property="name"/> SET MODE ACTIVE;

</foreach>

</script>

</wx2macro>

Monitors

A monitor is a macro which repeatedly runs some SQL to obtain up-to-date information from the database. The following example shows a concurrency monitor which is updated every 10 seconds.

Chapter 7 - Putting It All Together Public

Data Definition 134



<name>Concurrency Monitor</name>


<actiontext>Concurrency Monitor</actiontext>

<objects>

</objects>

<report>

<widget type="hbox" row="0" column="0" colspan="1" style="color:#FFFFFF">

<widget type="label" style="color:#0E5CAE;font-size:32px;font-weight:bold">WX2

Concurrency Monitor</widget>

<widget type="server" style="color:#FF0000;font-size:32px;font-weight:bold"/>


</widget>

<widget type="chart" row="1" column="0" minwidth="250" minheight="200" >

<chartformat type="column" subtype="3-D" angle="30" depth="10%" mindepth="20"/>

<scalemarks majorxgrid="10" minorxgrid="5"/>

<update refresh="10000" refreshmin="2000" refreshmax="600000" />

<title style="color:black;font-size:12px;font-

weight:bold"><html><head><meta name=\"qrichtext\" content=\"1\"

/></head><body>Concurrency Level - <span

style="color:red">red</span> for sessions awaiting locks, <span

style="color:blue">blue</span> for idle sessions, <span

style="color:green">green</span> for all

sessions.</body></html></title>

<x>

<title style="font-weight:bold">Time</title>

<datapoints>20</datapoints>

</x>

<y>

<title style="font-weight:bold" type="value">Concurrent sessions</title>

<rangemax type="value">100</rangemax>

<rangemin type="value" >0</rangemin>

<series datacol="0" barcolor="red" label="Awaiting locks"/>

<series datacol="1" barcolor="blue" label="Idle sessions"/>

<series datacol="2" barcolor="green" label="All sessions"/>

</y>

<data>select a.a1,b.b1,c.c1 from (select count(distinct session_id) from

sys.ipe_locks where status = 'PENDING') a(a1),(select count(*) from

sys.ipe_cursessions where command_running = 0) b(b1),(select count(*) from

sys.ipe_cursessions) c(c1)</data>

</widget>

</report>

</wx2macro>

Reports

Reports contain SQL that is executed once. They often contain an update button. This is connected to the table(s) to refresh the table when the update button is clicked.



<name>Locks Report</name>


<actiontext>Locks Report</actiontext>

<requiredserverversion major="7" minor="9" increment="1"/>

<objects>

</objects>

<report>

<connection from="updateButton" signal="clicked()" to="locksTable"

slot="refreshTable"/>

<connection from="updateButton" signal="clicked()" to="timeTable"

slot="refreshTable"/>

<widget type="hbox" row="0" column="0" colspan="1" style="color:black">


Data Definition 135

<widget type="label" style="color:#0E5CAE;font-size:32px;font-weight:bold">Locks

Report</widget>

<widget type="server" style="color:#FF0000;font-size:32px;font-weight:bold"/>


<widget id="updateButton" type="button" align="left">Update Report<onclick

id="but2" property="down" value="true"/></widget>


</widget>

<widget type="label" row="1" column="0">Current locks held and pending:</widget>

<widget id="locksTable" type="table" row="2" column="0" minwidth="250"

minheight="300">

<sql>select c.user_id "User", c.session "Session", l.tno "Transaction", l.type

"Lock Type", trim(s.name) || '.' || trim(t.name)"Table", l.row_hash "Row Hash",

l.status "Status", l.queue_time "Queued Time", l.grant_time "Grant Time", case

c.command_running when 0 then 'Idle' when 1 then 'Running' when 2 then 'Statement

rollback' when 3 then 'Transaction rollback' when 4 then 'Queued' when 5 then

'Compiling' when 6 then 'Awaiting interpreter' else 'Unknown' end "Status",

c.last_command "Command" from sys.ipe_cursessions c, sys.ipe_locks l, sys.ipe_schema

s, sys.ipe_table t where l.session_id = c.session and s.id = t.schema_id and t.id =

l.table_id order by 5,6,7</sql>

</widget>

<widget id="timeTable" type="table" row="3" column="0" height="70">

<sql>select current_timestamp "Report time"</sql>

</widget>

</report>

</wx2macro>

Object view tab

Macro Directories

Installation directory

Macros within the installation directory are loaded once at Console start-up.

These are the macros that come with the application and are placed in this directory on installation. Macros will not be removed from this directory, but may be updated. Occasionally a macro will no longer be needed, in that case the type will be changed to obsolete-*, e.g.

<wx2macro type="obsolete-objectaction">

User Macro directory

The user macro directory will be

C:\Users\ <user> \.wxconsole\macros

or similar on Windows.


Data Definition 136

Macros contained here are reloaded every time they are needed (i.e. when the view menu is shown). This means that during macro development they may be changed in an editor and the changed macro immediately reloaded.

User QuickViz directory

QuickViz macros are in

C:\Users\ <user> \.wxconsole\quickviz

This directory is searched for relevant quickviz macros for a table. Macros here will have an id like:

<wx2macro type="objectaction" id="QuickViz:MPID:MESSAGES_OUT:MESSAGES_IN">

This means this QuickViz macro is relevant for any tables with three columns named: MPID, MESSAGES_OUT and MESSAGES_IN (in that order).

Writing effective macros

The macro XML is constantly being improved. Do not rely on behaviour which is not documented here, as that behaviour may change at any time.

QuickViz - Creating macros the easy way

Suppose you have a query:

select

case when st.slabid is null then 'Total '

else cast(to_char(st.slabid,'9999999') as varchar(7)) end as "Slab ID",

cast(to_char(st.usedgb+st.freegb,'999,990.9') as varchar(9)) as "Slab GB",

cast(to_char(st.usedgb,'999,990.9') as varchar(9)) as "Used GB",

cast(to_char(st.freegb,'999,990.9') as varchar(9)) as "Free GB",

cast(to_char((st.usedgb*100)/(st.usedgb+st.freegb),'990.9') || '%' as varchar(6)) as

"% Used"

from

(select

s.slab_id as slabid,

sum(s.data_stored*x.cu_size)/power(1024,3) as usedgb,

sum(s.free_space*x.cu_size)/power(1024,3) as freegb

from sys.ipe_disk_slab s,

sys.ipe_xor_element x

where s.mpid=x.mpid

group by grouping sets ((s.slab_id),())) st(slabid,usedgb,freegb)

order by st.slabid desc nulls last;


Data Definition 137

This gives a table of RAM usage against slab ID. Right-click on the table and from the popup menu select QuickViz -> Create QuickViz. Fill in the dialog as shown below:

Then click “create macro”. A new macro will be created in the <user home>/.wxconsole/macros directory. It will appear on the View -> QuickViz menu as Slab RAM Usage selecting that will run the query and display the graph again.

If instead the default “Visualise” button had been clicked then a macro would have been created in <user home>/.wxconsole/quickviz. This will be shown on the right-click popup menu as QuickViz -> QuickViz: Slab RAM Usage for any table which has columns named “Slab ID”, “Slab GB”, “Used GB”, “Free GB” and “% Used” (in that order). This allows QuickViz macros to be used to visualise data without rerunning the query, so for instance, several QuickViz graphs may be shown for the same table.


Data Definition 138

A

Index No index entries found.

Kognitio Console Scripting and Macros - Amazon S3 · Then the SQL Script button will create a Kog...

Documents

Transcript of Kognitio Console Scripting and Macros - Amazon S3 · Then the SQL Script button will create a Kog...