Console Scripting and Macro Guide - DMG Federal€¦ · Web viewThis manual describes Console...

Kognitio Console Scripting and Macros

Version 7.9.3March 2013

Public

NoticesThis 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 Scripting and Macro Guide, October 2012Kognitio Technology Centre© Kognitio Limited, 2002-20123A Waterside Park, Cookham RoadBRACKNELL, Berks, RG12 1RB United Kingdom

Public

Public Preface

About this ManualThis 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.

Console Scripting and Macro Guide iii

http://www.lua.org/

ContentsAbout this Manual...................................................................................iiiContents.................................................................................................v

1 Kog Scripting....................................................................................................xv

1.1 Getting Started.............................................................................................xv1.2 Naked SQL...................................................................................................xvi

Global Variables.....................................................................................xviiSQL statements returning a table..........................................................xixUsing $ substitution within SQL statements...........................................xx

1.3 KogScript command line tool.......................................................................xxi1.4 Using require in Kog scripts.........................................................................xxii

Package Path.........................................................................................xxiiiLUA_PATH.............................................................................................xxivStandard Library Location......................................................................xxiv

1.5 What Happens “under the hood”..................................................................xxv1.6 Other Kognitio Extensions............................................................................xxvi

Shell.......................................................................................................xxviTable __toString()...................................................................................xxviMixed Lua and Kog scripts.....................................................................xxviLua Lanes...............................................................................................xxvi

1.7 Compatibility with SQL Script.......................................................................xxviiWhenever...............................................................................................xxviiLoops......................................................................................................xxviiJump to error exit...................................................................................xxviiiMove large chunks of code into functions..............................................xxixUse functions with parameters for similar SQL......................................xxix

2 Kog Script Libarary..........................................................................................31

2.1 Lua builtin library functions...........................................................................31_G...........................................................................................................31_VERSION.............................................................................................31assert......................................................................................................32collectgarbage........................................................................................32dofile.......................................................................................................33error........................................................................................................33

Console Scripting and Macro Guide v

getmetatable...........................................................................................34ipairs.......................................................................................................34load.........................................................................................................35loadfile....................................................................................................36next.........................................................................................................36pairs........................................................................................................37pcall........................................................................................................38print........................................................................................................38rawequal.................................................................................................38rawget.....................................................................................................39rawlen.....................................................................................................39rawset.....................................................................................................39require....................................................................................................40selectfrom...............................................................................................40select......................................................................................................41setmetatable...........................................................................................41shell........................................................................................................42sql...........................................................................................................42tonumber................................................................................................43tostring....................................................................................................43type.........................................................................................................44xpcall......................................................................................................44bit32.band...............................................................................................44bit32.lshift...............................................................................................44bit32.bxor................................................................................................44bit32.extract............................................................................................45bit32.lrotate.............................................................................................45bit32.arshift.............................................................................................45bit32.rshift...............................................................................................45bit32.rrotate............................................................................................45bit32.bnot................................................................................................45bit32.replace...........................................................................................45bit32.bor.................................................................................................45bit32.btest...............................................................................................46debug.getinfo..........................................................................................46debug.traceback.....................................................................................46debug.getupvalue...................................................................................46debug.getuservalue................................................................................46debug.getlocal........................................................................................46debug.debug..........................................................................................46

Console Scripting and Macro Guide vi

debug.upvaluejoin..................................................................................46debug.upvalueid.....................................................................................47debug.gethook........................................................................................47debug.getregistry....................................................................................47debug.getmetatable................................................................................47debug.setmetatable................................................................................47debug.setlocal........................................................................................47debug.sethook........................................................................................47debug.setupvalue...................................................................................47debug.setuservalue................................................................................48os.time....................................................................................................48os.exit.....................................................................................................48os.getenv................................................................................................48os.difftime...............................................................................................48os.setlocale............................................................................................48os.remove...............................................................................................48os.rename..............................................................................................48os.tmpname............................................................................................49os.execute..............................................................................................49os.clock..................................................................................................49os.date....................................................................................................49math.modf..............................................................................................49math.asin................................................................................................49math.tan.................................................................................................49math.exp.................................................................................................49math.atan...............................................................................................50math.acos...............................................................................................50math.max................................................................................................50math.min.................................................................................................50math.deg................................................................................................50math.randomseed..................................................................................50math.pow................................................................................................50math.ceil.................................................................................................50math.floor...............................................................................................51math.abs.................................................................................................51math.cosh...............................................................................................51math.sin..................................................................................................51math.frexp..............................................................................................51math.random..........................................................................................51math.sinh................................................................................................51

Console Scripting and Macro Guide vii

Preface

math.tanh...............................................................................................51math.ldexp..............................................................................................52math.cos.................................................................................................52math.log..................................................................................................52math.atan2.............................................................................................52math.fmod..............................................................................................52math.sqrt................................................................................................52math.rad.................................................................................................52io.flush....................................................................................................52io.lines....................................................................................................53io.popen..................................................................................................53io.stderr..................................................................................................53io.open....................................................................................................53io.input....................................................................................................53io.stdout..................................................................................................53io.stdin....................................................................................................53io.output..................................................................................................53io.close...................................................................................................54io.read....................................................................................................54io.tmpfile.................................................................................................54io.type.....................................................................................................54io.write....................................................................................................54string.format...........................................................................................54string.byte...............................................................................................54string.gmatch..........................................................................................54string.char...............................................................................................55string.lower.............................................................................................55string.upper............................................................................................55string.len.................................................................................................55string.sub................................................................................................55string.dump.............................................................................................55string.reverse..........................................................................................55string.rep................................................................................................55string.match............................................................................................56string.gsub..............................................................................................56string.find................................................................................................56table.insert..............................................................................................56table.__tostring.......................................................................................56table.concat............................................................................................56table.pack...............................................................................................56

Console Scripting and Macro Guide viii

table.sort.................................................................................................56table.remove...........................................................................................57table.unpack...........................................................................................57coroutine.status......................................................................................57coroutine.resume....................................................................................57coroutine.yield........................................................................................57coroutine.running....................................................................................57coroutine.wrap........................................................................................57package.config.......................................................................................57package.cpath........................................................................................58package.loaded......................................................................................58package.loadlib......................................................................................58package.path..........................................................................................58package.preload.....................................................................................58package.searchers.................................................................................58package.searchpath...............................................................................58

2.2 Kog Script std library....................................................................................59string.format...........................................................................................59

2.3 std.base........................................................................................................59std.assert................................................................................................59std.bind...................................................................................................60std.collect...............................................................................................60std.compose...........................................................................................60std.concat...............................................................................................61std.curry..................................................................................................61std.die.....................................................................................................62std.eval...................................................................................................62std.filter...................................................................................................62std.fold....................................................................................................63std.id.......................................................................................................63std.ileaves..............................................................................................63std.inodes...............................................................................................64std.leaves...............................................................................................64std.map...................................................................................................64std.memoize...........................................................................................65std.metamethod......................................................................................65std.nodes................................................................................................65std.op......................................................................................................66std.pack..................................................................................................66std.pickle................................................................................................66

Console Scripting and Macro Guide ix

Preface

std.prettytostring.....................................................................................67std.render...............................................................................................67std.ripairs................................................................................................68std.tostring..............................................................................................68std.totable...............................................................................................69std.warn..................................................................................................69std.class.................................................................................................70std.list.....................................................................................................71

2.4 std.strbuf......................................................................................................71__concat.................................................................................................71__tostring................................................................................................71

2.5 std.string.......................................................................................................71...............................................................................................................72[ ]............................................................................................................72caps........................................................................................................72chomp.....................................................................................................72escapePattern........................................................................................72escapeShell............................................................................................73find_as_list.............................................................................................73finds........................................................................................................73gsubs......................................................................................................74ltrim.........................................................................................................74numbertosi..............................................................................................74ordinalSuffix............................................................................................75pad.........................................................................................................75rep..........................................................................................................75rtrim........................................................................................................75trim.........................................................................................................75wrap........................................................................................................76

2.6 std.Table......................................................................................................76clone.......................................................................................................76clone_rename.........................................................................................77empty......................................................................................................77indices....................................................................................................77insert.......................................................................................................78invert.......................................................................................................78merge.....................................................................................................78pack........................................................................................................79remove...................................................................................................79sort.........................................................................................................79

Console Scripting and Macro Guide x

values.....................................................................................................80

3 Data Definition..................................................................................................81

3.1 Data Items....................................................................................................81Data Item................................................................................................81Column...................................................................................................83Connectors.............................................................................................84Connector...............................................................................................84Domains.................................................................................................85Domain...................................................................................................86External Scripts......................................................................................86External Script........................................................................................87Plugins....................................................................................................88Plugin.....................................................................................................89Privileges................................................................................................89Privilege..................................................................................................90Queues...................................................................................................92Queue.....................................................................................................92Schemas................................................................................................93Schema..................................................................................................94Script Environments...............................................................................94Script Environment.................................................................................95SecClasses............................................................................................96SecClass................................................................................................96Sessions.................................................................................................97Session...................................................................................................98Tables.....................................................................................................99Table......................................................................................................100Users......................................................................................................101User........................................................................................................102Views......................................................................................................103View........................................................................................................103

4 Macro Elements................................................................................................105

wx2macro...............................................................................................105actiontext................................................................................................107beforeserverversion................................................................................107chartformat.............................................................................................109

Console Scripting and Macro Guide xi

Preface

dockable.................................................................................................109kogscript.................................................................................................110menu......................................................................................................112name......................................................................................................113objects....................................................................................................114object......................................................................................................116properties...............................................................................................117report......................................................................................................118requiredserverversion.............................................................................120requiredtableaccess...............................................................................121scalemarks.............................................................................................121script.......................................................................................................122sql...........................................................................................................125title..........................................................................................................127update....................................................................................................127<widget> common..................................................................................128<widget type=“button”>..........................................................................132<widget type=“chart”>............................................................................132<widget type=“checkbox”>.....................................................................133<widget type=“combobox”>....................................................................134<widget type=“groupbox”>.....................................................................137<widget type=“grid”>..............................................................................139<widget type=“hbox”>.............................................................................139<widget type=“image”>...........................................................................140<widget type=“label”>.............................................................................140<widget type=“lineedit”>.........................................................................141<widget type=“meter”>...........................................................................143<widget type=“piechart”>........................................................................145<widget type=“radiobutton”>..................................................................146<widget type=“server”>..........................................................................147<widget type=“slider”>............................................................................148<widget type=“stretch”>..........................................................................149<widget type=“table”>.............................................................................150<widget type=“username”>....................................................................152<widget type=“vbox”>.............................................................................153

5 Using KogScript In Macros..............................................................................156

6 Using Old Style SQL Scripts In Macros..........................................................157

Console Scripting and Macro Guide xii

Variables................................................................................................157Assignment.............................................................................................158Connect statement.................................................................................158Describe Command................................................................................158Disconnect Statement............................................................................158Edit Command........................................................................................158Errorcode Command..............................................................................158Errorcodenot Command.........................................................................159Export Command...................................................................................159Goto Command......................................................................................159Help Command......................................................................................159If Statement............................................................................................159Include Command..................................................................................160Results Command..................................................................................160Returncode Command...........................................................................160Set Statement.........................................................................................160Setvar Command...................................................................................161Shell Command......................................................................................161Show Command.....................................................................................162Whenever Statement..............................................................................162Quit Command.......................................................................................162Script variables.......................................................................................163Example 1:.............................................................................................164

7 Putting It All Together......................................................................................166

How Macros Are Used...........................................................................166Macro Directories...................................................................................169Writing effective macros.........................................................................170QuickViz - Creating macros the easy way.............................................170

A............................................................................................................................172

Index......................................................................................................................172

Console Scripting and Macro Guide xiii

1Kog 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 StartedKog scripting is turned off by default in Console. It may be turned on in the Configuration dialog.

Console Scripting and Macro Guide xv

Preface

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 SQLThe 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;

Console Scripting and Macro Guide xvi

Click here to create a Kog script

This Combo box allows the script type to be changed.

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 VariablesWhen 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



Console Scripting and Macro Guide xvii

Preface





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, made up of three parts:

<onerror> [ ; <transaction> ] [ ; <exitcode> ]

Where:

<onerror> = “continue”, “stop”, debug” or “exit”, default=“continue”

<transaction> = “rollback”, “commit” or “none”, default=”none”

<exitcode> =”success”, “failure” or “failure=n”, default=”success”

On Console the <onerror> value is set to the contents of “On server error” combo box.

Set this to change the action when an SQL error is encountered.

e.g error_mode=’exit;rollback;failure=9’

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

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.

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

Console Scripting and Macro Guide xviii

statements are placed in.

sqldebug Integer: Controls output to Console logs pane:

nil => no output0 => no output1 => “OK”, or “error” + error string, rows affected2 => + times3 => + resultset

SQL statements returning a tableNaked SQL Statements may also return a Lua table containing data about the query.

t = select * from sys.ipe_user;

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")

Console Scripting and Macro Guide xix

Preface

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;

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

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

Where: <space> ::= ', ' | '\t' | '\r' | '\n'

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> ) [ <any> ]

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' endt = select * from sys.$name();

Console Scripting and Macro Guide xx

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 stat-l name require library name-v show version information-E ignore environment variables-s server connect to server-s { str } connect using the connection string str-u user connect as user-p password use password for connection-- 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:

Console Scripting and Macro Guide xxi

Preface

>"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) endSYSGRP_DBGGRP_DISKUSAGEGRP_MONITORGRP_LOGODBCMIKEPUBLIC> ^Z

Example 2:

The following example runs the script listusers.kog:

print("Finding Users:")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.kogKog Scripting - version: 7.02.01-s120808-michaela1 (32 bit)Lua 5.2.1 Copyright (C) 1994-2012 Lua.org, PUC-RioFinding Users:SYSGRP_DBGGRP_DISKUSAGEGRP_MONITORGRP_LOGODBCMIKEPUBLIC> os.exit()

Console Scripting and Macro Guide xxii

1.4 Using require in Kog scriptsKog 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.

Package PathThe 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"

Console Scripting and Macro Guide xxiii

Preface

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

endreturn t

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_PATHThe 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.

Console Scripting and Macro Guide xxiv

Standard Library LocationLinux 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.

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 = 2select $x, '$y ', $(z+1) from sys.ipe_user;

Will compile to :

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

Console Scripting and Macro Guide xxv

Preface

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 ExtensionsAlthough Naked SQL is the major extension, Kognitio have added a few other features.

Note: Lua scripts (files with extension .lua) are pure 5.2 Lua - the select keyword has the standard Lua select meaning.

ShellThe shell function has been added to call out into the operating system command shell. Within Console this uses a Qt Process object.

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 scriptsIt is possible to call Kog scripts from Lua scripts and call Lua scripts from Kog scripts.

Console Scripting and Macro Guide xxvi

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

1.7 Compatibility with SQL Script

Wheneverwhenever sqlerror <perform-action> [ <transaction-behaviour> ]

Convert <perform-action> as

‘continue success’ => error_mode='continue;success'

‘continue failure’ => error_mode='continue;failure'

‘continue’ => error_mode='continue;failure'

‘exit success’ => error_mode='exit;success'

‘exit failure’ => error_mode='exit;failure'

‘exit’ => error_mode='exit;success'

‘exit’ <error-code> => error_mode='exit;failure=<error-code>'

Convert <transaction-behaviour> as

‘commit’ => 'commit'

‘rollback’ => 'rollback'

‘none’ => 'none' or ''

So

whever sqlerror continue success rollback => error_mode='continue;success;rollback'

whever sqlerror exit failure commit => error_mode='exit;commit;failure'

Console Scripting and Macro Guide xxvii

Preface

LoopsSQL scripts have no easy way to perform loops. This idiom is sometimes used:

set var x 0; -- initialise loop variableloop:

-- body of loopselect $x+1; -- perform a query to increment loop variable, yuck!set var x $col1; -- set loop variable from results of queryif $x < 10 goto loop; -- use goto to loop back to label loop.

With Kog Script loops are just one of the Lua control structures.

for i = 0,9 do-- body of loopend

Jump to error exitSQL scripts often have an error exit code similar to:

-- Final CommitCOMMIT;GOTO SCRIPT_OK;

SCRIPT_ERR:COMMIT;QUIT 1;

SCRIPT_OK:

On detection of errors elsewhere in the script there is a GOTO SCRIPT_ERR like:

IF $vCount = 0 GOTO NEXT_PART;-- vCount > 0 means error-- do something GOTO SCRIPT_ERR;

NEXT_PART:

With Lua it is better to use a function for the error

function errorExit() commit;

Console Scripting and Macro Guide xxviii

os.exit(1)end

Then call it with

if vCount > 0 then -- do something errorExit() end

Move large chunks of code into functionsSQL scripts often have code like

IF vStatus = 0 GOTO LABEL1; -- lots of SQLGOTO LABEL2LABEL1: -- more SQLLABEL2:

In Kog script this may be converted into an if statement, but also it is often advantageous to put the blocks of SQL into their own functions.

function LotsOfSQL() -- lots of SQLendfunction MoreSQL() -- more SQLend

if vStatus == 0 then LotsOfSQL()else MoreSQL()end

Use functions with parameters for similar SQLOften SQL scripts will have recurring sections of SQL with minor changes, perhaps different values in an INSERT statement.

SET VAR id 5;INSERT INTO sometable (id, ts, name) VALUES ($id, TIMESTAMP, 'dave');INSERT INTO sometable (id, ts, name) VALUES ($id, TIMESTAMP, 'john');

Console Scripting and Macro Guide xxix

Preface

INSERT INTO sometable (id, ts, name) VALUES ($id, TIMESTAMP, 'sue');

These may be converted into functions

function writeName(name) INSERT INTO sometable (id, ts, name) VALUES ($id, TIMESTAMP, $name);endid = 5writeName("'dave'")writeName("'john'")writeName("'sue'")

Console Scripting and Macro Guide xxx

2Kog 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 functionsKog script uses a small library of built-in functions, mainly from the Lua language (version 5.2). As well as these there are a wider set of functions which may be loaded by the require mechanism – these are documented in the next few sections.

_GThis is the Lua global variable that holds the global environment.

_VERSIONThis is a Lua variable that holds the version number. Its value depends whether a Kog script is being run.

Example

Console Scripting and Macro Guide 31

-- Lua sciptprint( _G._VERSION) -- Lua 5.2

-- Kog scriptprint( _G._VERSION) -- Kog Script 1.0 (Lua 5.2

assertassert( v [, message] )

This is a Lua builtin function that issues an error when the value of its v argument is false, that is false or nil, otherwise it returns all its arguments. If the message parameter is present it prints that, otherwise it prints “assertion failed!”.

collectgarbagecollectgarbage( opt, [, arg] )

This is a Lua builtin function which provides a generic interface to the garbage collector. The function it performs depends on the first argument opt:

Opt Function

“stop” Stop the garbage collector

“restart” Restart the garbage collector

“collect” Perform a full garbage collection

“count” Returns the total amount of memory used by this Kog script instance. Note there may be multiple Kog script instances running concurrently in Console.

“step” Perform a garbage collection step. The arg parameter controls the size of the step in an unspecified way.

If this step finished a garbage collection cycle then return true.

“setpause” Sets arg/100 as the new value of the collector pause.


Public Chapter 3 - Console Scripting and Macro Guide

A value of 100 or less means there will be no pause; values over 100 mean that the garbage collector waits for the memory to increase to that % from the previous collection before starting a new collection. So a value of 200 means that the garbage collector waits for the memory to double.

“setstepmul”

Sets arg/100 as the new value of the collector step multiplier.

Values below 100 make the collector too slow to be useful. Larger values make the collector more aggressive at each step.

“isrunning” Returns a Boolean which indicates whether the garbage collector is running.

“incremental”

Default Mode. Run the collector in incremental mode.

“generational”

Use an experimental generational garbage collector.

dofiledofile( [filename] )

This Lua builtin function opens the named file and executes its conents as a chunk of Lua or Kog script code. If the filename parameter ends with .kog then the chunk is run as Kog script, otherwise as Lua. When called with no arguments Lua would normally take input from stdin, however Console has currently no way of feeding input to stdin, so dofile() just hangs.

As chunks behave as the body of Lua functions, values returned by the chunk are returned by dofile. Errors in the chunk are propagated by dofile to its caller.

errorerror( message [, level] )


Chapter 3 - Console Scripting and Macro Guide Public

This is a Lua builtin function which terminates the last protected function called and returns an error message based on the message parameter. error() never returns.

Level Function

0 No additional information is added to the error message parameter.

1 Default. The position where the error function was called is prepended to the error message parameter.

2 The position where the function that called error function is called is prepended to the error message parameter.

3,4,… Higher positions in the call stack (3rd, 4th…) positions.

getmetatablegetmetatable( object )

This is a Lua builtin function to find the metatable of the object parameter.

Object has Function returns

No metatable nil

__metatable field value of the __metatable field.

metatable metatable

Example

t = {'a','b'}print(getmetatable(t),' \n') -- no metatable for tables by defaultm = {1,2,'ab'}setmetatable(t,m) -- add a metatable to tprint(getmetatable(t), ' \n')m.__metatable = {3}print(getmetatable(t),' \n')-- set the __metatable field print(m, m.__metatable, ' \n');-- output is:--nil --table: 15E0B6E0 --table: 169F1128



--table: 15E0B6E0 table: 169F1128

ipairsipairs( t )

This is a Lua builtin function to get an iterator of a table as { index, value } pairs.

If t has a metamethod __ipairs, then it calls __ipairs(t) and returns the first three results from the call.

Otherwise ipairs(t) returns three values: an iterator function, the table t and 0, so that the code:

for i,v in ipairs(t) do body end

Will iterate over the pairs (1, t[1]), (2, t[2]), up to the first integer key absent from the table.

Note that non-integer keys will not be iterated over and t[1] = ‘a’; t[3]=’c’ will only iterate over the first element.

Example

t = {'a','b','c', e='e', 'f'}for i,v in ipairs(t) do print(i,v,' \n') end--Output is (note ‘e’ is missing):--1 a --2 b --3 c --4 f

loadload(ld, [, source [, mode [, env]]])

This is a Lua builtin function to load a chunk of Lua code.

If ld is a string then the chunk is that string. If ld is a function then load calls it relatedly to get the chunk pieces. Each call to ld must return a string that concatenates with previous results to create the chunk. A return or no value, value of nil or “” the empty string signals the end of the chunk.

If there are no syntactiv errors then load returns the compiled chunk as a function; otherwise load returns nil plus the error message.



The source parameter is used for error messages and debugging information as the source of the chunk. When absent the default for ld strings is ld, and for ld functions “=(load)”.

The mode control whether the chunk can be text or precompiled binary. It may be ‘b’ (binary chunks), ‘t’ (text chunks), or to the default ‘bt’ (both binary or text).

If the resulting function has upvalues, the first upvalue is set to the env parameter (or the global environment _G if env is absent). When loading main chunks the first upvalue will be set to the _ENV variable.

Example

i=0;function x() i=i+1; if i>5 then return nil; end; return "print( 'call='..tostring(" .. i .. ")..'\\n')" end;y = load(x)y()--output is:--call=1--call=2--call=3--call=4--call=5

loadfileloadfile( [filename [, mode [, env] ] ] )

This is a Lua builtin function to load a chunk from a file.

It is similar to load() but only loads from files (or stdin).

nextnext( table [, index] ] )

This is a Lua builtin function to traverse all fields of a table.

Its table argument is a table and its index argument is an index into this table. The next function returns the next index of the table and its associated value. When called with nil as its second argument or with a single argument next returns an initial index and its associated value.



When called with the last index or with nil for an empty table, next returns nil.

You may use next to check if a table is empty (see second example)

The order in which the indices are enumerated is not specified, even for numeric indices.

The behavior of next is undefined if during the traversal a value is assigned to a non-existent fields in the table. Pre-existent fields may be modified, including being set to nil.

Example

t = { 1, a='A', 3 }i,v = next(t)print(i, v, ' \n')i,v = next(t,i)print(i, v, ' \n')i,v = next(t,i)print(i, v, ' \n')-- output is:-- 1 1 -- 2 3 -- a A

Example

t = {1}print(next(t) == nil, ' \n')t = {}print(next(t) == nil, ' \n')-- Output is:--false--true

pairspairs(t)

This is a Lua builtin function which allows iteration over a table.

If the table t has a metamethod __pairs, then __pairs is called with t as its argument and returns the first three results from the __pairs call.

Otherwise it returns three values the next function, the table t and nil. Then the code

for i,v in pairs(t) do body end

iterates over all key value pairs (i,v) of table t.



The behavior of this construct is undefined if during the traversal a value is assigned to a non-existent fields in the table. Pre-existent fields may be modified, including being set to nil.

Example

t = { 1, a='A', 3 }for i,v in pairs(t) do print(i,v, ' \n') end-- output is:-- 1 1 -- 2 3 -- a A

pcallpcall( f [, arg1, …] )

This is a Lua builtin function to run a function f with its arguments in protected mode.

Any error generated by f is not propagated; instead pcall catches the error and returns a status code.

The first result from pcall is the boolean status code which is true if the f function does not generate an error. In that case pcall also returns all results from the call. If f generates any error pcall returns false plus the error message.

Example

function x(a) print(a..'\n'); error("this is an error") end;a, b = pcall(x, 5)print(a, b, ' \n')-- Output is:--5--false [string "script"]:1: this is an error

printprint( … )

This is a Lua builtin function to output to stdout.

The print is intended as a quick and simple way of showing values, for instance for debugging. It uses tostring to convert each argument to a string and then prints them to stdout.

For complete control over output use string.format and io.write



rawequalrawequal( v1, v2 )

This is the Lua builtin function for equality.

It checks whether v1 is equal to v2 without invoking any metamethods, returning true if the are equal and false if not.

Tables are equal if they are the same table, not if their contents are the same.

User data is equal if they are the same object.

Example

t1 = {1}t2 = {1}print(rawequal(t1,t1)) -- trueprint(rawequal(t1,t2)) -- false

rawgetrawget( table, index )

This Lua builtin function finds the value at index in the table. No metamethods are invoked.

Example

t1 = {1,2,3, b='B', 4 }print(rawget(t1, 1)) -- 1print(rawget(t1, 4)) -- 4print(rawget(t1, 'b')) -- B

rawlenrawlen( v )

This Lua builtin function finds the length of a table or string

Example

t1 = {1,2,3}t2 = {1, 2, 3, b='b', 4 }print(rawlen(t1)) -- 3



print(rawlen(t2)) -- 4, Note only counts integer indexed print(rawlen("12345")) -- 5

rawsetrawset( table, index, value)

This Lua builtin function to assign a value to table[index]. No metamethods are invoked .

Example

t1 = {1,2,3, b='B', 4 }rawset(t1, 'b', 'C')rawset(t1, 2, -2)rawset(t1, 5, 5)print(rawget(t1, 'b')) -- Cprint(rawget(t1, 2)) -- -2print(rawget(t1, 5)) -- 5

requirerequire( modname )

This is a Lua builtin function to load a module.

The require function starts by looking to see whether there is an entry in the package.loaded table, if there is the module is already loaded and require returns the value of package.loaded[modname].

If not present in package.loaded then require tries to find a loader by following the package.searchers sequence. It is possible to change how require looks for a module by changing this sequence.

Using the default configuration of the package.searchers sequence require first sees if package.preload[modname] has a value. If it has then the (it must be a function) function value is the loader. Otherwise require searches for a Kog script (Lua) loader in using the package.path path. If that also fails package.cpath is used to find a C loader. If that also fails it tries an all-in-one loader.

Once a loader is found require calls it with two arguments:



selectfromselectfrom( index, … )

This is a Kog script builtin function to replace the select() function. The select keyword is used by SQL.

If index is a positive number ( greater than 0) then return all arguments after argument number index. Negative numbers return that number of arguments from the end, so -1 returns the last argument. If index is the string ‘#’ then return the number of extra arguments received.

Example

print( selectfrom(3, 1,2,3,4,5,6,7) ) -- 3 4 5 6 7print( selectfrom(-3, 1,2,3,4,5,6,7) ) -- 5 6 7-- print( selectfrom(0, 1,2,3,4,5,6,7) ) -- gives an errorprint( selectfrom(8, 1,2,3,4,5,6,7) ) -- no outputprint( selectfrom('#', 1,2,3,4,5,6,7) ) -- 7print( selectfrom(3.5, 1,2,3,4,5,6,7) ) -- 4 5 6 7

selectselect( index, … )

This is a Lua builtin function, do not use in Kog scripts use selectfrom instead.

Example

-- In Lua codeprint( select(3, 1,2,3,4,5,6,7) ) -- 3 4 5 6 7print( select(-3, 1,2,3,4,5,6,7) ) -- 5 6 7-- print( selectfrom(0, 1,2,3,4,5,6,7) ) -- gives an errorprint( select(8, 1,2,3,4,5,6,7) ) -- no outputprint( select('#', 1,2,3,4,5,6,7) ) -- 7print( select(3.5, 1,2,3,4,5,6,7) ) -- 4 5 6 7

setmetatablesetmetatable( table, metatable )

This is a Lua builtin function to set the metatable of a table.

If metatable is nil then remove the metatable. If the original has a __metatable field then raise an error.

Example



t = {'a','b'} -- no metatable for tables by defaultm = {1,2,'ab'}setmetatable(t,m) -- add a metatable to tsetmetatable(t, nil) -- remove the metatable from tm.__metatable = {3}setmetatable(t,m) -- add a __metatable to tsetmetatable(t, nil) -- causes error

shellshell( command )

This is a Kog script builtin function to execute a command in an operating system shell. Note that unlike os.execute this runs the command within a QT QProcess.

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 workshell('cmd.exe /C pwd') -- working directory unchanged

Instead use:

shell_dir = [[C:\somepath]] -- [[ ]] string used to avoid \ escapeshell('cmd.exe /C pwd') -- working directory set to c:\somepath

Example:

shell('cmd.exe /C pwd')shell_dir = [[C:\cygwin]]shell('cmd.exe /C pwd')

shell_dir = [[C:\program files]]shell('cmd.exe /C pwd')

sqlsql( s )



This is a Kog script builtin function used to execute SQL. The string s is executed as SQL.

Example

connect to latest user sys using password;sqldebug=2sql("select * from ipe_user" )-- Output is:--Connect statement.----Connecting :--DSN=latest;UID=sys;PWD= password--DSN=latest;UID=sys;PWD= password--OK60 rows (118 ms)--60 rows buffered--Execute time: 0:00.1--First row time: 0:00.1--All rows time: 0:00.1

tonumbertonumber( e, [, base] )

This is a Lua builtin function to convert the e argument to a number.

When called with one argument then if that argument is a string convertible to a number that number is returned. If it is a number then that number is returned. Base 10 is assumed.

When called with a base parameter (a number between 2 and 36), the number is interpreted in that base. In bases above 10 letters are interpreted as digits with ‘a’ or ‘A’ being 10, ‘b’ or ‘B’ being 11, etc.

Failed conversions return nil

Example

print( tonumber(1), ' \n' ) -- 1print( tonumber('2'), ' \n' ) -- 2print( tonumber('2.5'), ' \n' ) -- 2.5print( tonumber('2b'), ' \n' ) -- nilprint( tonumber('2b', 16), ' \n' ) -- 43print( tonumber(111, 2), ' \n' ) -- 7a=111; print( tonumber(a, 2), ' \n' ) -- 7

tostringtostring( v )



This is a Lua builtin function to convert the v argument to a string.

It converts arguments of any type into strings of a reasonable format. If the metastable of v has a __tostring field then this __tostring is called with v as an argument and returns __tostring return value.

For complete control of how numbers are converted use string.format.

typetype( v )

This is a Lua builtin function to find the type of its v argument as a string. Possible values are:

“nil”“number”“string”“boolean”“table”“function”“thread”“userdata”

xpcallxpcall( fn msghandler, [, arg1, …] )

This is a Lua builtin function similar to pcall, except that it also sets a ew message handler msghandler.

bit32.bandLua builtin function

bit32.lshiftLua builtin function



bit32.bxorLua builtin function

bit32.extractLua builtin function

bit32.lrotateLua builtin function

bit32.arshiftLua builtin function

bit32.rshiftLua builtin function

bit32.rrotateLua builtin function

bit32.bnotLua builtin function

bit32.replaceLua builtin function



bit32.borLua builtin function

bit32.btestLua builtin function

debug.getinfoLua builtin function

debug.tracebackLua builtin function

debug.getupvalueLua builtin function

debug.getuservalueLua builtin function

debug.getlocalLua builtin function

debug.debugLua builtin function

debug.upvaluejoinLua builtin function



debug.upvalueidLua builtin function

debug.gethookLua builtin function

debug.getregistryLua builtin function

debug.getmetatableLua builtin function

debug.setmetatableLua builtin function

debug.setlocalLua builtin function

debug.sethookLua builtin function

debug.setupvalueLua builtin function



debug.setuservalueLua builtin function

os.timeLua builtin function

os.exitLua builtin function

os.getenvLua builtin function

os.difftimeLua builtin function

os.setlocaleLua builtin function

os.removeLua builtin function

os.renameLua builtin function

os.tmpnameLua builtin function



os.executeLua builtin function

os.clockLua builtin function

os.dateLua builtin function

math.modfLua builtin function

math.asinLua builtin function

math.tanLua builtin function

math.expLua builtin function

math.atanLua builtin function



math.acosLua builtin function

math.maxLua builtin function

math.minLua builtin function

math.degLua builtin function

math.randomseedLua builtin function

math.powLua builtin function

math.ceilLua builtin function

math.floorLua builtin function

math.absLua builtin function



math.coshLua builtin function

math.sinLua builtin function

math.frexpLua builtin function

math.randomLua builtin function

math.sinhLua builtin function

math.tanhLua builtin function

math.ldexpLua builtin function

math.cosLua builtin function



math.logLua builtin function

math.atan2Lua builtin function

math.fmodLua builtin function

math.sqrtLua builtin function

math.radLua builtin function

io.flushLua builtin function

io.linesLua builtin function

io.popenLua builtin function

io.stderrLua builtin function



io.openLua builtin function

io.inputLua builtin function

io.stdoutLua builtin function

io.stdinLua builtin function

io.outputLua builtin function

io.closeLua builtin function

io.readLua builtin function

io.tmpfileLua builtin function



io.typeLua builtin function

io.write

string.formatLua builtin function

string.byteLua builtin function

string.gmatchLua builtin function

string.charLua builtin function

string.lowerLua builtin function

string.upperLua builtin function

string.lenLua builtin function



string.subLua builtin function

string.dumpLua builtin function

string.reverseLua builtin function

string.repLua builtin function

string.matchLua builtin function

string.gsubLua builtin function

string.findLua builtin function

table.insertLua builtin function



table.__tostringLua builtin function

table.concatLua builtin function

table.packLua builtin function

table.sortLua builtin function

table.removeLua builtin function

table.unpackLua builtin function

coroutine.statusLua builtin function

coroutine.resumeLua builtin function

coroutine.yieldLua builtin function



coroutine.runningLua builtin function

coroutine.wrapLua builtin function

package.configLua builtin string

package.cpathLua builtin string

package.loadedLua builtin table

package.loadlibLua builtin function

package.pathLua builtin string

package.preloadLua builtin table



package.searchersLua builtin table

package.searchpathLua builtin function

2.2 Kog Script std library

string.formatThis 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 errorprint(string.format("%#.2e",12.34567).."\n")require 'std.string'print(string.format("%#.2e").."\n")

2.3 std.baseThis library adds useful functions to Kog scripts.

Example

std = require 'std.base'

std.assertExtend to allow formatted arguments.

std.assert(v, f, ...)v value to assertf format… arguments to formatreturns 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.bindPartially apply a function.

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

Example

std = require 'std.base' function fn(a,b,c) return a*100+b*10+c; endfn1 = 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.collectCollect the results of an iterator.

std.collect(x, i, ...)x table to hold resultsi iterator… parameters to iteratorreturns 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.composeCompose functions (fn applied first).

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

Example

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

std.concatConcatenate lists.

std.concat(...)… listsreturns 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.curryCurry a function.

std.curry(f, n)f function to curryn number of argumentsreturns curried version of f

Example

std = require 'std.base'function fn(a,b,c) return a*100+b*10+c; endfn1 = 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' ) -- 123print(fn2(1)(2,3) .. '\n') -- 123print(fn2a(2,3) .. '\n') -- 123print(fn3(1)(2)(3) .. '\n') -- 123print(fn3a(2)(3) .. '\n') -- 123print(fn3b(3) .. '\n') -- 123

std.diePrint 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.evalEvaluate a string. The opposite of std.pickle().

std.eval(s)s stringreturns value of string

Example

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

std.filterFilter an iterator with a predicate.

std.filter(x, p, i, ...)x table to hold resultsp predicatei iterator… parameters to iteratorreturns 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' endprint(std.tostring(std.filter({}, fn1, std.leaves, t)) .. '\n') -- {1=b}

std.foldFold a binary function into an iterator.

std.fold(f, d, i, ...)f functiond initial valuei iterator… parameters to iteratorreturns 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 endprint(std.tostring(std.fold(fn1, '', std.leaves, t)) .. '\n') -- 'abcd'

std.idIdentity function

std.id(...)… tuplereturns tuple

std.ileavesTree iterator which returns just numbered leaves, in order.

std.ileaves(tr)tr tree to iterate overreturns iterator functionreturns tree

Example



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

std.inodesTree iterator over numbered nodes, in order.

std.inodes (tr)tr tree to iterate overreturns iterator functionreturns 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 .. " " ) endend-- a c d

std.leavesTree iterator which returns all leaves.

std.leaves(tr)tr tree to iterate overreturns iterator functionreturns 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.mapMap a function over an iterator.

std.map(x, f, i, ...)x table to hold resultsf functioni iterator



… parameters to iteratorreturns 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 endprint(std.tostring(std.map({}, fn1, std.leaves, t)) .. '\n') -- {1=aa,2=bb,3=cc,4=dd}

std.memoizeMemoize a function, by wrapping it in a functable.

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

Example

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

std.metamethodReturn given metamethod, if any, or nil.

std.metamethod(x, n)x object to get metamethod ofn name of metamethod to getreturns metamethod function or nil if no metamethod or not a

function

std.nodesTree iterator; return all the nodes in a tree

std.nodes(tr)tr tree to iterate overreturns iterator functionreturns 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 .. " " ) endend-- a b c d

std.opArray containing various operators.

std.op ["[]"] -- indexstd.op ["+"] -- Additionstd.op ["-"] -- Subtractionstd.op ["*"] -- Multiplicationstd.op ["/"] -- Divisionstd.op ["and"] -- Boolean andstd.op ["or"] – Boolean orstd.op ["not"] -- Boolean negationstd.op ["=="] -- Equalitystd.op ["~="] -- Not equals

Example

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

std.packTurn a tuple into a list.

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

Example

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

std.pickleConvert a value to a string.

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

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



Example

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

std.prettytostringPretty-print a table.

std.prettytostring(t, indent, spacing)t table to printindent indent between levels ["\t"]spacing space before every linereturns 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.renderTurn tables into strings with recursion detection.

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



elem element rendererpair pair renderersep separator rendererreturns 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.ripairsTurn tables into strings with recursion detection.

std.ripairs(t)t table to iterate overreturns iterator functionreturns the table, as abovereturns #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.tostringExtend tostring to work better on tables.

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



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.totableTurn an object into a table according to __totable metamethod.

std.totable(x)x object to turn into a tablereturns 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.warnGive 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' )

std.classThis enables classes to be created



Example

require 'std.class'

Animal = class(function(a,name)a.name = nameend)

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 = breedend)

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) thenprint ("lions are big Cats\n")

endprint(fido:speak() .. "\n")print(felix:speak() .. "\n")print(leo:speak() .. "\n")

std.list

2.4 std.strbufThis 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 stringreturn new StrBuf

__concatConcatenation operation

Example

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

__tostringConverts the concatenation buffer into a string

Example

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

2.5 std.stringThis module adds extra string functions to _G.string

..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 ")

capsCapitalise each word in a string

Example

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

chompRemove any final newline from a string.

Example

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

escapePatternEscape a string to be used as a pattern.

Example

require 'std.string's = "%me"print(s:escapePattern() .. "\n" )

escapeShellEscape 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_listDo find, returning captures as a list.

Where:s target stringp patterninit 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))

findsDo find, returning captures as a list.

Where:s target stringp patterninit start position (default: 1)plain inhibit magic characters (default: nil)

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

Example

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



gsubsPerform multiple calls to gsub.

Where:s string to call gsub onsub {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'} ) )

ltrimTrims of leading whitespace from the left of a string

Example

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

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

Example

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

ordinalSuffixReturn the English suffix for an ordinal.

Example

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



padJustify 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")

repRepeat a string

Example

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

rtrimTrims of trailing whitespace from the right of a string

Example

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

trimTrims of leading and trailing whitespace from a string

Example

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

wrapWrap a string into a paragraph

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))

2.6 std.TableTable 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 valuereturn new Table with values set to those of the Table or

table or the value

clonefunction 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 tablereturn table containing a cloned version of t

ExampleTable = 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_renamefunction 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.



ExampleTable = require 'std.table'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")

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

t tablereturn boolean true if table is empty

ExampleTable = 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")

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

t tablereturn table containing indices of table parameter

ExampleTable = 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")

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

t tablev value to insert into table treturn table t



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

invertfunction 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 tablereturn table containing inverted t

ExampleTable = 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 tableu second tablereturn first table

ExampleTable = 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")

packfunction 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 tablesreturn table containing all the table parameters and ‘n’ the

number of tables



ExampleTable = 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")

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

t tablei index to removereturn table t with index i removed.

ExampleTable = 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")

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

t tablec comparator functionreturn sorted table

ExampleTable = 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")

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

t tablereturn table containing values of table parameter

ExampleTable = require 'std.table'



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



3Data 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.



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”



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”



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”

“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.



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



“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

“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.

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


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.

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

“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.

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.

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.

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”

“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

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”

“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

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 = idle1 = running2 = statement rollback3 = transaction rollback4 = queued5 = compiling query

“status” String One of:

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

“clientname” String

“netaddress” String

“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.

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 = default1 = random2 = replicated3 = hashed4 = hashed replicated5 = 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 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

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.


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.



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”

“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 = default1 = random2 = replicated3 = hashed4 = hashed replicated5 = 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.


4Macro Elements

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

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

Attibutes

attibute values notestype “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 shownid … Any stringdebug “true” Debug the macro, output to a

log pane in Console.

Child Elements

<actiontext><dockable><iconfilepath><menu>


Chapter 4 - Public

<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 - MERGEFORMAT

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

Attibutes

attibute values notes

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.




</wx2macro>

beforeserverversionThe <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


Chapter 4 - MERGEFORMAT Public

Example: 07.02.01rel120813

Attibutes

attibute values notesmajor An integer

minor An integer optionalincrement An integer optionalpatch 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> <menu position="4">Reports</menu> <actiontext>Locks Report</actiontext> <beforeserverversion major="7" minor="9" increment="0"/> <objects> </objects> <report> … </report></wx2macro>



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

Attibutes

attibute values notestype string “column”, “line”, “point”, “scatter”,

“xy”, “stack”subtype String Optional, “3d”, “3-d”, “point”angle Integer Optional, angle in degreesdepth Integer(%) Optional, depth of 3d graph as a % of

height.mindepth Integer Optional, minimum depth in pixelsmincolwidth Integer Optional, minimum width of each

column in pixelsmaxcolwidth Integer Optional, maximum width of each

column in pixelsseriesgap Integer Optional, width in pixels between

series data.

Child Elements

none

Parent Elements

<widget type=”chart”>

Notes

Example

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

Attibutes




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>

kogscriptThe <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>).



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

attibute values notesparam 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

destroyeddestroyed(QObject*)doneitemChanged(DataItem*)

Slots

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



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.

menuThe <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

attibute values notesposition An integer Position of the

item within the menu. Currently ignored.

Child Elements

none



Parent Elements

wx2macro

Notes

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

Example





</wx2macro>

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

Attibutes

attibute values notesid A String Unique identifier

within the macro

Child Elements

none

Parent Elements

wx2macro

Notes

The name of the Macro



Example

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




</wx2macro>

objectsThe <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.



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>


</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>



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

Attibutes

attibute values notesoption 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.

<?xml version="1.0" encoding="UTF-8"?><wx2macro type="objectaction"> <name>UpdateStatistics</name> <actiontext>Update statistics</actiontext> <objects> <object option="1+">view</object> </objects>



Notes

Example

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

Attibutes

attibute values notesid String Unique identifier within the macrominwidth Integer Minimum width of the element in

pixelsminheight Integer Minimum height of the element in

pixelswidth Integer Preferred/Initial width of the

element in pixelsheight Integer Preferred/Initial height of the

element in pixelsstyle 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



Slots

closedeleteLaterhideloweronActivated(MacroComboBox*,int)onClicked(MacroButton*)onStateChanged(MacroCheckBox*,int)onToggled(MacroRadioButton*,bool)onValueChanged(MacroSlider*,int)raiserepaintsetDisabled(bool)setEnabled(bool)setFocussetHidden(bool)setPropertyFromValue(const char*,QString)setShown(bool)setStyleSheet(QString)setupViewport(QWidget*)setVisible(bool)setWindowModified(bool)setWindowTitle(QString)showshowFullScreenshowMaximizedshowMinimizedshowNormalupdateupdateMicroFocus

Notes

Example



requiredserverversionThe <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

attibute values notesmajor An integer

minor An integer optionalincrement An integer optionalpatch A String optional

Child Elements

none

Parent Elements

wx2macro

Notes




Example




requiredtableaccessThe <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

attibute values notestable 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



<name>Full Ram Usage Monitor</name><menu position="8">Reports</menu><actiontext>Ram Usage Monitor</actiontext><requiredserverversion major="7" minor="0"/><objects><objects/>


</wx2macro>



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

Attibutes

attibute values notesmajorxticks 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 Double Optional, display a short tick on the

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 Double Optional, display a vertical line

every minorxticks values apart.minorygrid Double Optional, display a faint horizontal

line every majorxticks values apart.

Child Elements

none

Parent Elements


Notes

Example

scriptThe <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>).

Attibutes

attibute values notesid String Unique identifier within the macroparam 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

destroyeddestroyed(QObject*)doneitemChanged(DataItem*)

Slots

deleteLaterexecuteexecute(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.

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”/>


<name>Dashboard</name> <menu position="1">Reports</menu> <actiontext>Dashboard</actiontext> <objects/> <report> <script id="findymax" execute="immediate"> <sql property="ymax">

select min(RAM_SIZE/1024) from SYS.IPE_PROCESS where TYPE='rs'</sql> </script> … </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 type="stretch"/> </widget> <widget type="stretch"/> </widget> </widget>

sqlThe sql element is used to hold SQL.

Attibutes

attibute values notesid String Unique identifier within the macrotarget 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>

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

Attibutes

attibute values notesstyle 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 128), but mainly just a text node will be present in the XML.

Parent Elements


Notes

Example

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



Attibutes

attibute values notestimeseries 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-secrefreshmin Integer, milli-sec

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.

attibute values notesid String Unique identifier within the macrominwidth Integer Minimum width of the element in

pixelsminheight Integer Minimum height of the element in

pixelsWidth Integer Preferred/Initial width of the

element in pixelsheight Integer Preferred/Initial height of the

element in pixelsstyle 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).

<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 the set of objects specified by <objects> (see above). The objectname attribute selects objects with that name from the set of objects. The id attribute gives an identifier to the current object being processed. See the scalemarks examples from page 122.<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><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.

clearclosedeleteLater



hidelowerraiserepaintsetDisabled(bool)setEnabled(bool)setFocussetHidden(bool)setShown(bool)setStyleSheet(QString)setVisible(bool)setWindowModified(bool)setWindowTitle(QString)showshowFullScreenshowMaximizedshowMinimizedshowNormalupdateupdateMicroFocus

<widget type=“button”>The buttot widget is used to create push buttons (QPushButton)

Attibutes

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


Signals

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

clickedclicked(bool)clicked(MacroButton*)pressedreleasedtoggled(bool)

Slots

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



animateClickanimateClick(int)clicksetChecked(bool)toggleupdate(DataItem*)

Example

<widget type=“chart”>The chart widget is used to show 2D and 3D charts.

Attibutes



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 128)



Notes

Example

<widget type=“checkbox”>The checkbox widget is used to create checkboxes (QCheckBox)

Attibutes


attibute values noteschecked 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 128)

Signals

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

clickedclicked(bool)pressedreleasedstateChanged(int)stateChanged(MacroCheckBox*,int)toggled(bool)

Slots

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

animateClickanimateClick(int)clickonStateChanged(int)



setChecked(bool)toggleupdate(DataItem*)

Example

<widget type=“combobox”>The combobox widget is used to make a selection from a list of options (QComboBox)

Attibutes


attibute values notesindex Integer Index of the element which is

initially selected.col Integer Column in dataitem to be used for the

list data.

Child Elements

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

<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 128)

Signals

activated(int)activated(MacroComboBox*,int)activated(QString)



currentIndexChanged(int)currentIndexChanged(QString)editTextChanged(QString)highlighted(int)highlighted(QString)selected(DataItem*)

Slots

clearEditTextonActivated(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.

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 type="hbox" row="0" column="0" style="color:black"> <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> … </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 type="hbox" row="0" column="0" style="color:black"> <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


attibute values notestitle String

Child Elements

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

<connection><kogscript><script><sql><widget>

Parent Elements

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

Signals

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

clickedclicked(bool)toggled(bool)

Slots

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

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="vbox"> <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="vbox"> <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"> <widget type="vbox"> <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.

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 128)

<widget type=“image”>The image widget is used to display bitmap images within a report. It is based on QLabel.



Attibutes


attibute values notesfile 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 128)

Example

<widget type=“label”>The label widget is used to include non-editable text within a report, it is based on QLabel.

Attibutes



Parent and Child Elements

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

Signals

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

linkActivated(QString)linkHovered(QString)



Slots

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

clearsetNum(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



Child Elements

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

<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 128)



Signals

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

cursorPositionChanged(int,int)editingFinishedreturnPressedselectionChangedtextChanged(QStringtextEdited(QString)

Slots

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

clearcopycutpasteselectAllsetText(QString)update(DataItem*)

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

closedeleteLaterhidelowerraiserefreshMeterrepaintsetDisabled(bool)setEnabled(bool)setFocussetHidden(bool)setPropertyFromValue(const char*,QString)setShown(bool)setStyleSheet(QString)setupViewport(QWidget*)setVisible(bool)setWindowModified(bool)setWindowTitle(QString)showshowFullScreenshowMaximizedshowMinimizedshowNormalupdateupdateMeter(SQLProcessorJob*)updateMicroFocus

Notes

Example



<widget type=“piechart”>The < > is used to

Attibutes


Child Elements

<connection><data><kogscript><properties><property><script><title>

Parent Elements

<report><widget>

Signals


Slots

closedeleteLaterhidelowerraiserepaintsetDisabled(bool)setEnabled(bool)setFocussetHidden(bool)setPropertyFromValue(const char*,QString)setShown(bool)setStyleSheet(QString)setupViewport(QWidget*)



setVisible(bool)setWindowModified(bool)setWindowTitle(QString)showshowFullScreenshowMaximizedshowMinimizedshowNormalupdateupdateMicroFocus

Notes

Example

<widget type=“radiobutton”>The < > is used to

Attibutes


attibute values notesselected Boolean Set “true” if the radio button is to

be initially selected.



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





Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“slider”>The < > is used to

Attibutes





Child Elements

Parent Elements

Signals

Slots

Example

<widget type=“stretch”>The < > is used to

Attibutes



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


Slots

closedeleteLaterhidelowerraiserefreshTablerepaintsetDisabled(bool)setEnabled(bool)setFocussetHidden(bool)setPropertyFromValue(const char*,QString)setShown(bool)setStyleSheet(QString)setupViewport(QWidget*)setVisible(bool)setWindowModified(bool)setWindowTitle(QString)



showshowFullScreenshowMaximizedshowMinimizedshowNormalupdateupdateMicroFocusupdateTable(SQLProcessorJob*)

Notes

Example



<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



<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


5Using 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.

Within macros these may be run in the <kogscript> tag.


6Using 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. Within macros 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:


Chapter 4 - Public

set var x 10;if $x <20 goto loop;set var schema sys;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 CommandExecutes Kognitio analytics platform SQL describe syntax.

Disconnect Statement'disconnect'

Edit CommandNot implemented, this is only useful for WxSubmit.

Errorcode CommandNot implemented, only relevant for WxSubmit


Public Chapter 4 -

Errorcodenot CommandNot implemented, only relevant for WxSubmit

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 0loop: …. select $n + 1 set var n $col1if $n < 10 goto loop;

Help CommandNot 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


Chapter 4 - Public

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.scrselect * from sys.ipe_user where name=$name;

Results CommandNot implemented, only relevant for WxSubmit

Returncode CommandNot implemented, only relevant for WxSubmit

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

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


Public Chapter 4 -

Examplesset 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 countset prompt tbl CHAR “Table to update”;-- ask user to supply table nameset mode transaction; -- set the database into transaction modeset mode autocommit; -- set the database into autocommit modeset schema mike; -- set default schema to “mike”set time zone local; -- set the time zone to the local timezoneset time zone ‘-7:00’; -- set the time zone to 7 hours behind UTC

Setvar CommandNot 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 workshell '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.sqlshell 'cmd.exe /C pwd';

set var shell_dir C:\cygwin;set var shell_test 'test1';include included_cmd.sql;

set var shell_dir C:\program files;set var shell_test 'test2';


Chapter 4 - Public

include included_cmd.sql;

include_cmd.sqlselect $shell_test;shell "cmd.exe /C pwd";

Show CommandNot 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

Examplesselect * from sys.ipe_systemif $numrows <> 1 quit;

Script variablesThe 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


Public Chapter 4 -

"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).

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>


Chapter 4 - Public

<script> include "some-script.sql"; </script>

</wx2macro>


7Putting 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:

<?xml version="1.0" encoding="UTF-8"?><wx2macro type="objectaction"> <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.


<name>Concurrency Monitor</name> <menu position="3">Reports</menu> <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 type="stretch"/> </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.

<?xml version="1.0" encoding="UTF-8"?><wx2macro type="objectaction"> <name>Locks Report</name> <menu position="4">Reports</menu> <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"> <widget type="label" style="color:#0E5CAE;font-size:32px;font-weight:bold">Locks Report</widget>

Chapter 0 - Kognitio Public

<widget type="server" style="color:#FF0000;font-size:32px;font-weight:bold"/> <widget type="stretch"/> <widget id="updateButton" type="button" align="left">Update Report<onclick id="but2" property="down" value="true"/></widget> <widget type="stretch"/> </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

Macros may be placed in an object view tab, for example the View object view contains a “RAM Usage” tab which is a macro. The requiredtableaccess elements are used to ensure the user has visibility of the tables needed to run the SQL, if not the macro is not shown in the object view. The objects element is used to select which object view the macro is for.


<name>RAM Usage</name> <actiontext>RAM Usage</actiontext> <requiredtableaccess table="sys.ipe_ram_images"/> <requiredtableaccess table="sys.ipe_view_img"/> <objects> <object option="1" objectname="view"> <test property="tabletype" match="!=" value="I"/> </object> </objects> <report> <widget type="image" row="0" column="0" width="32" file="wxconsole32.png"/> <widget type="label" row="0" column="1">Information on RAM used by this view in bytes:</widget> <widget type="table" row="1" column="0" colspan="2" minwidth="250" minheight="300"> <sql>select case x.distribution when 0 then 'Random' when 2 then 'Replicated' when 3 then 'Hashed' when 4 then 'Hash/Replicated' when 5 then 'Hash/Random' else 'Unknown' end "RAM Distribution", case x.xsum/(1024*1024) when 0 then cast(to_char(x.xsum, '999,999') as varchar(14)) else cast((to_char(x.xsum/(1024*1024), '999,999,999') || 'MB') as varchar(14)) end "Total RAM used", case x.xmin/(1024*1024) when 0 then cast(to_char(x.xmin, '999,999') as varchar(14)) else cast((to_char(x.xmin/(1024*1024), '999,999,999') || 'MB') as varchar(14)) end "Min RAM", case x.xmax/(1024*1024) when 0 then cast(to_char(x.xmax, '999,999') as varchar(14)) else cast((to_char(x.xmax/(1024*1024), '999,999,999') || 'MB') as varchar(14)) end "Max RAM"from

(select vi.distribution, coalesce(sum(ram_used), 0), coalesce(min(ram_used), 0), coalesce(max(ram_used), 0) from sys.ipe_ram_images r, sys.ipe_view_img vi where r.table_id = vi.image_id and vi.table_id =<value objectname="view" property="id"/> group by 1) x(distribution, xsum,xmin,xmax)</sql> </widget> </report>

</wx2macro>

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.

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 macrosThe 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 waySuppose 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;

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.


AIndex

No index entries found.

Console Scripting and Macro Guide - DMG Federal€¦ · Web viewThis manual describes Console...

Documents

Transcript of Console Scripting and Macro Guide - DMG Federal€¦ · Web viewThis manual describes Console...