This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRIS, see the InterSystems IRIS Adoption Guide and the InterSystems IRIS In-Place Conversion Guide, both available on the WRC Distributions page (login required).

Home > Class Reference > %SYS namespace > %Library.COSCallout

%Library.COSCallout

class %Library.COSCallout extends %Library.RegisteredObject

Transform COS source code to a parse tree

Internal ISC code, not for customer use - these interfaces may change without warning

Property Inventory (Including Private)

Method Inventory (Including Private)

Properties (Including Private)

property BinDir as %String (TRUNCATE = 1);

The directory for CacheObjectScript.DLL.

Defaults to the CacheSys/Bin directory - change it if you want to debug a different version of the DLL.

Property methods: BinDirDisplayToLogical(), BinDirGet(), BinDirIsValid(), BinDirLogicalToDisplay(), BinDirLogicalToOdbc(), BinDirNormalize(), BinDirSet()
property DLLCallMode as %Integer [ InitialExpression = 3 ];

How we call the DLL

Takes one of the following values :-

1 - use $ZF(-3) ... handy for debugging the DLL because it doesn't stay loaded

2 - use $ZF(-4)/$ZF(-5) ... to cache the DLL handle

3 - use $ZF(-4)/$ZF(-6) ... the default - there's normally no reason to change it

Initialised to 3

Property methods: DLLCallModeDisplayToLogical(), DLLCallModeGet(), DLLCallModeIsValid(), DLLCallModeLogicalToDisplay(), DLLCallModeNormalize(), DLLCallModeSet()
property DLLHandle as %Integer [ InitialExpression = 0 ];

The cached DLLHandle (used only when DLLCallMode=2)

Property methods: DLLHandleDisplayToLogical(), DLLHandleGet(), DLLHandleIsValid(), DLLHandleLogicalToDisplay(), DLLHandleNormalize(), DLLHandleSet()
property DLLResultCode as %String (TRUNCATE = 1);

Set to a result code string

Mainly of use to Intersystems support.

Property methods: DLLResultCodeDisplayToLogical(), DLLResultCodeGet(), DLLResultCodeIsValid(), DLLResultCodeLogicalToDisplay(), DLLResultCodeLogicalToOdbc(), DLLResultCodeNormalize(), DLLResultCodeSet()

Methods (Including Private)

method %OnClose() as %Status
Inherited description: This callback method is invoked by the %Close() method to provide notification that the current object is being closed.

The return value of this method is ignored.

method Compile(SourceStream As %CacheString, ErrorsStream As %CacheString, ByRef ColoringErrors As %Boolean) as %Boolean

Convert the given COS source code to a parse tree

  • SourceStream is a stream containing the source code

  • ErrorsStream is a stream to which any error messages are written

The return value is 1 on success, 0 on failure

If 0 is returned the caller should see the DLLResultCode property for information about failure.

CacheObjectScript.DLL must be in the directory given by the BinDir property. By default this points to the CacheSys/Bin directory.


In the example below SourceIn and ErrorsOut are streams. SourceIn supplies the source code and ErrorsOut receives any error messages.

  Set TT=##class(%Library.COSCallout).%New()
  Set Ret=TT.Compile(SourceIn,ErrorsOut)
  If 'Ret Write "Fatal error: ",TT.DLLResultCode,! ZTrap
  Do Errors.Rewind()
  If 'Errors.AtEnd {
    //... show Errors
  }
  Else {
    //... use tree
  }
  
private method ConfigName() as %String

Helper function to return the Caché configuration name.

private method ConfigPath() as %String

Helper function to return the Caché configuration path.

private method InvokeDLL(DLLFunction As %Integer, DLLArgs) as %List

Invoke the CacheObjectScript DLL function (DLLFunction), passing DLLArgs.

Returns what the $ZF call into the DLL returns, or something in the same format :-

$LISTBUILD(ZFOK, $LISTBUILD(Lang1, Lang2, ...), ColoringErrors, DLLResultCode)

classmethod PathToDLL() as %String

Return the path to the DLL

private method SetDefaultBinDir()

Set the default CacheSys/Bin directory

private method ZF5(handle As %Integer, DLLFunction As %Integer, DLLArgs, ByRef failed As %Boolean) as %String

Sets failed to 1 if the $ZF(-5,..) call fails, otherwise sets it to 0 and returns the DLL return code

private method ZF6(DLLPath As %String, DLLFunction As %Integer, DLLArgs, ByRef failed As %Boolean) as %String

Sets failed to 1 if the $ZF(-6,..) call fails, otherwise sets it to 0 and returns the DLL return code

Inherited Members

Inherited Methods (Including Private)