Copyrights

MiniM ZDLL Module for External ActiveScript Engines

There is MiniM ZDLL module to call external ActiveScript Engines such as VBScript, JScript, PerlScript or PythonScript. Also can be used other script engines with Microsoft ActiveScripting interface.

Module zscript contains:

• zscript.dll as MiniM ZDLL module
• Routine ^%ZSCRIPT in %zscript.rou
• Sample routine ^scripts in scripts.rou
• Sample external VBScript code in zscript.vbm
• This documentation as zscript.html

Module can be installed using installer setup-zscript.exe. Installer install documentation file zscript.html into /doc subdirectory of MiniM installation.

General purposes of zscript module is

• Create and hold ActiveScript Engine object
• Call external scripts
• Allow external scripts to call MiniM process

Common steps to run external scripts are:

1. Load and hold zscript module
2. Add scripts on other languages
3. Call script engine
4. Unload zscript module

After unloading zscript module all internal data and modules are losted.

Function description

Full zscript functionality is available using ^%ZSCRIPT routine.

LoadLibrary()

Function load and hold zscript module into MiniM process. After loading module is ready to work. If zscript module is already loaded this function does not do anything.

Return: empty string on success and error description or trap on error.

Example:

 s err=$$LoadLibrary^%ZSCRIPT()

UnloadLibrary()

Function unload previously loaded zscript module. After unloading external scripts are not accessible. If zscript module does not loaded this function does not do anything.

Return: empty string.

Example:

 s err=$$UnloadLibrary^%ZSCRIPT()

LangInstalled(lang)

Function determine that ActiveScripting language lang is installed on current computer or not. If ActiveScript engine for this language is installed on current computer one can be used, otherwise not. Note: this function does not require zscript module loading and works properly in both cases.

Parameter lang should contain language name, for example "VBScript", "JavaScript".

Return: if selected language is installed and supported on this computes function return non zero number and return 0 if this language not installed.

Example:

USER>w $$LangInstalled^%ZSCRIPT("VBScript")
1
USER>w $$LangInstalled^%ZSCRIPT("UnknownScript")
0
USER>w $$LangInstalled^%ZSCRIPT("JavaScript")
1
USER>w $$LangInstalled^%ZSCRIPT("PerlScript")
1
USER>w $$LangInstalled^%ZSCRIPT("Script")
1

AddFile(FileName,Language)

Function adds into current script engine one more script module. One script module can contain variables and functions written using selected language. Common script context is a set of modules and different modules can have different languages. Module can contain set of functions which can be called from MiniM process later. Functions of module are accessible after script module is loaded. Each script module has name. After loading from file module has name as this file.

Function AddFile adds module text from file specified in FileName.

Return: empty string if module loaded correctly and string with error description or trap error.

Example:

 s filename="zscript.vbm"
 s lang="VBScript"
 s err=$$AddFile^%ZSCRIPT(filename,lang)

This example adds script module from file "zscript.vbm" as "VBScript" language.

ListModules(modules)

Function enumerates loaded into script context script modules with names and languages. Names are listed as subindex of local variable modules.

Return: empty string on success or trap error on error.

Example:

USER>s filename="zscript.vbm"

USER>s lang="VBScript"

USER>s err=$$AddFile^%ZSCRIPT(filename,lang)
USER>i $$ListModules^%ZSCRIPT(.list)

USER>w
err=""
filename="zscript.vbm"
lang="VBScript"
list("zscript.vbm")="VBScript"

Here listed one module "zscript.vbm" with language "VBScript".

AddSource(ModuleName,Source,Language)

Function adds into current script context one more module from string Source with name ModuleName and language Language. Module text can be created programmatically.

Return: empty string on success.

Example:

USER>n code="function abc( a, b){ return ""a = "" + a + "", b = "" + b;}"

USER>n module="ddd"

USER>n lang="JScript"

USER>i $$LoadLibrary^%ZSCRIPT()

USER>i $$AddSource^%ZSCRIPT(module,code,lang)

USER>i $$ListModules^%ZSCRIPT(.list)

USER>w
code="function abc( a, b){ return "a = " + a + ", b = " + b;}"
lang="JScript"
list("ddd")="JScript"
module="ddd"

Here listed one module with name "ddd" and language "JScript".

DeleteAllModules()

Function clears all set of currently loaded script modules.

Return: empty string on success.

Example:

s err=$$DeleteAllModules^%ZSCRIPT()

DeleteModule(ModuleName)

Function deletes from currently loaded set of modules specified in ModuleName module. After deletion this module is not accessible.

Return: empty string on success.

Example:

s err=$$DeleteModule^%ZSCRIPT("ddd")

Func(%ModuleName,%Name,%p...)
Proc(%ModuleName,%Name,%p...)

This function calls script engine, use %Name as script's function name in %ModuleName module. Functions pass parameters to script functions using %p parameter. Instead %p parameter programmer can specify no or one or many parameters passed by value.

Function Func need to be called script function which return value (as function) and function Proc need to be called script function which does not return value (as procedure).

Example:

 n code="function abc( a, b){ return ""a = "" + a + "", b = "" + b;}"
 n module="ddd"
 n lang="JScript"
 i $$LoadLibrary^%ZSCRIPT()
 i $$AddSource^%ZSCRIPT(module,code,lang)
 w "JScript func return: ",$$Func^%ZSCRIPT(module,"abc",123,456),!
 i $$UnloadLibrary^%ZSCRIPT()

Here function $$Func^%ZSCRIPT(module,"abc",123,456) calls JavaScript function abc from module "ddd" and pass two parameters: 123 and 456.

Return: function Func return value returned by script function and Proc has not any return.

ActiveScript engine context

Inside script engines zscript module exposes one global object with name MiniM wich have 3 functions: MTEXT, EXECUTE and EVALUATE. Functions names are case insensitive. Script functions can call this global object using approptiate syntax, it depends on script language.

MText(Text)

Function doubles quote symbols and decorates unprintable bytes to be used as syntactically correct MUMPS string or expression.

Return: decorated string.

Example:

  AccName = MiniM.Mtext( objItem.Element )

Execute(Commands)

This function execute MUMPS commands specified in Commands parameter. String is passed into MiniM process and executes. After execution control returns into script context.

Return: none.

Example:

MiniM.Execute( "k printers")
MiniM.Execute( "s printers(" & id & ")=" & Caption)

Evaluate(Expression)

This function call MiniM process to evaluate MUMPS expression specified as parameter Expression. After evaluation control returns into script context.

Return: expression evaluated as string.

Example:

  id = MiniM.Evaluate( "$i(printers)")

Script's error handling

While external scripts executes, can be detected script's engines runtime errors. If script errors occurs, generated error <ZSCRIPT> Error specification contains line and symbol position.

USER>s code="function abc( a, b){ retu;}"

USER>i $$AddSource^%ZSCRIPT("ddd",code,"JScript")

USER>w $$Func^%ZSCRIPT("ddd","abc",123,456),!

<ZScript error line 1, pos 22> ::Func+5^%ZSCRIPT::

Line and position values are depends of script engine.

Additional $ZERROR informaion show routine place where error occurs.

Examples

With zscript module are distributed two examples: call simple function loaded from source and call script from external file. External script on VBScript calls WMI instrumentation object to get available printers and current user account's lists. Both functions (printers and accounts has very small differences and couns as one example). See example routine scripts in file scripts.rou and VBScript functions in file zscript.vbm.

Example how to work sample code:

USER>d printers^scripts w
printers=5
printers(1)="Fax"
printers(2)="EPSON TX117_119 Series"
printers(3)="EPSON TX117_119"
printers(4)="Acrobat PDFWriter"
printers(5)="Acrobat Distiller"

Installer setup-zscript.exe installs files:

• zscript.dll into /bin subdirectory
• %zscript.rou into /bin subdirectory and imports into "%sys" database
• scripts.rou into /bin subdirectory and imports into "user" database
• zscript.vbm into /bin subdirectory
• zscript.html into /doc subdirectory

Download setup-zscript.exe (exe, 0.45Mb)

To add module send text description and zip archive to mail: support@minimdb.com