no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
Next revision | |||
— | en:docs:fapi:dosallochuge [2018/08/30 17:04] – created prokushev | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | |||
+ | This call allocates multiple segments as a huge block of memory. | ||
+ | |||
+ | ==Syntax== | ||
+ | | ||
+ | |||
+ | ==Parameters== | ||
+ | ;NumSeg (USHORT) - input : Number of 65536-byte segments to be allocated. | ||
+ | ;Size (USHORT) - input : Number of bytes to be allocated in the last (non-65536-byte) segment. A value of zero indicates none. | ||
+ | ; Selector (PSEL) - output : Address where the selector of the first segment allocated is returned. | ||
+ | ; MaxNumSeg (USHORT) - input : Maximum number of 65536-byte segments this object occupies as a result of any subsequent [[DosReallocHuge]]. If MaxNumSeg is 0, OS/2 assumes this segment will never be increased by DosReallocHuge beyond its original size, though it may be decreased. This value is ignored in the DOS mode. | ||
+ | ; AllocFlags (USHORT) - input : Bit indicators describing the characteristics of the segment allocated. The bits that can be set and their meanings are: | ||
+ | ''' | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | |||
+ | ==Return Code== | ||
+ | rc (USHORT) - return | ||
+ | Return code descriptions are: | ||
+ | * 0 NO_ERROR | ||
+ | * 8 ERROR_NOT_ENOUGH_MEMORY | ||
+ | * 87 ERROR_INVALID_PARAMETER | ||
+ | * 212 ERROR_LOCKED | ||
+ | |||
+ | ==Remarks== | ||
+ | DosAllocHuge allows a process to allocate a large amount of memory by telling the system how many 64KB segments it needs and whether it requires an additional partial segment. The system allocates the memory, which is movable and swappable, and returns a selector to the first segment. When this selector is used with a call, the requested function is performed for the entire block of memory. | ||
+ | |||
+ | Each segment of a huge memory allocation has a unique selector. To determine the remaining selectors of a huge memory allocation, issue [[DosGetHugeShift]], | ||
+ | * Assume DosAllocHuge is issued with NumSeg equal to 3, and that the number 63 is returned for the selector of the first segment. | ||
+ | * If DosGetHugeShift returns a shift count of 4, shifting the value " | ||
+ | * Adding this increment to selector number 63 produces 79 for the second selector. Adding the same increment to selector number 79 yields 95 for the third selector. | ||
+ | Like single segment memory allocated with DosAllocSeg, | ||
+ | |||
+ | Applications should be discretionary in claiming large memory when doing so can impair system performance. To test system memory availability, | ||
+ | |||
+ | Memory allocated by DosAllocHuge is freed by DosFreeSeg. One call to DosFreeSeg, passing the selector returned from a DosAllocHuge, | ||
+ | |||
+ | ''' | ||
+ | |||
+ | ===Family API Considerations=== | ||
+ | Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following considerations apply to DosAllocHuge when coding for the DOS mode: | ||
+ | * Requested size value is rounded up to the next paragraph (16-byte) | ||
+ | * Selector is the actual segment address allocated. | ||
+ | |||
+ | ==Example Code== | ||
+ | === C Binding=== | ||
+ | <PRE> | ||
+ | #define INCL_DOSMEMMGR | ||
+ | |||
+ | USHORT | ||
+ | |||
+ | USHORT | ||
+ | USHORT | ||
+ | PSEL | ||
+ | allocated (returned) */ | ||
+ | USHORT | ||
+ | USHORT | ||
+ | |||
+ | USHORT | ||
+ | </ | ||
+ | ''' | ||
+ | |||
+ | This example requests a block of memory with 4 segments, the last segment having 1,040 bytes. The block of memory will never be larger than 8 segments. The memory can be shared with DosGiveSeg API calls. The system can discard the memory if it needs too. | ||
+ | |||
+ | <PRE> | ||
+ | #define INCL_DOSMEMMGR | ||
+ | |||
+ | #define NUMBER_OF_SEGMENTS 4 | ||
+ | #define BYTES_IN_LAST_SEGMENT 1040 | ||
+ | #define MAXIMUM_SEG_SIZE 8 | ||
+ | #define ALLOC_FLAG SEG_GIVEABLE | SEG_DISCARDABLE | ||
+ | |||
+ | SEL Selector; | ||
+ | USHORT rc; | ||
+ | |||
+ | rc = DosAllocHuge(NUMBER_OF_SEGMENTS, | ||
+ | BYTES_IN_LAST_SEGMENT, | ||
+ | & | ||
+ | MAXIMUM_SEG_SIZE, | ||
+ | ALLOC_FLAG); | ||
+ | </ | ||
+ | |||
+ | ===MASM Binding=== | ||
+ | <PRE> | ||
+ | EXTRN DosAllocHuge: | ||
+ | INCL_DOSMEMMGR | ||
+ | |||
+ | PUSH | ||
+ | PUSH | ||
+ | PUSH@ WORD Selector | ||
+ | PUSH | ||
+ | PUSH | ||
+ | CALL | ||
+ | |||
+ | Returns WORD | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ====== Note ====== | ||
+ | |||
+ | Text based on [[http:// | ||
+ | |||
+ | {{page> | ||
+ | |||