Service Function 0001h Test Memory Region

les di, Buffer ;points to first byte to be tested

mov cx, Size ;size of buffer, in bytes

mov ax, 0001h ;Test Memory Region

call [Service] ;service-function handler

jc error_handler

mov [Result], ax ;0 = global, 1 = global and local, 2 = local

Test Memory Region (Service Function 0001h) determines whether a given block of memory is global or local in the current session. Local memory is replaced when a session switch occurs.

Client programs and task switchers can call this function. The task switcher corresponding to the specified service-function handler is responsible for processing the function.

Parameters

Buffer

Points to the first byte of memory to be tested.

Size

Specifies the buffer size, in bytes. This value must be in the range 0 through 65,535, where 0 indicates 64K (65,536). Buffers larger than 64K require more than one call to Test Memory Region to test the entire region.

Return Value

If the function is successful, the carry flag is clear and the AX register contains values specifying whether the memory is global or local. This can be one of the following values:

Value Meaning

0000h The buffer is in global memory.
0001h The buffer is in both global and local memory.
0002h The buffer is in local memory.

All other values are reserved.

If the task switcher does not support this function, the carry flag is set.

Comments

The task switcher corresponding to the specified service-function handler determines whether memory is global or local. If more than one task switcher is active, the one that creates a client program's session determines whether its memory is local or global. For this reason, a client program should test its memory region each time it receives the call Query Suspend (Notification Function 0001h) or Session Active (Notification Function 0004h), to determine whether the memory it occupies is global or local relative to the task switcher performing the session switch.

Client programs in global memory can use Test Memory Region to identify requests for asynchronous operations coming from other client programs in global memory. Client programs that service these requests do not have to take special action when a session switch occurs, because a requesting program's buffer and callback address remain accessible even after the session switch.

Since location sometimes affects operation, memory-resident programs can use Test Memory Region to determine whether they are in local or global memory. For example, a communication program in local memory should temporarily shut down before being suspended, but the same program in global memory can continue to run, since a session switch does not affect it.

A task switcher processing Test Memory Region must not enable interrupts or call any MS-DOS system function. Although the task switcher modifies the AX register, it must preserve all other registers.

See Also

Notification Function 0001h Query Suspend
Notification Function 0004h Session Active