UnidSql Functions v. 1.x

Here is  a revised output of the function sql_help() which describes available unidSql functions. These tips match the following format:

 function_name(arg_types)->(output type):
 -- functionality (#WARNINGS#) --
 debug: [ID] to pass to versions compiled with -D__UNIDEBUG__
 used by: [other functions] using the described function
 returns: more details about results and stored results
 ex: an example use (unid-adm)
 Other comments.
Functions marked as #INTERNAL# should not be used at all. Functions marked #ADVANCED# or #RECURSIVE# should be used with caution. Functions marked #STORES# do store their last list of results for availability to last_out().

To use a debug-version of unid-adm and see more output, do something like:

$ ./unid-adm-debug base.unid admin -d 253 

To display a help text from unid-adm:

? select sql_help('some_function') 

To display all help texts:

? select sql_help('all') 

List of help texts

acti_record(int linkid|string alias)->(string info)
 -- utility --
  debug: 253
  used by: SEND_RECORD(), SEND_TABLE()
  returns: string info
  ex: 
  ? select acti_record('unid_home')

bait_chain_if(int nodid, int symid)->(sting table)
 -- retrieval task (#INTERNAL,RECURSIVE#) --
  debug: 243
  used by: CHAIN_NODE_IF()  returns: string node-table

bait_full_record(int recid|string alias, int symid)->(string record)
 -- retrieval task (#INTERNAL,RECURSIVE#) --
  debug: 240
  used by: SEND_FULL_NODE()
  returns: string record-data

bait_table(int recid|string alias, int symid)->(string table)
 -- retrieval task (#INTERNAL,RECURSIVE#) --
  debug: 249
  used by: SEND_NODE()
  returns: string record-table

blank_link(linkid)->(int 1)
 -- modification task --
  debug: 230
  returns: int 1 or 0
  Changes the symbolic value of a record link to -1,
  preserving the record structure.

chain_node_if(int nodid, int refid, int symid)->(string nodelist)
 -- retrieval task (#INTERNAL,RECURSIVE#) --
  debug: 244
  used by: BAIT_CHAIN_IF(),CHAIN_RECORD_IF()
  returns: string node-list
  Chains a node according to some condition.

chain_record_if(int recid|string alias, int symid)->(string negints)
 -- retrieval task (#INTERNAL,RECURSIVE#) --
  debug: 245
  used by: LOOK_UP()
  returns: string node-list
  Sends the list of records nested in recid that contain symbol symid.

change_data(int datid|string data, string new, int mode)->(int 1)
 -- administration task (#REPAIR#) -- 
  debug: 231
  returns: int 1 or 0
  Changes the value of a data field. For repair purpose only.

change_node(int nodid, int id| string 'text', int pos)->(negint pos)
 -- modification task (#INTERNAL#) --
  debug: 214
  used by: EXAMPLIFY(),GET_FORMAT(),GET_SYMBOL(),INK_RECORD(),
           INSERT_SYMBOL(),MAKE_RECORD(),TEMPLATIZE()
  returns: int 0 - position
  stores: int nodid: main_specs->res->num1
          string data: main_specs->res->txt1
  Changes one of the (a|b|n) values of a node.

clone_title(string title)->(string formated)
 -- insertion task (advanced) 
  debug: 241
  returns: string subdb-title (formatted)

examplify(int templid|string title, string title, string params, string alias)->(int recid)
 -- insertion task --
  debug: 257
  returns: int record id
  ex. 1: 
  ? select examplify(
      -1461,
      'another subrecord',
      'prop1:unid-protyp-sep:type1:unid-params-sep:prop2:unid-protyp-sep:type2',
      'another_alias'
    )
  ex. 2: 
  ? select examplify(
      'Subrecord title',
      'another subrecord',
      'prop1:unid-protyp-sep:type1:unid-params-sep:prop2:unid-protyp-sep:type2',
      'another_alias'
    )
Creates a new record under an existing subdb with params and alias. When the first parameter is a string, it's a subdb title - not an alias. examplify() should accept the same syntax as make_full_record() to pass record ids in params (UNID_CODE_SUBDB token). Note the use of separators (see '_tokens_').

find_end(int linkid)->(int endid)
  -- navigation task --
  debug: 216
  used by: INK_RECORD(),INSERT_SYMBOL(),REMOVE_RECORD()
  returns: last node in chain of linkid
  ex: 
  ? select find_end(-197)

find_record(int linkid)->(int recid)
  -- navigation task --
  debug: 219
  used by: REPLACE_SYMBOL(),RETITLE(),SEARCH_RECORD(),SEND_FULL_RECORD(),
           SHOW_RECORD(),SWAP_LINKS(),SWAP_SYMBOLS()
  returns: first node in chain of linkid
  ex: 
  ? select find_record(-197)

get_chars(defined token)->(string chars)
  -- utility --
  debug: 260
  returns: string associated to token
  ex: 
  ? select get_chars('UNID_CODE_STX')
  See '_tokens_' for a list of tokens (defined in Unid.h).

get_format(int symid)->(int formid)
  -- insertion task  --
  debug: 215
  used by: MAKE_RECORD(),TEMPLATIZE()
  returns: new or existing format id (negative)
  ex: 
  ? select get_format(46)
  Creates or retrieves a format id from:
   - an existing data id (positive), or 
   - an existing record id (negative)

get_id(string data|int id)->(int alid|recid|formid)
  -- navigation task  --
  debug: 229
  returns: int id
  ex. 1: 
  ? select get_id('my_string')
  Retrieves the id corresponding to an alias or record title
  (can be positive in case of an aliased symbol).
  ex. 2: 
  ? select get_id(-197)
  Retrieves the n-value of a provided record id (advanced).

get_myvar(varname)->(string varname)->(string value)
  -- utility  (#INTERNAL,ADVANCED#)--
  debug: 255
  returns: string value
  used by: VIEW_SYMOFFRECS (experimental)
  ex: 
  ? select get_myvar('num')
  Retrieves the value of one of the available main_specs.res variables:
  - num (fun_store.main_specs->res->num1) 
  - sub (fun_store.main_specs->subdb_flag) 
  - sym (fun_store.main_specs->res->num2) 
  - txt (fun_store.main_specs->res->txt1) 
  - var (fun_store.main_specs->res->txt2)

get_string(int id| string text)->(int stringid)
  -- insertion and retrieval task  --
  debug: 211
  used by: CHANGE_NODE(),EXAMPLIFY(),GET_SYMBOL(),MAKE_RECORD(),
           RETITLE(),TEMPLATIZE()
  returns: int id
  ex. 1: 
  ? select get_string('my text')
  Retrieves (or creates) the id of provided data.
  ex. 2: 
  ? select get_string(64)
  Retrieves the data value of provided id.

get_subject(string title, string format, string params, string alias, string opt)->(int recid)
  -- insertion and retrieval task (#ADVANCED#) --
  debug: 262
  returns: int id
  ex. 1: 
  ? select get_subject(
     'Unid table template',
     'Unid table template',
     '',
     '', 
     'normal'
    )
  Retrieves the id of provided subdb title.
  ex. 2: 
  ? select get_subject(
     'my title',
     'my format',
     'prop1:unid-protyp-sep:type1',
     'my_alias', 
     'normal'
    )
  Creates a subrecord of the provided format,
  or creates the subdb with provided data (except format).
  ex. 3:
  ? select get_subject(
     'my title',
     'my format',
     'prop1:unid-protyp-sep:type1',
     'my_alias', 
     'force'
    )
  Creates a subrecord of the provided format,
  but (dangerous) creates it even without subdb.

get_symbol(string prop|int pid, string type|int tid, int unicity)->(int symid)
  -- insertion and retrieval task  --
  debug: 213
  used by: EXAMPLIFY(),MAKE_FULL_RECORD()
  returns: int id
  ex. 1: 
  ? select get_symbol(
     '19°',
     'temperature',
      0
    )
  Retrieves or creates the symbol provided by existing data or id.
  ex. 2: 
  ? select get_symbol(
     -197,
     'main page',
      1
    )
  Retrieves or creates the symbol provided by existing data or id
  (positive data id or negative record id).

ink_record(int recid|string alias, int symid)->(int nodid)
  -- insertion task  --
  debug: 217
  used by: EXAMPLIFY(),MAKE_FULL_RECORD(),MAKE_RECORD(),TEMPLATIZE()
  returns: int id
  ex: 
  ? select ink_record(
     'unid_home',
     get_symbol('p1','t1',0),
      0
    )
  Appends a symbol to some record.

insert_symbol(int linkid, int nodid)->(int linkid)
 -- insertion task  --
  debug: 227
  returns: int node id
  ex: 
  ? select insert_symbol(-197,-224)

last_out(string sql, int mode)->(string rslt)
 -- retrieval task (#STORES#) --
  debug: 273
  returns: string results
  stores: list of ids (only first item in a row)
  Some functions store results in main_specs.datares (a string array)
  then last_out() has a similar effect as working on a temporary table.
  ex: 
  ? select last_out('select i,get_string(a) from node where i=:unid-item: and a>0',1)
  Returns id and title of a each record stored in a previous list.
  The function stores only the first item of each selection (here i).
  Note the use of :unid-item: (UNID_CODE_ITEM, see _tokens_).
  As the first item selected (i) is the same as in the last command, this
  query can be repeated, but not if we had the a-value first.
   mode=0: only prints contents of main_specs.datares (regardless of query)
   mode=1: executes query and stores new results.

list_form(int linkid, int mode)->(int numrows)
 -- retrieval task (#STORES#) --
  debug: 248
  used by: REMOVE_RECORD()
  returns: int numrows
  stores: list of records sharing format linkid
  ex: 
  ? select list_form(-198,0)
  Returns list and number of occurences of a format
   mode=0: to be found from the provided record link (not necessarily a record id)
   mode=1: format specified directly as symbol id

list_occs(string data1, string data2, string mode)->(int foundoccs)
 -- retrieval task (#STORES#) --
  debug: 236
  returns: int found occurences
  stores : list of nodes
  ex: 
  ? select list_occs('Kirk','captain','protyp')
  Returns list and number of occurences of a type-property pair
  under the following modes: 
  a) data1 only (leave the second parameter string empty)
   mode= one of (ali,rec,sub,tit,pro,typ,pid,tid)
  b) data1+data2:
   mode=one of (protyp,pidtyp,protid,pidtid)
  An optional '-' prefix on mode (e.g. '-protid') will count occurences only,
  a '-' suffix (e.g. 'protid-') will look for unique properties
  and a '+' suffix (e.g. 'protid+') targets multiplicity (unicity = 0).
  main_specs.datares stores results (see last_out()).

locate_node(string sql)->(int found occurences)
 -- retrieval task (#STORES#) --
  debug: 232
  returns: int found occurences
  stores : int node ids
  ex: 
  ? select locate_node('a=-223 or a=24')
  Locates nodes according to some sql WHERE clause.

look_up(int|string pro, int|string typ, int recid ,int mode)->(int foundoccs)
 -- retrieval task (#STORES#) --
  debug: 242
  returns: int found occurences
  stores : int node ids
  ex: 
  ? select look_up('%','description',-197,4)
  Sends the list of records nested in recid that match typ and pro. 
   mode=1: propid+typid
   mode=2: propid+type
   mode=3: prop-typid
   mode=4: prop-type

make_full_record(string title, string format, string params ,string alias)->(int recid)
 -- insertion task -- 
  debug: 259
  used by: GET_SUBJECT()
  returns: int record id
  ex: 
  ? select make_full_record('mytitle','myformat','p1:unid-protyp-sep:t1','myalias')
  Creates a new record with params and alias.

make_node(int nodid, int pos)->(int nodid)
 -- insertion task (#INTERNAL#) --
  debug: 212
  used by: EXAMPLIFY(),GET_FORMAT(),GET_SYMBOL(),INK_RECORD(),
           INSERT_SYMBOL(),MAKE_RECORD(),TEMPLATIZE()
  returns: int node id
  Creates a node with value in one of three possible containers (a|b|n).

make_record(string title,string format)->(int recid)
 -- insertion task --
  debug: 218
  used by: MAKE_FULL_RECORD()
  returns: int record id
  ex: 
  ? select make_record('mytitle','myformat')
  Creates a bare record with title and format.

make_string(string text)->(int stringid)
 -- insertion task (#INTERNAL#) --
  debug: 210
  used by: GET_STRING()
  returns: int data id
  Creates a data entry.

node_type(int nodid)->(int nodtyp)
 -- utility --
  debug: 238
  used by: SWAP_LINKS()
  returns: int node type (see Unid.h)
  ex: 
  ? select i,get_string(a) from node where node_type(i)=2
  List record ids and titles.
  -- valid types:
     TYP_NO_ID     = -1
     TYP_OTHER_ID  =  0
     TYP_SYMBOL_ID =  1
     TYP_RECORD_ID =  2
     TYP_FORMAT_ID =  3
     TYP_LINK_ID   =  4
     TYP_END_ID    =  5

raise_id(int any)->(int id)
 -- insertion task (#INTERNAL#) --
  debug: 209
  returns: int id  Checks bin for a recycling value then creates and/or returns it.
  A positive (data) or negative (node) parameter makes the id such too.

recycle(int)->(int id)
 -- insertion task (#INTERNAL#) --
  debug: 208
  returns: int id
  Backbone of the raise_id() function: retrieves an id from the stock.

recycle_flyers(int 1)->(int rslt)
 -- administration task --
  debug: 266
  returns: int number of recycled
  ex: 
  ? select recycle_flyers(1)
  Removes all unused symbols.

recycle_junks(int 1)->(int rslt)
 -- administration task --
  debug: 267
  returns: int number of recycled
  ex: 
  ? select recycle_junks(1)
  Removes all unused data.

reformat(int recid, int formatid)->(int 1)
 -- modification task --
  debug: 222
  used by: SUBSUME()
  returns: int 1 on success
  ex: 
  ? select reformat(-197,-234)
  Changes the value of a format link 
  (i.e. the format symbol of a given record).

regex(string data, string regex, int mode)->(int|string result)
 -- utility --
  debug: 272
  returns: int 1 if matches,0 otherwise or string match
  ex. 1: 
  ? select * from records where regex(rec,'#Unid table.*',0)=1
  Returns records where title match.
   mode=0: returns 1 (true) or 0 (false) according to the match
   mode=1: returns the last captured subregex, this implies the regex
           has at least one set of parentheses as in:
  ex. 2: 
  ? select regex('this is my data','(this).+',1)

remove_alias(int recid| string alias)->(int remrows)
 -- administration task --
  debug: 233
  returns: number of removed aliases
  ex. 1: 
  ? select remove_alias('myalias')
  Removes alias 'myalias'.
  ex. 2: 
  ? select remove_alias(-197)
  Removes each alias of record -197.
  ex. 3: 
  ? select remove_alias(223)
  Removes each alias of symbol -223 ;  (note the absolute value used for symbol aliases).

remove_flyer(int flyerid)->(int 1)
 -- administration task --
  debug: 264
  returns: 1 in case of success
  ex: 
  ? select remove_flyer(-223)

remove_junk(int junkid)->(int 1)
 -- administration task --
  debug: 265
  returns: 1 in case of success
  ex: 
  ? select remove_junk(124)
  Removes some unused data.

remove_link(int linkid)->(int 1)
 -- modification task --
  debug: 234
  returns: 1 in case of success
  ex: 
  ? select remove_link(-212)
  Removes one link from a record and recycles.

remove_record(int recid)->(int remlinks)
 -- modification task --
  debug: 235
  returns: number of links removed
  ex: 
  ? select remove_record(-197)
  Removes a record, recycles and cleans db.

replace_symbol(int linkid, int symid, int newid, int mode)->(int count)
 -- modification task --
  debug: 268
  returns: number of links modified
  ex: 
  ? select remove_symbol(-223)
  Replaces a symbol id by a new one, either: 
   mode=0: in a specified link position
   mode=1: in a record
   mode=10: idem but recursively
   mode=100: in a subdb
   mode=1000: idem but recursively
   mode=-1 in the whole base.
  Note: 0 and -1 are the only implemented modes (v0.4.3).

retitle(int recid, string newtitle)->(int SQLITE_OK)
 -- modification task --
  debug: 271
  returns: int SQLITE_OK
  ex: 
  ? select retitle(-197,'my new title')

search_record(int nodid, string search, int mode)->(int nodid)
 -- modification task (#STORES#) --
  debug: 237
  used by: INK_RECORD(debug)
  returns: int node id, stores node list (see last_out())
  ex: 
  ? select search_record(-197,'script',2)
  Finds the various nodes matching a search within some record
  and returns the last node id while storing the list.
  The search string can represent several types of content:
   mode= 0: search = id, returns last node where title, 
            format or symbol id = search;
   mode= 1: search = type (full string), returns last matching property
            where title, format or type = search;
   mode=-1: idem but with unicity = 1;
   mode= 2: as mode = 1 but matches a partial type string;
   mode=-2: idem but with unicity = 1;

send_node(int nodid, int refid)->(string record)
 -- retrieval task (#INTERNAL#) --
  used by: BAIT_FULL_RECORD(),SEND_FULL_RECORD()
  debug: 220
  returns: string|stream, recursive content of a node

send_full_record(int recid|string alias, int mode)->(string record)
 -- retrieval task --
  debug: 221
  returns: string|stream, recursive content of a record
  ex: 
  ? select send_full_record('unid_home',1)
  Sends the detailed and recursive content of a record as string.
   mode= int (still unused)

send_node(int nodid, int refid)->(string table)
 -- retrieval task (#INTERNAL#) --
  used by: BAIT_TABLE(),SEND_NODE(),SEND_TABLE()
  debug: 250
  returns: string|stream, recursive content of a node

send_record(int recid|string alias, int mode)->(string record)
 -- retrieval task --
  debug: 252
  returns: string|stream strict content of a record with symbol data
  ex: 
  ? select send_record('unid_home',1)
  (advanced use involves modes like TVIEW_16FLDS et al. see Unid.h)

send_table(int recid, int mode)->(string table)
 -- retrieval task --
  debug: 251
  returns: string|stream record table without symbol data
  ex: 
  ? select send_table('unid_home',1)
  (advanced use involves modes like TVIEW_16FLDS et al. see Unid.h)

set_alias(int id, string alias)->(int alid)
 -- insertion task --
  debug: 228
  used by: EXAMPLIFY(),MAKE_FULL_RECORD()
  returns: int alias id
  ex. 1: 
  ? select set_alias(-197,'unid_home')
  Sets the alias of a record.
  ex. 2: 
  ? select set_alias(-222,'my_symbol')
  Sets the alias of a symbol (stored as abs(symid)).
  Both aliases can then be recovered with get_id(id).

set_myvar(string varname, string value)->(int 1)
 -- utility (#ADVANCED#) --
  debug: 256
  used by: GET_SUBJECT(force)
  returns: int 1 in case of success
  Sets one of the available main_specs.res variables.
  Valid var names: 
   num : main_specs->res->num1 (int)
   sym : main_specs->res->num2 (int)
   txt : main_specs->res->txt1 (string)
   var : main_specs->res->txt2 (string)
   sub : main_specs->res->subdb_flag (bool)
  Handle with care!

show_node(int nodid)->(string row)
 -- retrieval task --
  debug: 224
  returns: string
  Displays the detailed content of a node.

show_record(int recid| string alias)->(string rows)
 -- retrieval task (#STORES#) --
  debug: 223
  returns: string
  Displays the strict content of a record.

show_symbol(int symid)->(string rows)
 -- retrieval task (#STORES#) --
  debug: 225
  returns: string
  Displays the detailed content of a symbol.

sign(int)->(int)
 -- retrieval task --
  debug: 207
  returns: int 1|0|-1
  Gets the relative value of an int.

sql_help('function_name'|'all')->(string help)
 -- retrieval task --
  debug: 226
  returns: string
  Displays a help line for one or all described UnidSQL items.

subsume(int recid| string alias, int subdbid)->(int formid)
 -- insertion task --
  debug: 254
  returns: int format id (negative)
  ex. 1: 
  ? select subsume(-197,-187)
  Registers an existing record under an existing template.
  ex. 2: 
  ? select subsume(-197,'note template')
  Note that the function takes care of prepending the subdb token
  UNID_CODE_SUBDB (see get_chars()), to get the real subdb name.

swap_links(int nodid, int targid)->(int 1)
 -- modification task --
  debug: 239
  returns: int 1 on success
  ex: 
  ? select swap_links(-190,-191)
  Swaps the positions of two links in a same record.

swap_symbols(int targ1, int pos1, int targ2, int pos2)->(int 1)
 -- modification task (#ADVANCED#) --
  debug: 261
  returns: int 1 on success
  ex: 
  ? select swap_symbols(-187,1,-187,2)
  Swaps the positions of two symbols (similar to swap_links()).
  Note that position 1 is the first symbol after format.
  Dangerous: the symbols of two different records can be swapped.

templatize(int recid, string sdbname)->(int subdbid)
 -- insertion task --
  debug: 246
  returns: int subd id
  ex: 
  ? select templatize(-1971,'my new subdb')
  Creates a named subdb from a record id and a format string.
  The function takes care of prepending UNID_CODE_SUBDB token.

uid()->(string uid)
 -- utility --
  debug: 206
  returns: string user name
  ex: 
  ? select uid()

64 sql functions.

Advertisements