8. Descriptor Management Services, Continued

8.1 Allocate Descriptors

This function is used to allocate one or more descriptors from the current Descriptor Table (GDT or LDT). The descriptor(s) allocated must be initialized by the application.

Availability:

To Call:

     AX = 0000h
     CX = Number of descriptors to allocate

Returns:

     If function was successful:
     Carry flag is clear.
     AX = Base selector

     If function was not successful:
     Carry flag is set.

Programmer's Notes:

• Since this function involves descriptor management, it will be rarely needed in 32-bit programs.

• The hardware limits you to 8,189 descriptors possible to obtain with this function.

  When running under DOS/4G or DOS/4GW (or any DOS extender) under various versions of Windows, you may be able to allocate around 1,600 descriptors.

  When running under DOS/4G or DOS/4GW under plain DOS, you will be able to allocate about 2,000 descriptors, since the default GDT size is 1/4 of a full GDT.

• If more than one descriptor was requested, AX will contain the first of a contiguous array of descriptors. You should add the value returned by function 0003h (Get Next Selector Increment Value) to get to the next selector in the array.

• The descriptor will be set to present data type, with a base and limit of zero.

• It is up to the caller to fill in the descriptors.

• The privilege level of descriptors will match the application's code segment privilege level. When modifying descriptors, always set the DPL to the same privilege ring as your program's code segment. Use the lar instruction to determine the privilege of a descriptor.

Code Sample:

The following function compiles with Watcom C/C++ version 11.0 or later, and Microsoft Visual C/C++ version 4.0 or later:

// allocate one or more descriptors

int dpmiAllocateDescriptors(short num,	// how many descriptors wanted
			unsigned short *pSel)	// (returned) first selector allocated
	{
	int result;			// zero if int 31h succeeds
	unsigned short errorCode;	// error code from DPMI host

	__asm {
		mov	cx, num		// the number of descriptors we want

		mov	eax, 0x000	// call dpmi host to do allocation
		int	0x31

		mov	errorCode, ax	// save error code from DPMI, if any

		sbb	eax, eax	// record success/failure flag
		mov	result, eax
		}

	// if the dpmi call failed, return the dpmi error code
	if (result != 0)
		return errorCode;

	// otherwise, set the base selector, which was stored in errorCode
	*pSel = errorCode;

	// indicate success
	return 0;
	}