Accessing GT.M system variables (Export-Tag: ``:sysvar'')
Global Access (Export-Tag: ``:global'')
Transaction support (Export-Tag: ``:trans'')
Accessing M-Code ``:mcode''
EXPORT

NAME

GTM - Perl extension for accessing GT.M

SYNOPSIS

  use GTM ":all";
  use GTM qw(:sysvar :global :trans);

  embed GT.M within Perl

DESCRIPTION

The GTM module embeds GT.M in Perl. This module provides the low-level Interface to the GT.M database environment.

FUNCTIONS

This section gives you an overview over all functions that are provided by this module.

They are ordered by sections, all functions within a section are accessible by an export-tag and share a naming convention (i.e: a prefix).

Accessing GT.M system variables (Export-Tag: ``:sysvar'')

All dollar variables ($test,$tlevel, etc.) are accessible by functions with their name prepended by ``D'' - which means Dollar (a obsolete currency still used in some degenerated countries).

 Examples:  $test == Dtest
            $horolog = Dhorolog
            
If you want to set a sysvar, pass an argument.
In any case they return their (old) value.

Note that the documentation is - like the correspondending XS-part - magically auto-generated :)

$device = Ddevice(): Gets the $device variable
$ecode = Decode([$new]): Gets [ and optionally sets ] the $ecode variable
$estack = Destack(): Gets the $estack variable
$etrap = Detrap([$new]): Gets [ and optionally sets ] the $etrap variable
$horolog = Dhorolog(): Gets the $horolog variable
$io = Dio(): Gets the $io variable
$job = Djob(): Gets the $job variable
$key = Dkey(): Gets the $key variable
$principal = Dprincipal(): Gets the $principal variable
$prompt = Dprompt([$new]): Gets [ and optionally sets ] the $prompt variable
$quit = Dquit(): Gets the $quit variable
$reference = Dreference(): Gets the $reference variable
$stack = Dstack(): Gets the $stack variable
$storage = Dstorage(): Gets the $storage variable
$system = Dsystem([$new]): Gets [ and optionally sets ] the $system variable
$test = Dtest(): Gets the $test variable
$tlevel = Dtlevel(): Gets the $tlevel variable
$trestart = Dtrestart(): Gets the $trestart variable
$x = Dx([$new]): Gets [ and optionally sets ] the $x variable
$y = Dy([$new]): Gets [ and optionally sets ] the $y variable
$za = Dza(): Gets the $za variable
$zb = Dzb(): Gets the $zb variable
$zc = Dzc(): Gets the $zc variable
$zcmdline = Dzcmdline(): Gets the $zcmdline variable
$zcompile = Dzcompile([$new]): Gets [ and optionally sets ] the $zcompile variable
$zcstatus = Dzcstatus(): Gets the $zcstatus variable
$zdate_form = Dzdate_form([$new]): Gets [ and optionally sets ] the $zdate_form variable
$zdir = Dzdir([$new]): Gets [ and optionally sets ] the $zdir variable
$zeditor = Dzeditor(): Gets the $zeditor variable
$zeof = Dzeof(): Gets the $zeof variable
$zerror = Dzerror([$new]): Gets [ and optionally sets ] the $zerror variable
$zgbldir = Dzgbldir([$new]): Gets [ and optionally sets ] the $zgbldir variable
$zininterrupt = Dzininterrupt(): Gets the $zininterrupt variable
$zinterrupt = Dzinterrupt([$new]): Gets [ and optionally sets ] the $zinterrupt variable
$zio = Dzio(): Gets the $zio variable
$zjob = Dzjob(): Gets the $zjob variable
$zlevel = Dzlevel(): Gets the $zlevel variable
$zmaxtptime = Dzmaxtptime([$new]): Gets [ and optionally sets ] the $zmaxtptime variable
$zmode = Dzmode(): Gets the $zmode variable
$zpos = Dzpos(): Gets the $zpos variable
$zproc = Dzproc(): Gets the $zproc variable
$zroutines = Dzroutines([$new]): Gets [ and optionally sets ] the $zroutines variable
$zsource = Dzsource([$new]): Gets [ and optionally sets ] the $zsource variable
$zstatus = Dzstatus([$new]): Gets [ and optionally sets ] the $zstatus variable
$zstep = Dzstep([$new]): Gets [ and optionally sets ] the $zstep variable
$zsystem = Dzsystem(): Gets the $zsystem variable
$ztexit = Dztexit([$new]): Gets [ and optionally sets ] the $ztexit variable
$ztrap = Dztrap([$new]): Gets [ and optionally sets ] the $ztrap variable
$zversion = Dzversion(): Gets the $zversion variable
$zyerror = Dzyerror([$new]): Gets [ and optionally sets ] the $zyerror variable

Global Access (Export-Tag: ``:global'')

Functions that provide global access start with ``g_''.

my $x = g_get(``global'', [ ``idx1'', [ ``idx2'', ..]]): Fetches a global. If the node is undefined, ``undef'' is returned.
g_kill(``global'', [ ``idx1'', [ ``idx2'', ..]]): Kills a global node including all descendant nodes.
g_xkill(``global'', [ ``idx1'', [ ``idx2'', ..]]): Kills a global node excluding all descendant nodes.
my $next = g_order (``global'', [ ``idx1'', [ ``idx2'', ..]]): Returns the next index of same depth.
my $prev = g_rorder(``global'', [ ``idx1'', [ ``idx2'', ..]]): Returns the previous index of same depth.
my $next = g_query(``global'', [ ``idx1'', [ ``idx2'', ..]]): Returns a full reference to the next node in order independant of depth.
g_set(``global'', [ ``idx1'', [ ``idx2'', ..]], $value): Sets a global.
g_data(``global'', [ ``idx1'', [ ``idx2'', ..]]): Checks if a global exists.

Transaction support (Export-Tag: ``:trans'')

In addition to tstart()/tcommit()/trollback()/trestart(), Dtlevel() and Dtrestart() are imported by ``:trans'', too.

They work in the same way as the Mumps versions, except that you can't pass local M-variables to tstart and you specify SERIAL by a boolean flag.

Well, I've not really tested these, but at least:

   perl -MGTM=:trans -e 'tstart; print Dtlevel; tcommit; print Dtlevel'

prints ``10'', as expected. :)

tstart([$serial, $tid]): Start a transaction.
tcommit(): Commits a transaction.
trestart([$level]): Restarts a transaction.
trollback($levels): Rolls a transaction back.

Only unload_gtm() is exported. Call this function before you call something like exec or _exit(). It calls gtm_exit() if and only if Perl started GT.M. unload_gtm() is called automagically on Perl exit if and only if Perl started GT.M.

BUGS

We use the DynaLoader carefully and we try to locate libgtmperl (formally libgtmshr) library by searching in $ENV{gtm_dist} first. It should work even on VMS - please report if not. You may get something like: Subroutine GTM::bootstrap redefined at /usr/local/share/perl/5.8.3/GTM.pm line 40. when using $ZPERLEVAL(...) in GT.M.

This is a simple initialization problem that I'm going to address later :)

AUTHOR

Stefan Traby, <stefan@hello-penguin.com> http://www.hello-penguin.com/gtm-perl

COPYRIGHT AND LICENSE

 Copyright (C) 2004 by Stefan Traby <stefan@hello-penguin.com>
 Copyright (C) 2004 by KW-Computer Ges.m.b.H., Graz, Austria

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (GPL).

In addition to this license

    Sanchez Computer Associates, Inc.
    40 Valley Stream Parkway
    Malvern, PA 19355, USA

has the non-exclusive right to do what ever they want with this code.