NAME YottaDB - Perl extension for accessing YottaDB SYNOPSIS use YottaDB ":all"; y_set "^var", 1; # s ^var=1 y_set "var", 2, 3; # s var(2)=3 print y_get "var", 2; # w var(2) y_lock_incr (3.14, "a", 1) or die "timeout"; y_trans (sub { ok (1 == y_get '$TLEVEL'); y_trans (sub { ok (2 == y_get '$TLEVEL'); y_ok; }, "BATCH" ); ok (1 == y_get '$TLEVEL'); y_ok; }, "BATCH" ); DESCRIPTION This module gives you access to the YottaDB database engine using YottaDB's simple API. It requires that you install and setup YottaDB first. After installing the database, setting up the environment is required for "Mumps" and "Perl". Environment-variable "ydb_gbldir" is needed for "Mumps" and "Perl". If incorrectly/not set you can't access globals or use M-Style locking and every attempt to do so will throw an exception. The installation process itself does not need "ydb_gbldir" by default; but "make test TEST_DB=1" needs it. I highly recommend using: $ source "$(pkg-config --variable=prefix yottadb)"/ydb_env_set and $ source "$(pkg-config --variable=prefix yottadb)"/ydb_env_unset for basic setup of environment and databases. Rule of the thumb: If it fails in "Mumps" it will fail in "Perl", too. Always try getting "Mumps" working first. Here we try to access a global without "ydb_gbldir" set in "Mumps" and - just for reference - "Perl": "Mumps": $ cd /tmp $ echo 'I $o(^foo(""))'|"$(pkg-config --variable=prefix yottadb)"/mumps -dir YDB> %YDB-E-ZGBLDIRACC, Cannot access global directory /tmp/$ydb_gbldir.gld. Cannot continue. %SYSTEM-E-ENO2, No such file or directory YDB> "Perl": $ cd /tmp $ perl -MYottaDB=:all -e 'y_next ("^foo","")' YottaDB-Error: -150374122 150374122,(SimpleAPI),%YDB-E-ZGBLDIRACC, Cannot access global directory /tmp/$ydb_gbldir.gld. Cannot continue.,%SYSTEM-E-ENO2, No such file or directory at -e line 1. Installing the YottaDB module from the git repository: $ # sudo apt install make libextutils-pkgconfig-perl libjson-perl $ git clone https://gitlab.com/oesiman/yottadb-perl.git $ cd yottadb-perl $ perl Makefile.PL $ make $ make test $ make test TEST_DB=1 # optional, accesses database $ sudo make install DO NOT USE THIS MODULE ON PRODUCTION SYSTEMS. FUNCTIONS $data = y_data $var [, @subs] The y_data function returns in $data: 0 - no value and no subtree 1 - has a value but no subtree 10 - no value but a subtree 11 - a value and a subtree exists y_killall () The y_killall function kills all local variables. y_kill_excl [$var0 [,$var1 [,...]]] The y_kill_excl function deletes all local variables except the specified one(s). y_kill_excl without arguments is the same as y_killall. y_kill_node $var [, @subs] Deletes a node but not a subtree. y_kill_tree $var [, @subs] Deletes a node and all subtrees. y_set $var, [@subs,] $value Sets the variable to $value $value = y_get $var [, @subs] Sets $value to the value of $var [, @subs]. Returns undef if not defined. $value = y_get_croak $var [, @subs] Sets $value to the value of $var [, @subs]. Croaks if it is not defined. $value = y_next $var [, @subs] Returns the next subscript or undef if there is none. Here a sample "order-loop": my $x = ""; while (defined ($x = y_next "^global", "subscript", $x)) { # ... do something with $x ... } $value = y_previous $var [, @subs] Returns the previous subscript or undef if there is none. (@subs) = y_node_next $var [, @subs] Returns the next node or the empty list if there is none. (@subs) = y_node_previous $var [, @subs] Returns the previous node or the empty list if there is none. $incval = y_incr $var [, @subs], $increment Increments $var [, @subs] by $increment and returns the result in $incval. $string = y_zwr2str $zwr_encoded_string Decodes the $zwr_encoded_string to $string. $zwrstring = y_str2zwr $string Encodes $string in zwr-format. $status = y_lock $timeout [, \@glob1 [, \@glob2 [,...]]] Release all locks held. If globals are specified lock all and return 1 if succeed or 0 if it's not possible to lock all references within $timeout, return 1 if it fails. Example: y_lock 0, ["^temp", 1, "two"], ["^temp", 3] or die "can't lock"; $status = y_lock_incr $timeout, $var [, @subs] Try to gain lock on $var [, @subs] for $timeout seconds if not held. Increment lock counter otherwise. $timeout may be 0.0001 for example. Returns 1 on timeout 0 otherwise. y_lock_decr $var [, @subs] Decrement lock count on $var [, @subs] and release the lock if it goes 0. $status = y_trans (\&code, $tansid [, lvar0 [, lvar1 ...]]) Run a transaction. :) SEE ALSO This module depends on JSON for "ydb_json_import". Install it on Debian: # apt-get install libjson-perl or via CPAN: # cpan JSON AUTHOR Stefan Traby COPYRIGHT AND LICENSE Copyright (C) 2018, 2019, 2020 by Stefan Traby This library is free software; you can redistribute it and/or modify it under terms of the GNU Affero General Public License Version 3.