Miscellaneous Functions

Breakpoint procedure

Allows to interrupt the execution of a script. While its major use is internal at DAVID while implementing new script commands, the Breakpoint procedure can be handy during development of a script because it lets the user decide whether to continue or abort the script.

Synopsis

CODE

Breakpoint("Do you want to abort the script?")

Parameters

Name	Type	Required?	Description
`message`	string	no	The message that is displayed

Returns

This function doesn’t return a value.

Remarks

With the call from the “Synopsis” section, the user sees this message box:

DebugOut procedure

Prints a string to the debug console if DBM is currently running under a debugger.

Synopsis

CODE

DebugOut("My message; parameter value is %par_value")

Parameters

Name	Type	Required?	Description
message	string	yes	The string to write. Embedded variables are replaced by their values.

Returns

DebugOut doesn't return a value.

Remarks

Variables can be embedded in the message parameter and will be resolved before the string is printed. Undefined variables resolve into an empty string. To include a variable, use the $varname or %varname syntax, or optionally, ${varname} or %{varname}. The curly braces notation helps to avoid ambiguities, like "%v0" which results in the content of the v0 local variable vs. "%{v}0" which results in the content of the v local variable, followed by a zero.

DllCall function

Calls a function that is defined in a separate DLL file.

The function must strictly follow these rules. Failure to do so will result in undefined behaviour, including malfunction and crash. Unfortunately, DBM has no chance to verify that the rules are followed, so DllCall should only be used when you have run out of other options!

The DLL is pure unmanaged code, e.g. written in C or C++ (but not C++/CLI or C#).
The function takes exactly one argument; this argument is a pointer to a zero-terminated UCS-2 string (C/C++ type LPCWSTR).
The function returns a zero-terminated UCS-2 string. The memory for this string is allocated by the function through a call to GlobalAlloc. The actual return value is a HGLOBAL. DBM calls GlobalFree to release the memory.
If the function doesn’t return a value, it should return NULL.

Synopsis

CODE

%function_result = DllCall("C:\path\to\dll\MyDll.dll", "DllFunction", "parameter")

Parameters

Name	Type	Required?	Description
`path`	string	yes	The full path to the DLL file (see “Remarks”)
`function`	string	yes	The name of the function
`parameter`	any	yes	The parameter for the function

Returns

DllCall returns whatever the called function returns.

Remarks

The path parameter should specify an absolute file path. Relative paths may work, but their use is discouraged because a relative path introduces a source of errors that are not easy to track down.
path must include the name and extension of the DLL file.
Depending on how you create the DLL, the function parameter may require an additional leading underscore. function is the name which the DLL exports.
If parameter is a number, it is converted into a string.
The DLL file is not unloaded after execution because odds are high that it will soon be used again; this DBM saves the overhead and execution time of repeatedly unloading and loading the file. To release the file, you must close DBM.

GetCurrentUser function

Returns information about the currently logged-in user.

Synopsis

CODE

%user_info = GetCurrentUser()

Parameters

(none)

Returns

A JSON object with the fields “name”, “long_name”, and “full_name”. If no user is logged in, all three fields contain empty strings.

GetProcessId function

Returns the Windows process ID of the DBM process.

Synopsis

CODE

%pid = GetProcessId()

Parameters

(none)

Returns

The process ID as a number.

Login/Logon procedures

Logs a user into DBM. Both commands are synonymous to each other. If a user is already logged in, they are logged off before logging in the new user.

Synopsis

CODE

Login(MyUser, MyPassword)

Parameters

Name	Type	Required	Description
`name`	string	yes	The user’s name
`password`	string	yes	The user’s password

Returns

The procedure doesn’t return a value.

Logout/Logoff procedures

Logs a user out of DBM. Both commands are synonymous to each other. No-op if no user is logged in.

Synopsis

CODE

Logout()

Parameters

(none)

Returns

The procedure doesn’t return anything.

makeguid function

CReates a GUID (“globally unique identifier”).

Synopsis

CODE

%guid = makeguid()

Parameters

(none)

Returns

A string that represents a GUID.

MessageBox function

Displays a short message on the screen ad waits for the user to click a button.

Synopsis

CODE

%reply = MessageBox("This will do something", "Confirm", MB_OKCANCEL)
if (%reply == "IDOK") { ... }

Parameters

Name	Type	Required?	Description
`message`	string	yes	The message text.
`title`	string	no	The title displayed in the message box. If unspecified or empty, the title is “Database Manager”.
`type`	string	no	The message box type (see below). Defaults to `MB_OK`.

Message box types

Type	Descrption
`MB_OK`	.The message box contains an “OK” button
`MB_OKCANCEL`	The message box contains an “OK” button and a “Cancel” button.
`MB_YESNO`	The message box contains a “Yes” button and a “No” button.

Returns

The return value is a string that describes the button which the user clicked:

Button	Return Value
OK	`IDOK`
Cancel	`IDCANCEL`
Yes	`IDYES`
No	`IDNO`

Shutdown procedure

Closes DBM and finishes its current session.

Synopsis

CODE

Shutdown(silent)

Parameters

Name	Type	Required?	Description
`silent`	string	no	If specified as “silent” (in any combination of upper and lower case), DBM skips all confirmations before closing down.

Returns

This function does not return.

varexist function

Synopsis

CODE

%exists = varexist($var1, %var2, ...)

Parameters

Any number of parameters are accepted, but each parameter must be a reference to a local or global variable; expressions are not allowed.

Returns

If each parameter is the name of a variable that exists and is visible within the current variable scope, then varexist returns 1.
Otherwise returns 0.