NAME YottaDB - Perl extension for accessing YottaDB <https://yottadb.com> 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 <https://yottadb.com/product/get-started> 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 <https://yottadb.com> AUTHOR Stefan Traby <stefan@hello-penguin.com> 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.