Copyrights

How to create custom $Z variable

Some tasks of applications porting to MiniM are reguired to emulate $Z system variable which does not implemented by MiniM. This article describes how to create custom $Z variable and use as an example $ZPOS variable

To create custom $Z variable in MiniM, we must to use three features of MiniM Database Server:

1. MiniM allow to create custom $Z function on MUMPS.
2. Subroutine call without arguments in MiniM is equal to call subroutine with zero arguments.
3. MiniM use user-defined custom $Z functions case insensitive.

This is call to subroutine without arguments:

s retvalue=$$func^routine

This is call to subroutine with zero arguments:

s retvalue=$$func^routine()

As long as MiniM Database Server use this two calls equal, we can create custom $Z variable, which in real is custom $Z function and defined custom $Z function with zero arguments.

Let to implement as an example $ZPOS system variable as a custom $Z variable. This variable returns current file position is current device is a file defice. In MiniM this device have a |FILE| type.

It is required to create routine with prefix %ZFUNC. In example let it be a %ZFUNCFILE routine name, and place inside subroutines related to a |FILE| device.

Inside this routine we must create subroutine with label name ZPOS in upper case only. This subroutine must evaluate current file position for current device if this device is a file device and return a value. In MiniM Database Server this is done by the $v("dev",8) function.

Example of the %ZFUNCFILE routine:

%ZFUNCFILE ; emulate $ZPOS system variable
 q
ZPOS ; return current offset of file device
 q $v("dev",8)

After routine creation and compiling additional $ZPOS system variable is ready to use. No any registration and other data changes are required. For example:

  s dev="|FILE|zscript.vbm" 
  o dev:("rwt") 
  u dev 
  r line 
  s pos=$zpos 
  c dev

Here we open file device in text mode, read one line and evaluate current file position in the file device by call to newly created $Z variable $zpos, and close the file.

MiniM Database Server allow to create any additional $Z variables if programmer can implement return value evaluation by any method using MUMPS, or $v(), or extended $zdll() call.

Programmer must understand that built-in $Z variables cannot be redefined in MiniM Database Server.