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.