NAME

Cac - Integration of Intersystems Cache Database into Perl

SYNOPSIS

      use Cac qw(:lowlevel :highlevel);
      _CacEval '$ZV'; print _CacConvert();

This module and all modules in the Cac::-Domain require a perl that has Cache fully embedded. (such a binary is a dual-binary that is a Perl and a Cache binary at the same time. Usually there is a softlink (ln -s cache cperl) so you don't need to use cache --perl anymore, it works the following way:

use

• cache --perl [perl options ] and you start perl with embedded cache
• cperl [ perl options ] and you get perl with embedded cache
• cache [ cache options ] and you get cache with embedded perl

For backward compatibility with older versions of Cache-Perl

• cache -perl [ perl options ]

is still supported but this feature is deprecated. Use "--perl" instead of "-perl".

Note: Most of this stuff is the low-level Interface, you normally don't need it, except maybe CacEval and CacExecute.

• use Cac::ObjectScript - for embedded ObjectScript support
• use Cac::Global - for high-performance global access (bulk support)
• use Cac::Routine - for calling routines and functions
• use Cac::Bind - for bidirectional binding of COS Variables to Perl variables
• use Cac::Util - for utility functions and helpers

DESCRIPTION

• This module provides full access to most Cache call-in functions.
• You should not use the call-in function without exactly knowing what you are doing
• These function are not exported by default and prepended by a underscore (that means internal).
• All functions are perlified - you pass a single string if Cache expects a counted string
• You don't need to check for errors. Most functions raise exceptions on error: use eval { }; to catch them
• Only "A" functions are supported, no "W". "W" is NOT Unicode anyway, Intersystems simply lies to you.

User Interface for Cache Functions

CacEval $expr

         Evaluates a ObjectScript expression and returns its result
         Exception: yes
         Note: This function is slow because it has to preserve terminal settings

CacExecute $stmt

         Executes a ObjectScript command and returns nothing.
         Exception: yes
         Note: This function is slow because it has to preserve terminal settings

Cache Call-In High-Level Functions

The high-level functions can be imported by: use Cache ':highlevel';

CacAbort [ CACHECTRLC | CACHE_RESJOB ]

         See Cache specification.
         Exception: Yes
         Note: Don't use it.

$ctx = _CacContext()

         See Cache specification.
         Exception: No

$value = CacConvert()

         See Cache specification.
         Exception: Yes
         Note: This function calls CacConvert(CACHEASTRING, ...)

$value = _CacConvert2()

         This routine uses CacType() to ask for the type of TOS and
         tries to get the value the fastest way possible.

         Exception: Yes

_CacCtrl($bitmap)

         See Cache specification
         Exception: Yes

$converted = _CacCvtIn($string, $table)

         See Cache specification
         Exception: Yes

$converted = _CacCvtOut($string, $table)

         See Cache specification
         Exception: Yes

CacEnd()

         See Cache specification
         Exception: Yes
         Note: You should NEVER EVER call this! even POSIX::exit(1); is prefered.

$error = _CacError()

         See Cache specification
         Exception: Yes (if a double fault happens)
         Note: No need to call this because every error is reported by croak.

$errorstring = _CacErrxlate($errornum)

         See Cache specification
         Exception: No (if the call to CacheErrxlate fails, undef is returned)

_CacEval $string

         See Cache specification
         Exception: Yes

_CacExecute $string

         See Cache specification
         Exception: Yes

$prompt = _CacPrompt()

         See Cache specification
         Exception: Yes
         Note: Experts call this functions only by accident. :)

_CacSignal $number

         See Cache specification
         Exception: Yes
         Note: Think and you will find out that you don't want it in most cases.

_CacStart($flags, $timeout, $princin, $princout)

         See Cache specification
         Exception: Yes
         Note: Don't call it. It's already done. Say simply thanks :)

$type = _CacType()

         See Cache specification
         Exception: No (ahm, check the return value for errors)

Cache Low-Level Call-In Functions

     The low-level functions can be imported by:
     use Cac ':lowlevel';

Use it only IF:

• you know how to use gdb
• you want to corrupt the database
• you never use a condom anyway :)
• you know what gmngen/checksum/mdate is made for :)

_CacCloseOref $oref

         See Cache specification
         Exception: Yes

_CacDoFun $rflags, $numargs

         See Cache specification
         Exception: Yes, please.

_CacDoRtn $rflags, $numargs

         See Cache specification
         Exception: Oui

_CacExtFun $rflags, $numargs

         See Cache specification
         Exception: Da

_CacGetProperty()

         See Cache specification
         Exception: Yes, sir.

CacGlobalGet $numsubscipt, $dieor_empty

         See Cache specification
         Exception: yup

_CacGlobalSet $numsubscript

         See Cache specification
         Exception: yup, on weekends only.

_CacIncrementCountOref $oref

         See Cache specification
         Exception: ja

_CacInvokeClassMethod $numarg

         See Cache specification
         Exception: si

_CacPop $arg

         Not implemented
         Exception: yes

$val = _CacPopDbl()

         See Cache specification
         Exception: yes

$val = _CacPopInt()

         See Cache specification
         Exception: yes

$string = _CacPopList()

         Currently not implemented
         Exception: yes

$oref = _CacPopOref()

         See Cache specification
         Exception: yes

$str = _CacPopStr()

         See Cache specification
         Exception: yes

$ptr = _CacPopPtr()

         Not Implemented
         Exception: yes

_CacPushClassMethod $classname, $methodname, [$flag]/

         See Cache specification
         Exception: /bin/true
         Note: flag defaults to 0

_CacPushDbl $double

         See Cache specification
         Exception: yes

$rflags = _CacPushFunc $tag, $routine;

         See Cache specification
         Exception: yes

$rflags = _CacPushFuncX $tag, $offset, $env, $routine;

         See Cache specification
         Exception: yes

_CacPushGlobal $global

         See Cache specification
         Exception: yes

_CacPushGlobalX $global, $env

         See Cache specification
         Exception: yes

_CacPushInt $i

         See Cache specification
         Exception: yes

_CacPushList $string

         See Cache specification
         Exception: yes

_CacPushMethod $oref, $methodname, [$flag]

         See Cache specification
         Exception: yes
         Note: $flag defaults to 0

_CacPushOref $oref

         See Cache specification
         Exception: yes

_CacPushProperty $oref, $property

         See Cache specification
         Exception: yes

_CacPushPtr $value

         See Cache specification
         Exception: yes

$rflags = _CacPushRtn $tag, $routine

         See Cache specification
         Exception: yes

$rflags = _CacPushRtnX $tag, $offset, $env, $routine

         See Cache specification
         Exception: yes

_CacPushStr $string

         See Cache specification
         Exception: yes

_CacSetProperty()

         See Cache specification
         Exception: yes

_CacUnPop()

         See Cache specification
         Exception: yes

SEE ALSO

Cac::ObjectScript, Cac::Global, Cac::Routine, Cac::Util, Cac::Bind.

AUTHOR

     Stefan Traby <stefan@hello-penguin.com>
     http://hello-penguin.com

COPYRIGHT

     Copyright 2001,2003,2004 by KW-Computer Ges.m.b.H Graz, Austria
     Copyright 2001,2002,2003,2004 by Stefan Traby <stefan@hello-penguin.com>

LICENSE

     This module is licenced under LGPL
     (GNU LESSER GENERAL PUBLIC LICENSE)
     see the LICENSE-file in the toplevel directory of this distribution.