| MIL 10 Reference
| Customize Help
| Save Settings

MfuncAllocScript


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux with restrictions

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MfuncAllocId
MfuncBufAncestorId
Synopsis
Allocate a MIL function context for your script-based user-defined MIL function.
Syntax
MIL_ID MfuncAllocScript(
MIL_CONST_TEXT_PTR FunctionName, //in
MIL_INT ParameterNum, //in
MIL_CONST_TEXT_PTR InterpreterLanguage, //in
MIL_CONST_TEXT_PTR ScriptFileName, //in
MIL_CONST_TEXT_PTR ScriptFunctionName, //in
MIL_INT ScriptFunctionOpcode, //in
MIL_INT64 InitFlag, //in
MIL_ID *ScriptBasedContextFuncIdPtr //out
)
Description

This function allows you to allocate a MIL function context for the current script-based user-defined MIL function. Being script-based, the function will, instead of calling a C function, run a function in a script. Call MfuncAllocScript() in the master function of the user-defined function. MfuncAllocScript() signals the creation of a user-defined MIL function, and should be the first MIL function called in the master function. It will also allocate a MIL function context identifier for the current function. You should use this MIL function context identifier as an argument for other Mfunc...() functions used during the user-defined function's execution. Once the function context is allocated, your function is known as a script-based user-defined MIL function. A script-based user-defined MIL function is considered a standard MIL function, respecting all MIL environment controls, such as tracing and error handling. The script that you provided as the slave-portion of the function is compiled/interpreted at runtime.

When defining the function context, you must specify a unique opcode for the script-based user-defined function. The opcode is used to locate the script-based user-defined function when an application calls the script-based user-defined function. You must also specify the language in which the script is written.

Script-based user-defined MIL functions can be grouped into user-defined script modules or remain ungrouped. To specify whether a user-defined function is grouped or not, and if grouped, assign it to a specific user-defined script module, pass an appropriate opcode to the ScriptFunctionOpcode parameter. Specify the opcode as a combination of two values: an offset from 0 to 63 and a label either identifying the module in which to group the function (M_SCRIPT_MODULE...) or identifying that the function is ungrouped (M_SCRIPT_FUNCTION). A user-defined script module can have up to 64 functions, and there can be up to 64 ungrouped functions.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
FunctionName

Specifies the name of the script-based user-defined MIL function.

function map For specifying the name of the user-defined function
CollapseValue Description
Collapse MIL_TEXT("FunctionName") 1

Specifies the name of the script-based user-defined MIL function.

This is the same as the name of the current master function. This is also the name that you will use to call the user-defined function in your application. The name of the function must be a null-terminated string.

(summarize)

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

ParameterNum

Specifies the number of parameters to be registered for the current user-defined function.

function map For specifying the number of parameters
CollapseValue Description
Collapse 0 <= Value <= 15

Specifies the number of parameters that you register for the function using MfuncParam() (or one of the type-specific versions of this function such as MfuncParamMILInt()). This should correspond to the number of parameters passed to the current user-defined function.

(summarize)
InterpreterLanguage

Specifies the language and language version in which the script is written.

function map For specifying the path to the language interpreter.
CollapseValue Description
Collapse

Specifies that the script is written in a language that can be identified using the supplied custom interpreter interface DLL. This DLL must contain all the information required for interfacing between MIL and the script that you provide as the slave portion of the function, passing the specified parameters to the script, and (optionally) returning a result to MIL. You must develop the custom interpreter interface DLL from the code provided by MIL. This code can be found in the "\Matrox Imaging\MIL\Scripting\MilInterpCustom" directory of your MIL installation. A custom interpreter interface DLL is required for every different language (or language version) you want to use with the Function Development module.

The language must be a version of Python or a language supported by the .NET Framework.

When developing a script-based user-defined MIL function, which will be used in a Distributed MIL application, and using a language or language version for which an interpreter interface DLL is not provided, it is recommended that a copy of the DLL file be placed on all the remote computers in the cluster, in a directory which is part of the computer's path environment variable. You must also ensure the presence of an appropriate MIL wrapper and the interpreter/ .NET framework on these computers.

(summarize)
Parameters

Specifies the drive, directory, and name of the file of the custom interpreter interface DLL file that you provide (for example, "C:\mydirectory\myCustomDLL.dll").

To specify the file on a remote computer (under Distributed MIL), prefix the specified file name string with "remote:///" (for example, "remote:///C:\mydirectory\myCustomDLL").

If the DLL file is not located in a directory that is part of the path environment variable, you must provide the full path to the file.
Collapse M_INTERPRETER_C_PYTHON27

Specifies that a CPython 2.7 based script is used.

Note that the script must be written using this version of the language.

(summarize)
Collapse M_INTERPRETER_C_PYTHON34

Specifies that a CPython 3.4 based script is used.

Note that the script must be written using this version of the language.

(summarize)
Collapse M_INTERPRETER_CSHARP
[This is only applicable to Windows]

Specifies that C# based code is used.
Collapse M_INTERPRETER_VB_DOT_NET
[This is only applicable to Windows]

Specifies that VB.NET based code is used.

(summarize)
ScriptFileName

Specifies the name and path of the file containing the user-defined script. The script file must be accessible to the computer executing the script.

If the script file is not located in a directory that is part of the path environment variable, you must provide the full path to the file.

When developing a script-based user-defined MIL function that will be used in a Distributed MIL application, it is recommended that a copy of the script file be placed on all the remote computers in the cluster, in a directory that is part of the computer's path environment variable.

ScriptFunctionName

Specifies the name of the function to export from the script file.

Note that, unless using a custom interpreter interface DLL, an error is generated if no function name is provided. If a custom interpreter interface DLL is used which doesn't require a function name, you can pass M_NULL to this parameter.

ScriptFunctionOpcode

Specifies the opcode to use to locate the script-based user-defined MIL function when an application calls the function. The opcode also serves to identify the module in which to group the function, if any.

To set a label identifying that the script-based user-defined MIL function is ungrouped, or a label identifying the module in which it is grouped, set one of the following:

function map For setting the label identifying that the function is grouped or ungrouped
CollapseValue Description
Collapse M_SCRIPT_FUNCTION +

Specifies that the script-based user-defined MIL function is an ungrouped user-defined MIL function.


You must specify a combination value from the following table:
(summarize)
Collapse M_SCRIPT_MODULE_1 +

Specifies that the script-based user-defined MIL function will be grouped in the first module.


You must specify a combination value from the following table:
(summarize)
Collapse M_SCRIPT_MODULE_2 +

Specifies that the script-based user-defined MIL function will be grouped in the second module.


You must specify a combination value from the following table:
(summarize)
Combination constant for any of the possible values of the ScriptFunctionOpcode parameter.

You must add the following value to the above-mentioned values to set the offset.

function map For setting the offset
CollapseCombination value Description
Collapse 0 <= Value <= 63

Sets the offset of the script-based user-defined MIL function among the ungrouped user-defined MIL functions or among those in the specified group.

When allocating multiple user-defined MIL functions in a single user-defined module, you must set a different offset for each new user-defined MIL function in the module (for example, M_SCRIPT_MODULE_1 + 12).

To allocate a script-based user-defined MIL function that is not grouped in a user-defined module, use M_SCRIPT_FUNCTION + the offset; you must set a different offset for each new ungrouped user-defined MIL function.

(summarize)
InitFlag

Specifies more information about the script-based user-defined MIL function.

The values below allow you to set whether the script-based user-defined MIL function is executed asynchronously or synchronously.

function map For specifying whether the script-based user-defined MIL function is executed asynchronously or synchronously
CollapseValue Description
Collapse M_DEFAULT

Specifies the default value.

If the system on which the function context is allocated has a remote processor, the default is the same as M_ASYNCHRONOUS_FUNCTION + M_REMOTE, if the system does not have a remote processor, the default is the same as M_SYNCHRONOUS_FUNCTION + M_LOCAL.

(summarize)
Collapse M_ASYNCHRONOUS_FUNCTION +

Specifies that the script-based user-defined MIL function will not wait for the slave script/function to finish executing before executing the next function (typically MfuncFree()) in the master function.


You must specify a combination value from the following table:
(summarize)
Collapse M_SYNCHRONOUS_FUNCTION +

Specifies that the script-based user-defined MIL function will wait for the slave script/function to finish executing before executing the next function in the master function.


You must specify a combination value from the following table:
(summarize)

You must add one of the following values to the above-mentioned values to set whether the script-based user-defined MIL function can be executed remotely.

function map For specifying whether the script-based user-defined MIL function can be executed remotely
CollapseCombination value Description
Collapse M_LOCAL

Specifies that the script-based user-defined MIL function must be executed by the Host processor. Note that MIL functions called from the script-based user-defined MIL function will still be executed on their target system.

This value cannot be added to M_ASYNCHRONOUS_FUNCTION.

(summarize)
Collapse M_REMOTE

Specifies that the script-based user-defined MIL function will be executed remotely, if possible. For more information, see the Steps to create a user-defined MIL function section of Chapter 33: The MIL function development module.

(summarize)
Combination constants for M_SYNCHRONOUS_FUNCTION.

You can add one of the following values to the above-mentioned value to set the type of the script-based user-defined MIL function.

Note that both M_ALLOC and M_FREE imply that the script-based user-defined MIL function is M_SYNCHRONOUS_FUNCTION, and cannot be added to M_ASYNCHRONOUS_FUNCTION.

function map For setting the type of script-based user-defined MIL function
CollapseCombination value Description
Collapse M_ALLOC

Specifies that the script-based user-defined MIL function is an allocation function, used to allocate a user-defined MIL object on a required system.
Collapse M_FREE

Specifies that the script-based user-defined MIL function frees an object allocated using a user-defined MIL allocation function. Note that when this value is used, the user-defined MIL function must accept the MIL identifier of the object to free as its only parameter.

(summarize)
ScriptBasedContextFuncIdPtr

Specifies the address of the variable in which to store the MIL identifier of the allocated MIL function context. Since the MfuncAllocScript() function also returns the MIL identifier, you can set this parameter to M_NULL.

Return value
The returned value is the MIL function context identifier if the allocation is successful. If allocation fails, M_NULL is returned.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
INTERPRETER C PYTHON27 INTERPRETER C PYTHON34 INTERPRETER CSHARP INTERPRETER VB DOT NET SCRIPT FUNCTION SCRIPT MODULE 1 SCRIPT MODULE 2 DEFAULT ASYNCHRONOUS FUNCTION SYNCHRONOUS FUNCTION LOCAL REMOTE ALLOC FREE