Cac - Integration of Intersystems Cache Database into Perl

Cac documentation Contained in the Cac distribution.

Index

Code Index:

NAME

Top

Cac - Integration of Intersystems Cache Database into Perl

SYNOPSIS

Top

  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:

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

For backward compatibility with older versions of Cache-Perl

  o 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.



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

DESCRIPTION

Top

 * 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

Top

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

Top

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

_CacAbort [ CACHE_CTRLC | 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(CACHE_ASTRING, ...)
$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

Top

 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, $die_or_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

Top

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

AUTHOR

Top

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

COPYRIGHT

Top

 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

Top

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

use 5.007;
use strict;
use warnings;

our $xs_loaded = 0;

BEGIN {
}
use XSLoader;
eval {
  XSLoader::load Cac unless $Cac::xs_loaded++; # this is in cacperl.xs :)
};
die "\n\nCan't load Cac-XS.\nThis happen when you use a plain Perl that is not embedded in Cache\n"
    ."Use the cperl script provided in the Cache-Perl distribution, loading Cache-Perl without\n"
    ."that will fail in any case\n\n$@" if $@;

require Exporter;
use AutoLoader qw(AUTOLOAD);

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use Cac ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.

our @EXPORT = qw(
	&CacEval &CacExecute	&CacHome
);

our %EXPORT_TAGS = ( 'all' => [ @EXPORT ],
                     'highlevel' => [ qw(
                                         _CacAbort _CacContext _CacConvert _CacConvert2                                         
                                         _CacCtrl _CacCvtIn _CacCvt_Out _CacEnd
                                         _CacError _CacErrxlate _CacEval
                                         _CacExecute _CacPrompt _CacSignal _CacStart
                                         _CacType 
                                      )
                                    ],
                     'lowlevel' => [ qw(
                                         _CacCloseOref _CacDoFun _CacDoRtn _CacExtFun
                                         _CacGetProperty _CacGlobalGet _CacGlobalSet
                                         _CacIncrementCountOref _CacInvokeClassMethod
                                         _CacPop _Cac_PopDbl _CacPopInt _CacPopList
                                         _CacPopOref _CacPopStr _CacPopPtr
                                         _CacPushDbl _CacPushFunc _CacPushFuncX
                                         _CacPushGlobal _CacPushGlobalX _CacPushInt
                                         _CacPushList _CacPushMethod _CacPushOref
                                         _CacPushProperty _CacPushPtr _CacPushRtn
                                         _CacPushRtnX _CacPushStr _CacSetProperty
                                         _CacUnPop
                                        )],
      
      );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} }, @{ $EXPORT_TAGS{'highlevel'} }, @{ $EXPORT_TAGS{'lowlevel'} });

our $VERSION = 1.83;



sub _CacPop($) {
   die "_CacPop not implemented.";
}


sub _CacPopList()
{
  die "_CacPopList is currently not implemented - sorry.";
}


sub _CacPopPtr() {
   die "_CacPopPtr is currently not implemented";
}


1;
__END__