Functions
int	dlmSystem_setFunction (int type, void DLMUserP, int(funcP)())
	Designates a DLM user hook. More...

void	dlmSystem_displayError (WCharCP formatP,...)
	Displays a error message to the same place MicroStation's DLM loader displays errors. More...

void *	dlmSystem_mdlCalloc (size_t arg1, size_t arg2)
	Allocates memory for the specified number of objects of the given size, and associates that memory with the current MDL descriptor. More...

int	dlmSystem_mdlFclose (FILE *fileP)
	Closes the specified file, so that further read/write operations are not allowed. More...

FILE *	dlmSystem_mdlFopen (WCharCP pFileName, WCharCP pFileAccess)
	Opens a file and associates it with an MDL application. More...

void	dlmSystem_mdlFree (void *memoryP)
	Frees memory allocated by dlmSystem_mdlMalloc, dlmSystem_mdlCalloc or dlmSystem_mdlRealloc. More...

FILE *	dlmSystem_mdlFreopen (WCharCP nameP, WCharCP accessP, FILE *fileP)
	Calls freopen and associates the returned file pointer with the current MDL app. More...

void *	dlmSystem_mdlMalloc (size_t size)
	Allocates a block of memory of the specified size in bytes. More...

void *	dlmSystem_mdlRealloc (void *oldBlockP, size_t newSize)
	Reallocates a block of memory to the specified size in bytes. More...

WCharP	dlmSystem_wcsdup (WCharCP pString)
	Duplicates a string saving it in memory it allocated using dlmSystem_mdlMalloc. More...

FILE *	dlmSystem_mdlTmpfile (void)
	Returns a pointer to a temporary file. More...

Detailed Description

Function Documentation

void dlmSystem_displayError	(	WCharCP	formatP,
			...
	)

Displays a error message to the same place MicroStation's DLM loader displays errors.

Normally, this is MicroStation's console window.

Parameters

[in]	formatP	A printf-style format string. It should not include a newline since dlmSystem_displayError appends a newline to every message.
[in]	...	The values to be displayed. dlmSystem_displayError uses formatP to decide how to interpret these arguments.

Remarks: When a load fails, many error messages are typically required to completely explain what happened. The message fields in the Command Window are insufficient for displaying all the error messages. Therefore, load errors are reported with the function dlmSystem_displayError.

void* dlmSystem_mdlCalloc	(	size_t	arg1,
		size_t	arg2
	)

Allocates memory for the specified number of objects of the given size, and associates that memory with the current MDL descriptor.

Parameters

[in]	arg1	the number of objects to be stored in the allocated block of memory
[in]	arg2	the size of one of the objects in bytes

Returns: a pointer to the allocated block of memory, or NULL if the request could not be satisfied.

Remarks: Memory allocated by this function must be freed when it is no longer needed. MicroStation automatically frees the memory when the MDL application is unloaded. It does not automatically free the memory when the DLL is unloaded. The memory is associated with an MDL application, not with a DLL.; Use dlmSystem_mdlFree to explicitly free memory allocated by dlmSystem_mdlCalloc. You cannot use the standard runtime function free to free memory allocated by dlmSystem_mdlCalloc.

See also: dlmSystem_mdlMalloc dlmSystem_mdlFree

int dlmSystem_mdlFclose ( FILE * fileP )

Closes the specified file, so that further read/write operations are not allowed.

Parameters

[in] fileP the file to close

Returns: SUCCESS if the given file points to a file that can be closed.

Remarks: DLM File Functions dlmSystem_mdlFopen, dlmSystem_mdlFclose, dlmSystem_mdlTmpfile and dlmSystem_mdlFreopen have the same parameters and return values as fopen, fclose, tmpfile and freopen. Except for dlmSystem_mdlFclose, which disassociates the pointer, these functions associate the file pointer with the current MDL application. When the application is unloaded, the file is automatically closed. To manipulate files without associating them with the MDL application, use the standard functions fopen, fclose, tmpfile and freopen.

FILE* dlmSystem_mdlFopen	(	WCharCP	pFileName,
		WCharCP	pFileAccess
	)

Opens a file and associates it with an MDL application.

Parameters

[in]	pFileName	the name of the file to be opened
[in]	pFileAccess	a standard fopen-style access string

Returns: the FILE that fopen returns to dlmSystem_mdlFopen. Since dlmSystem_mdlFopen returns the FILE pointer that fopen returns, MDL and native code can use this FILE pointer without concern for how the file was opened.

Remarks: dlmSystem_mdlFopen is merely a layer on top of fopen. dlmSystem_mdlFopen performs an fopen and associates the FILE pointer with the currently active MDL application, and then returns the same FILE pointer as fopen. To avoid problems, files opened with dlmSystem_mdlFopen must always be closed with dlmSystem_mdlFclose. If fclose is used to close a file opened with dlmSystem_mdlFopen, MicroStation will attempt to close the file again when it it unloads the MDL application. The results of this operation will be unpredictable, and a crash may occur. If a DLL needs to open a file that will not be associated with any MDL application, the DLL should call fopen directly.; dlmSystem_fopen provides DLM's access to the same function an MDL program calls when it calls "fopen". This function calls the real "fopen" and then associates the file pointer with the MDL application. When a DLL calls "fopen", it calls the real "fopen" and the file pointer is not associated with any MDL program. There are similar functions for "fclose", and "freopen". Similar functions are not needed for any of the other file IO functions, because the same function is called regardless of whether the function is called from an MDL program or from a DLM. For example, "fread" calls from both DLM's and MDL program result in calls to the real "fread" function.

void dlmSystem_mdlFree ( void * memoryP )

Frees memory allocated by dlmSystem_mdlMalloc, dlmSystem_mdlCalloc or dlmSystem_mdlRealloc.

Parameters

[in] memoryP the block of memory to be freed.

FILE* dlmSystem_mdlFreopen	(	WCharCP	nameP,
		WCharCP	accessP,
		FILE *	fileP
	)

Calls freopen and associates the returned file pointer with the current MDL app.

Parameters

[in]	nameP	the name of the file
[in]	accessP	a file access string that dlmSystem_mdlFreopen will pass to the standard freopen
[in]	fileP	a file pointer for a file that was opened using dlmSystem_mdlFreopen, dlmSystem_mdlFopen, or dlmSystem_mdlTmpfile

Returns: the FILE that freopen returns to dlmSystem_mdlFreopen. Since dlmSystem_mdlFreopen returns the FILE pointer that freopen returns, MDL and native code can use this FILE pointer without concern for how the file was opened.

See also: dlmSystem_mdlFopen

void* dlmSystem_mdlMalloc ( size_t size )

Allocates a block of memory of the specified size in bytes.

Parameters

[in] size the size in bytes of the block to be allocated

Returns: a pointer to the allocated block of memory, or NULL if the request could not be satisfied.

Remarks: Memory allocated by this function must be freed when it is no longer needed. MicroStation automatically frees the memory when the MDL application is unloaded. It does not automatically free the memory when the DLL is unloaded. The memory is associated with an MDL application, not with a DLL.; Use dlmSystem_mdlFree to explicitly free memory allocated by dlmSystem_mdlMalloc. You cannot use the standard runtime function free to free memory allocated by dlmSystem_mdlMalloc.

See also: dlmSystem_mdlCalloc dlmSystem_mdlFree

void* dlmSystem_mdlRealloc	(	void *	oldBlockP,
		size_t	newSize
	)

Reallocates a block of memory to the specified size in bytes.

Parameters

[in]	oldBlockP	a pointer to the block of memory to reallocate. This must point to memory allocated with either dlmSystem_mdlMalloc, dlmSystem_mdlCalloc, dlmSystem_mdlRealloc, or dlmSystem_wcsdup
[in]	newSize	the size to reallocate the block to

Returns: a pointer to the reallocated block

Remarks: Memory allocated by this function must be freed when it is no longer needed. MicroStation automatically frees the memory when the MDL application is unloaded. It does not automatically free the memory when the DLL is unloaded. The memory is associated with an MDL application, not with a DLL.; Use dlmSystem_mdlFree to explicitly free memory allocated by dlmSystem_mdlRealloc. You cannot use the standard runtime function free to free memory allocated by dlmSystem_mdlRealloc.

See also: dlmSystem_mdlCalloc dlmSystem_mdlFree

FILE* dlmSystem_mdlTmpfile ( void )

Returns a pointer to a temporary file.

Returns: a pointer to the file.

Remarks: This creates a temporary file using the standard C function tmpfile and associates it with the current MDL descriptor.

See also: dlmSystem_mdlFclose, dlmSystem_mdlFopen

int dlmSystem_setFunction	(	int	type,
		void *	DLMUserP,
		int(*)()	funcP
	)

Designates a DLM user hook.

MicroStation's MDL interface provides a virtual operating system to MDL applications. One benefit of this is the way MicroStation manages resources for an MDL application. For example, when an MDL application calls malloc MicroStation translates that into a call to dlmSystem_mdlMalloc. dlmSystem_mdlMalloc allocates the requested memory, but it also associates that memory with the MDL application. When MicroStation unloads the application it also frees all of the memory allocated to the application.

A DLL can take advantage of these services by using the dlmSystem_... functions. The developer may do this for the convenience of having MicroStation manage the resources, or he may do it because the DLL is used by MDL applications. Since MicroStation translates an MDL call to free into a call to dlmSystem_mdlFree, an MDL application cannot free memory that a DLL allocates with malloc. If a DLL is going to allocate memory and expect an MDL application to free it, then the DLL must allocate the memory with dlmSystem_mdlMalloc.

dlmSystem_mdlMalloc, dlmSystem_mdlCalloc, dlmSystem_mdlRealloc, dlmSystem_wcsdup, and dlmSystem_mdlFree have the same parameters and return values as their counterparts in the C runtime library. These functions associate the memory with the current MDL application. When that application is unloaded, the memory is automatically freed. To allocate and free memory without associating it with the current MDL application, use malloc, calloc, realloc and free.

dlmSystem_mdlFopen, dlmSystem_mdlFclose, dlmSystem_mdlTmpfile and dlmSystem_mdlFreopen have the same parameters and return values as their counterparts in the C runtime library. Except for dlmSystem_mdlFclose, which disassociates the pointer, these functions associate the file pointer with the current MDL application. When the application is unloaded, the file is automatically closed. To manipulate files without associating them with the MDL application, use the standard functions fopen, fclose, tmpfile and freopen.

The dlmSystem_call.. functions let DLL's call MDL functions. dlmSystem_callMdlFunction lets a DLL call an MDL function. dlmSystem_callMdlFunctionV lets a DLL function that takes a variable argument list call an MDL function passing along the variable argument list. dlmSystem_callAnyFunction lets a DLL invoke a function without caring whether the function is a native code function or an MDL function. All three of these functions switch the current MDL descriptor to the value specified by the mdlDescP argument prior to calling the function, and restore the current MDL descriptor prior to returning.

Parameters

[in]	type	The functionType parameter specifies the type of hook. Valid values are DLM_SYSTEM_MDL_UNLOAD and DLM_SYSTEM_DLM_UNLOAD.
[in]	DLMUserP	identifies the DLM setting up the hook. This value was supplied by MicroStation in the call to the DLMs initialization function.
[in]	funcP	specifies the function to be called when the designated event occurs. A value of NULL cancels the outstanding hook.

Returns: Returns SUCCESS if it was able to set up the hook. Otherwise, it returns ERROR.

WCharP dlmSystem_wcsdup ( WCharCP pString )

Duplicates a string saving it in memory it allocated using dlmSystem_mdlMalloc.

Parameters

[in] pString the string to be duplicated

Remarks: dlmSystem_wcsdup is like wcsdup except that the memory allocated for the saved string is associated with the current MDL application; Memory allocated by this function must be freed when it is no longer needed. MicroStation automatically frees the memory when the MDL application is unloaded. It does not automatically free the memory when the DLL is unloaded. The memory is associated with an MDL application, not with a DLL.; Use dlmSystem_mdlFree to explicitly free memory allocated by dlmSystem_wcsdup. You cannot use the standard runtime function free to free memory allocated by dlmSystem_wcsdup.

Returns: a pointer to the duplicated string

Functions

Detailed Description

Function Documentation