MsysAlloc

This function allocates a MIL system so that it can be used by subsequent MIL functions. This function can allocate a MIL system, which consists of a Matrox imaging board (or third-party board), the Host CPU and memory, and any available graphics controller. Alternatively, this function can allocate a Host-type system, which consists of the Host CPU and memory, and any available graphics controller. Upon execution of this function, MIL ensures that it can open communication with the hardware associated with the system before allocating it, and generates an error if it cannot.

A system must be allocated before any buffers, displays, or digitizer can be allocated on it. Before allocating a system, an application must be allocated, using MappAlloc() or MappAllocDefault(). To use the default system, you must allocate it using M_SYSTEM_DEFAULT.

Note, upon allocation of an application, a default Host system is automatically allocated. Rather than using MsysAlloc() to allocate a Host system, you can use this default Host system, by specifying M_DEFAULT_HOST wherever a Host system identifier is required.

When you no longer need a particular system, free it using MsysFree().

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 which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

ContextAppId

Specifies the identifier of the application context to use.

For specifying the application context
Value	Description
M_DEFAULT	Specifies the current application context.
Application Context Identifier	Specifies the application context identifier.

SystemDescriptor INQ

Specifies the type of system to allocate. Set this parameter to one of the following values:

For specifying the type of system to allocate
Value	Description		MIL system-specific tooltip (†)
M_SYSTEM_1394	Allocates a MIL IEEE 1394b IIDC system.		†					e
M_SYSTEM_CRONOSPLUS	Allocates a MIL CronosPlus system.		†		b
M_SYSTEM_DEFAULT	Specifies the default system. This value is set during MIL installation and using the MILConfig utility. Note that the end-user can always change this value. (summarize) Specifies the default system. (more details...)		†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_SYSTEM_GIGE_VISION	Allocates a MIL GigE Vision system. This allocation opens general communication with all the GigE Vision-compliant cameras (or devices) found on your subnet (through one or more Gigabit Ethernet network adapters in your computer). (summarize) Allocates a MIL GigE Vision system. (more details...)		†			c																s
M_SYSTEM_GPU	Allocates a MIL GPU system.		†				d
M_SYSTEM_HOST	Specifies a Host system. Note that a Host system has no hardware-supported acquisition capabilities, however some acquisition capabilities are available when using a simulated digitizer, allocated using MdigAlloc() with M_EMULATED. (summarize) Specifies a Host system. (more details...)		†	a					f
		MIL system specific
		A Host system, allocated on a Matrox Iris GT platform, is allocated on-board your Matrox Iris GT, but the system has no access to the acquisition capabilities of the Matrox Iris GT driver. To access the Matrox Iris GT acquisition capabilities, you must allocate a MIL Iris GT system (with M_SYSTEM_IRIS_GT).	†						f
M_SYSTEM_IRIS_GT	Allocates a MIL Iris GT system.		†						f
M_SYSTEM_MORPHIS	Allocates a MIL Morphis system.		†							g
M_SYSTEM_MORPHISQXT	Allocates a MIL Morphis QxT system.		†								h
M_SYSTEM_ORION_HD	Allocates a MIL Orion HD system.		†									i
M_SYSTEM_RADIENT	Allocates a MIL Radient system.		†										j
M_SYSTEM_RADIENTCXP	Allocates a MIL Radient eV-CXP system.		†											k
M_SYSTEM_SOLIOS	Allocates a MIL Solios system.		†												l	m
M_SYSTEM_USB3_VISION	Allocates a MIL USB3 Vision system. This allocation opens general communication with all the USB3 Vision-compliant cameras (or devices) connected to your computer. (summarize) Allocates a MIL USB3 Vision system. (more details...)		†															o
M_SYSTEM_VIO	Allocates a MIL Vio system.		†														n
MIL_TEXT("dmilpcie://[Passkey:]RemoteComputerName[:Port]/MILSystemType") ¹	[This is only applicable to Matrox Supersight platform] Allocates a DMIL remote system on a remote Matrox Supersight SHB that will communicate with the local SHB, using the PCIe protocol. To allocate a DMIL remote system on a Matrox Supersight SHB, that SHB must have a valid DMIL installation and be in the same Matrox Supersight as the local SHB. When specifying the string that indicates the remote SHB: If required, replace [Passkey] with the passkey for the remote SHB. The passkey is an alphanumeric string of up to 16 characters in length. This passkey is set by the MILConfig utility in the server settings page. If a passkey was not set for the remote system, omit the passkey and the ":" that follows it. Replace RemoteComputerName with the remote SHB's name. This protocol does not support connections to "localhost" or to IP addresses. If required, replace [Port] with the port that the local computer should access on the remote computer to initiate new connections, unless the default server connection port is appropriate; in which case, omit the port number and the ":" that follows it. Replace MILSystemType with any valid MIL system type listed in this table. If the remote system is the Host CPU of another SHB (without a Matrox frame grabber installed) use M_SYSTEM_HOST. The "://" and "/" must be included. Prior to allocating a DMIL remote system, certain conditions must be met. For more information, see Chapter 29: Distributed MIL. (summarize) [This is only applicable to Matrox Supersight platform] Allocates a DMIL remote system on a remote Matrox Supersight SHB that will communicate with the local SHB, using the PCIe protocol. (more details...)		†	a	b	c	d	e	f	g	h	i	j		l	m	n	o	p		r	s
		MIL system specific
		Note that to allocate a remote GPU or Matrox Orion HD system, the Distributed MIL server cannot be running as a service on the remote computer; you must either set it to run at logon, or start it manually. To set it to run at logon, open the MILConfig utility and select Run at every logon with user credentials in the Server Settings pane, found under the Distributed MIL item. To start it manually, you must logon to the remote computer and, from the MILConfig utility, push the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 29: Distributed MIL.	†				d					i
MIL_TEXT("dmilshm://[Passkey:]localhost[:Port]/MILSystemType") ¹	Allocates a DMIL remote system for a separate process on the local computer, using the DMIL SHM protocol. This protocol allows you to communicate between a client and server process on the same computer using shared memory. To allocate a DMIL remote system on a computer, that computer must have a valid DMIL installation. When specifying the string that indicates the local computer: If required, replace [Passkey] with the passkey for the DMIL server on the local computer. The passkey is an alphanumeric string of up to 16 characters in length. This passkey is set by the MILConfig utility in the server settings page. If a passkey was not set for the DMIL server, omit the passkey and the ":" that follows it. Following "localhost:", replace [Port] with the port that the local computer should access to initiate new connections with the DMIL server, unless the default connection port is the listening port of the DMIL server; in which case, omit the port number and the ":" that follows it. Replace MILSystemType with any valid MIL system type listed in this table, such as M_SYSTEM_MORPHIS. The "://" and "/" must be included. The DMIL SHM protocol only supports connections to localhost. Prior to allocating a DMIL remote system, certain conditions must be met. For more information, see Chapter 29: Distributed MIL. (summarize) Allocates a DMIL remote system for a separate process on the local computer, using the DMIL SHM protocol. (more details...)		†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
		MIL system specific
		Note that to allocate a remote GPU or Matrox Orion HD system, the Distributed MIL server cannot be running as a service on the remote computer; you must either set it to run at logon, or start it manually. To set it to run at logon, open the MILConfig utility and select Run at every logon with user credentials in the Server Settings pane, found under the Distributed MIL item. To start it manually, you must logon to the remote computer and, from the MILConfig utility, push the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 29: Distributed MIL.	†				d					i
MIL_TEXT("dmiltcp://[Passkey:]RemoteComputerName[:Port]/MILSystemType") ¹	Allocates a DMIL remote system on a remote or local computer, using the TCP/IP protocol. To allocate a DMIL remote system on a computer, that computer must have a valid DMIL installation. When specifying the string that indicates the remote computer (or local computer for a DMIL server also running locally): If required, replace [Passkey] with the passkey for the remote computer. The passkey is an alphanumeric string of up to 16 characters in length. This passkey is set by the MILConfig utility in the server settings page. If a passkey was not set for the remote computer, omit the passkey and the ":" that follows it. If you are attempting to connect to a local computer, specify the passkey for the DMIL server on the local computer. Replace RemoteComputerName with the remote computer's name or IP address; MIL supports both IPv4 and IPv6 addresses. A typical IPv4 string has the format n.n.n.n, where n is a number between 0 and 255. A typical IPv6 string has the format x:x:x:x:x:x:x:x, where x is a hexadecimal number between 0000 and FFFF. If you are supplying an IPv6 address, you must use square brackets to separate the address from the port. If you are attempting to connect to the local computer, set this to localhost. If required, replace [Port] with the port that the local computer should access on the remote computer to initiate new connections, unless the default connection port is the listening port of the DMIL server on the remote computer; in which case, omit the port number and the ":" that follows it. If you are attempting to connect to a local computer, specify the listening port of the DMIL server on the local computer. Replace MILSystemType with any valid MIL system type listed in this table, such as M_SYSTEM_SOLIOS. The "://" and "/" must be included. Prior to allocating a DMIL remote system, certain conditions must be met. For more information, see Chapter 29: Distributed MIL. (summarize) Allocates a DMIL remote system on a remote or local computer, using the TCP/IP protocol. (more details...)		†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
		MIL system specific
		Note that to allocate a remote GPU or Matrox Orion HD system, the Distributed MIL server cannot be running as a service on the remote computer; you must either set it to run at logon, or start it manually. To set it to run at logon, open the MILConfig utility and select Run at every logon with user credentials in the Server Settings pane, found under the Distributed MIL item. To start it manually, you must logon to the remote computer and, from the MILConfig utility, push the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 29: Distributed MIL.	†				d					i

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

SystemNum INQ

Specifies the number (or rank) of the target board of the specified system type. This parameter can be set to one of the following:

For specifying the number of the target board
Value	Description		MIL system-specific tooltip (†)
M_DEFAULT	Specifies the default board.		†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_DEVn	Specifies the n ^th board of the specified system type. You can set n to one of the following values: 0 <= n <=15. (summarize) Specifies the n ^th board of the specified system type. (more details...)		†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
		MIL system specific
		Note that only M_DEV0 is valid.	†			c												o				s

InitFlag INQ

Specifies the type of initialization to perform on the selected system. This parameter can be set to one of the following.

For specifying the type of initialization setup
Value	Description	MIL system-specific tooltip (†)
M_DEFAULT	Same as M_COMPLETE.	†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_COMPLETE	Specifies to initialize the system completely; the system is initialized to its default state and any required resident software is downloaded. At least one complete initialization is necessary after you power-up your system. (summarize) Specifies to initialize the system completely; the system is initialized to its default state and any required resident software is downloaded. (more details...)	†	a	b	c	d	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_PARTIAL	Specifies to initialize the system to its default state, but it does not download any resident software. M_PARTIAL should only be selected if the required resident software has already been downloaded. This option is particularly useful when debugging since resident software generally needs to be downloaded once after power-up (or rebooting the system) and the downloading process can take a substantial amount of initialization time on certain systems. (summarize) Specifies to initialize the system to its default state, but it does not download any resident software. (more details...)	†				d

SysIdPtr

Specifies the address of the variable in which to write the system identifier. Since the MsysAlloc() function also returns the system identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value

The returned value is the system identifier if the allocation is successful. If allocation fails, M_NULL is returned.

Remark

If you are creating a DLL that includes a call to MsysAlloc(), ensure that the call is not made from the DllMain() function, because MsysAlloc() might load a required DLL and you cannot load a DLL from DllMain(). If necessary, call MsysAlloc() from an initialization function in your DLL instead.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.