aboutsummaryrefslogtreecommitdiff
path: root/OpcodeDocumentation.md
blob: cf0c21864269f013f0d111c359fbe03b31a7c8ce (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

   

Connection

dbconnect

idb dbconnect Stype, Spath
idb dbconnect Stype, Shost, Sdatabase, Suser, Spassword

Connect to a database of type Stype and keep the reference in the handle idb

SQLite connections require only the path to the database file, or :memory: can be used for an in-memory database. MySQL and PostgreSQL connections require hostname/IP, database name, username and password.

Recommended to be run in the global orchestra space.

; SQLite connection
gidb dbconnect "sqlite", "/path/to/database.db"

; MySQL and PostgreSQL connections
gidb dbconnect "mysql", "hostname", "database_name", "username", "password"
gidb dbconnect "postgresql", "hostname", "database_name", "username", "password"

Executing statements

All opcodes require

  • idb , which is the handle created by the dbconnect opcode.
  • Squery, which is the SQL statement to be executed.

i-rate query opcodes

dbexec

dbexec idb, Squery

Execute a SQL statement returning no results.

dbexec gidb, "CREATE TABLE frequencies (frequency FLOAT)"

dbscalar

ires dbscalar idb, Squery [, irow] [, icolumn]
Sres dbscalar idb, Squery [, irow] [, icolumn]

Return a single numeric or string value. Optionally irow and icolumn can be specified which default to 0 and 0 , ie the first value.

inumber dbscalar gidb, "SELECT 1, 2, 3", 0, 2
Svalue dbscalarstr gidb, "SELECT 'this', 'is', 'a', 'test'"

dbarray

ires[][] dbarray idb, Squery
Sres[][] dbarray idb, Squery

Return a two-dimensional numeric or string array.

ires[][] dbarray gidb, "SELECT 1, 2 UNION SELECT 3, 4"
Sres[][] dbarray gidb, "SELECT 'this', 'is' UNION SELECT 'a', 'test'"

k-rate query opcodes

All opcodes require

  • ktrigger , which triggers the execution of the statement when the value is 1 or -1. If -1, any future triggers are ignored. For example ktrigger can be set to -1 initially and the statement will execute once.

All opcodes emit

  • kdone , which is set to 1 for a single k-cycle when the statement execution has completed.

dbexec_k

kdone dbexec_k idb, Squery, ktrigger

Execute a SQL statement returning no results.

kdone dbexec_k gidb, "CREATE TABLE frequencies (frequency FLOAT)", -1

dbscalar_k

kdone, kres dbscalar idb, Squery, ktrigger [, krow] [, kcolumn]
kdone, Sres dbscalar idb, Squery, ktrigger [, krow] [, kcolumn]

Return a single numeric or string value. Optionally krow and kcolumn can be specified which default to 0 and 0 , ie the first value.

kdone, knumber dbscalar_k gidb, "SELECT 1, 2, 3", ktrigger, 0, 2
kdone, Svalue dbscalarstr_k gidb, "SELECT 'this', 'is', 'a', 'test'", ktrigger

dbarray_k

kdone, kres[][] dbarray_k idb, Squery, ktrigger
kdone, Sres[][] dbarray_k idb, Squery, ktrigger

Return a two-dimensional numeric or string array. Note: any operations on the result array may fail before the query has completed. Hence ideally initialise the array first, or make sure kdone == 1 , otherwise the accessing the array will fail.

kdone, kres[][] dbarray gidb, "SELECT 1, 2 UNION SELECT 3, 4", -1
kdone, Sres[][] dbarray_k gidb, "SELECT 'this', 'is' UNION SELECT 'a', 'test'", ktrigger

k-rate query opcodes (blocking)

These opcodes will block the execution of the k-cycle until complete so should not be used for realtime purposes. Ie offline rendering or special operations (eg in example 7) should be fine.

dbexec_kb

dbexec_kb idb, Squery

Execute a SQL statement returning no results.

dbexec_kb gidb, "CREATE TABLE frequencies (frequency FLOAT)"

dbscalar_kb

kres dbscalar_kb idb, Squery [, krow] [, kcolumn]
Sres dbscalarstr_kb idb, Squery [, krow] [, kcolumn]

Return a single numeric or string value. Optionally krow and kcolumn can be specified which default to 0 and 0 , ie the first value.

knumber dbscalar_kb gidb, "SELECT 1, 2, 3", 0, 2
Svalue dbscalar_kb gidb, "SELECT 'this', 'is', 'a', 'test'"

dbarray_kb

kres[][] dbarray_kb idb, Squery
Sres[][] dbarray_kb idb, Squery

Return a two-dimensional numeric or string array.

kres[][] dbarray_kb gidb, "SELECT 1, 2 UNION SELECT 3, 4"
Sres[][] dbarray_kb gidb, "SELECT 'this', 'is' UNION SELECT 'a', 'test'"