| MIL 10 Reference
| Customize Help
| Save Settings

MfuncAlloc


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
Previous
MfuncAllocId
Synopsis
Allocate a MIL function context for your user-defined function.
Syntax
MIL_ID MfuncAlloc(
MIL_CONST_TEXT_PTR FunctionName, //in
MIL_INT ParameterNum, //in
MIL_FUNC_FUNCTION_PTR SlaveFunctionPtr, //in
MIL_CONST_TEXT_PTR SlaveFunctionDLLName, //in
MIL_CONST_TEXT_PTR SlaveFunctionName, //in
MIL_INT SlaveFunctionOpcode, //in
MIL_INT64 InitFlag, //in
MIL_ID *CBasedContextFuncIdPtr //out
)
Description

This function allows you to allocate a MIL function context for the current user-defined function. Call MfuncAlloc() in the master function of the user-defined function. MfuncAlloc() signals the creation of a user-defined MIL function context, and should be the first MIL function called in the master function. Once the function context is allocated, your function is known as a user-defined MIL function. A user-defined MIL function is considered a standard MIL function, respecting all MIL environment controls, such as tracing and error handling.

When defining the function context, you must specify a unique opcode for the user-defined function. The opcode is used to locate the slave function when an application executes the user-defined function.

MIL user-defined functions can be grouped into user-defined 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 module, pass an appropriate opcode to the SlaveFunctionOpcode 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_USER_MODULE_n, where n is a number between 1 and 7) or identifying that the function is ungrouped (M_USER_FUNCTION). A user-defined 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 user-defined function.

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

Specifies the name of the user-defined 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 MIL 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 passed to the current user-defined function. Note that the number of parameters should not exceed 16.

SlaveFunctionPtr

Specifies the address of the slave function.

The slave function must be declared as follows:

void MFTYPE SlaveFunction(
MIL_ID FunctionId
)
Parameters
FunctionId

Specifies the identifier of the user-defined MIL function that references this slave function. This is the identifier returned by the MfuncAlloc() function.

If your slave function will be executed by a system with an on-board processor or if the your slave function's code will be compiled into a library file, you can set this parameter to M_NULL.

SlaveFunctionDLLName

Specifies the name of the library file which contains the slave function's code. The library file must be visible to the system executing the slave function.

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

If the library file is not located in a directory which is part of the path environment variable, you can alternatively provide the full path to the file.

If your slave function will be executed by a system with an on-board processor or if the your slave function's code will be included in your application, you can set this parameter to M_NULL.

SlaveFunctionName

Specifies the name of the slave function to export from the library file.

This parameter must be set if a library file is provided to the SlaveFunctionDLLName parameter.

If your slave function will be executed by a system with an on-board processor or if the your slave function's code will be included in your application, you can set this parameter to M_NULL.

SlaveFunctionOpcode

Specifies the opcode to use to locate the slave function when an application executes the user-defined MIL function. The slave function's opcode also serves to identify which user-defined module, if any, the user-defined function belongs to.

To specify a label identifying that the function is ungrouped, or a label identifying the module in which the function is grouped, specify one of the following:

function map For specifying the label identifying that the function is grouped or ungrouped
CollapseValue Description
Collapse M_USER_FUNCTION +

Specifies that the user-defined function is an ungrouped user-defined function.


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

Specifies the module in which to group the user-defined function, where n is a value between 1 and 7, inclusive.


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

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

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

Specifies the offset of the user-defined function among the ungrouped functions or among the functions in a specified group.

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

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

(summarize)
InitFlag

Specifies more information about the user-defined MIL function.

The values below allow you to set whether the slave function is executed asynchronously or synchronously.

function map For specifying whether the slave 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 user-defined function will not wait for the slave 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 user-defined function will wait for the slave 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 slave function can be executed remotely.

function map For specifying whether the slave function can be executed remotely
CollapseCombination value Description
Collapse M_LOCAL

Specifies that the slave function must be executed by the Host processor. Note that MIL functions called from the slave 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 slave function will be executed remotely, if possible. If you select M_REMOTE, but do not compile your slave function with a cross-compiler specific to the target processor, an error will be generated. 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 user-defined MIL function.

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

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

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

Specifies that the user-defined 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)
CBasedContextFuncIdPtr

Specifies the address of the variable in which to store the MIL identifier provided for the user-defined function. Since the MfuncAlloc() function also returns the MIL identifier, you can set this parameter to M_NULL.

Return value
The returned value is the 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.
USER FUNCTION USER MODULE n DEFAULT ASYNCHRONOUS FUNCTION SYNCHRONOUS FUNCTION LOCAL REMOTE ALLOC FREE