Table of contents -> Chapter 19 - Using the memory handling functions

TEIMSI incorporates functions for memory management, it is important to know that a string object is referenced by a number (handle) which is a 32-bit long integer. A string object is stored internally in a space that the assembler NwMemory function creates, for programming is basically necessary to know the use of the following three functions:

1- NwMemory

2- NwMemoryResize

3- NwMemoryFree_p

The NwMemory function creates a space in memory and returns a handle (that is an integer of 32 bits) used to access the allocated space. Memory functions manage to administer strings with only two operating system functions (GlobalAlloc and GlobalFree in Win.2000/XP/7/...), if a space that exceeds the internal limit available is required, it's used the file system to help rebuild and resize the strings buffer. Also, every call to NwMemory ensures good chances of working if it's not exceeded the limit of available physical memory in the system; otherwise if it fails then it's considered a fatal error: the program displays the error message and exit. It's generally hard to find a program that exceeds that limit.

The following code shows an example of good use of memory functions using only assembler.

_direct{
	call2 NwMemory, 10000
		;	eax now it contains the handle of the 10000 bytes space.

	call2 NwMemoryResize, eax, 1000000, -1		;	It resizes the previously 1000000 bytes allocated space. The -1 indicates that it's not desired to preserve any byte
									;	of the original space (otherwise you must indicate how many bytes will be copied from the original space of 10000 bytes starting from the beginning).

	push eax						;saves "eax" on the stack
		NWPOS_eaxedi				;saves into the 1000000 bytes space the "?" characters
		mov ecx, 1000000
		mov eax, "????"

		mov ebx, ecx
		shr ecx, 2
		and ebx, 3
		rep stosd
		mov ecx, ebx
		rep stosb

	pop  eax						;gets the handle
	call2 NwMemoryFree_p, eax			;it frees the memory space.
}

The function call to NwMemoryFree_p, it may have been replaced by the NwMemoryFree macro, which performs the same thing as the function. Then it will be:

NwMemoryFree eax

Is not necessary to call NwMemory to allocate space with TEIMSI, for that is the "makestring" function, the following example illustrates its use:

	var myspace=makestring(1000000);		//	makestring creates a string with chr(0) repeated one after another.
	_direct{
		mov eax, [myspace+reg.vo]		;	it loads the string's handle
		NWPOS_eaxedi				;	determines the pointer to the string and then stores it into the "edi" register.

		mov ecx, [myspace+reg.nu]		;	loads the string length, =1000000

		mov eax, "????"				;	saved to the same characters "?" repeated a million times.
		mov ebx, ecx
		shr ecx, 2
		and ebx, 3
		rep stosd
		mov ecx, ebx
		rep stosb
	}
	myspace=undefined;				//	frees the string in memory.

The following example above, it's more slowly but with only two instructions:

	var myspace=str_repeatn("?", 1000000)		//	Create string
	myspace=undefined;					//	frees the string in memory.

Other similar to "NWPOS_eaxedi" macro instructions are shown below:

NWPOS_ebxedi ; put in the "edi" register the pointer to the string whose handler is in ebx.

NWPOS_eax ; it stores into the "esi" register the pointer to the string whose handler is in eax.

NWPOS_ebx ; it stores into the "esi" register the pointer to the string whose handler is in ebx.

NWPOS_regarea lparea ; stores into the "esi" register the pointer to the string whose TEIMSI variable structure is located at the "lparea" address

; the utility of the macro is that can be also obtained the pointer to string with static mode.

; for more information about modalities see chapter "TEIMSI Variables".

NWPOS mindex ; puts into the "esi" register the pointer to the string whose handler is in an arbitrary register indicated by "Mindex"

NWLEN mindex ; puts into the "ecx" register the the internal length that has been allocated for the specified string according to the handler it's

; inside an arbitrary register indicated by "Mindex". The internal length is somewhat larger length (usually 256 bytes)

; provided by property of the variable, its role there is for the string handling assembler functions

; in the memory (which in turn perform space optimizations and space reservation for strings).

MACRO NWPOSLEN mindex ; puts into the "esi" register the pointer to the string and puts into the "ecx" register the internal length that is assigned

; to the specified string according to the handler which is in an arbitrary register indicated by "Mindex". (see NWLEN)