Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
en:docs:fapi:dosallochuge [2020/12/04 13:03] – prokushev | en:docs:fapi:dosallochuge [2021/09/16 13:11] – prokushev | ||
---|---|---|---|
Line 5: | Line 5: | ||
This call allocates multiple segments as a huge block of memory. | This call allocates multiple segments as a huge block of memory. | ||
- | ==Syntax== | + | ===== Syntax ===== |
- | | + | |
- | ==Parameters== | + | <code c> |
- | ;NumSeg | + | DosAllocHuge (NumSeg, Size, Selector, MaxNumSeg, AllocFlags) |
- | ;Size (USHORT) - input : Number of bytes to be allocated in the last (non-65536-byte) segment. A value of zero indicates none. | + | </ |
- | ; Selector | + | |
- | ; MaxNumSeg (USHORT) - input : Maximum number of 65536-byte segments this object occupies as a result of any subsequent [[DosReallocHuge]]. If MaxNumSeg | + | |
- | ; AllocFlags | + | |
- | ''' | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | ==Return Code== | + | ===== Parameters ===== |
- | rc (USHORT) - return | + | |
- | Return code descriptions are: | + | |
- | * 0 NO_ERROR | + | |
- | * 8 ERROR_NOT_ENOUGH_MEMORY | + | |
- | * 87 ERROR_INVALID_PARAMETER | + | |
- | * 212 ERROR_LOCKED | + | |
- | ==Remarks== | + | * NumSeg ([[USHORT]]) - input : Number of 65536-byte segments |
- | DosAllocHuge allows a process | + | * Size ([[USHORT]]) - input : Number |
+ | * Selector ([[PSEL]]) - output : Address where the selector | ||
+ | * MaxNumSeg ([[USHORT]]) - input : Maximum number of 65536-byte segments | ||
+ | * AllocFlags ([[USHORT]]) - input : Bit indicators describing the characteristics | ||
- | Each segment of a huge memory allocation has a unique selector. To determine the remaining selectors of a huge memory allocation, issue [[DosGetHugeShift]], | + | ^ Bit ^ Description ^ |
- | * Assume DosAllocHuge is issued with NumSeg equal to 3, and that the number 63 is returned for the selector of the first segment. | + | | 15-4 | Reserved |
- | * If DosGetHugeShift returns a shift count of 4, shifting the value " | + | | 3 | If segment |
- | * 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. | + | | 2 | Segment may be discarded |
- | Like single segment memory allocated with DosAllocSeg, | + | | 1 | Segment |
+ | | 0 | Segment is shareable through [[DosGiveSeg]]. | | ||
- | Applications should be discretionary in claiming large memory when doing so can impair system performance. To test system memory availability, | + | <code c> |
+ | #define SEG_NONSHARED | ||
+ | #define SEG_GIVEABLE | ||
+ | #define SEG_GETTABLE | ||
+ | #define SEG_DISCARDABLE | ||
+ | </ | ||
- | Memory allocated by DosAllocHuge is freed by DosFreeSeg. One call to DosFreeSeg, passing the selector returned from a DosAllocHuge, | + | ===== Return Code ===== |
- | ''' | + | rc ([[USHORT]]) - return |
- | ===Family API Considerations=== | + | Return code descriptions are: |
- | 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== | + | * 0 NO_ERROR |
- | === C Binding=== | + | * 8 ERROR_NOT_ENOUGH_MEMORY |
- | <PRE> | + | * 87 ERROR_INVALID_PARAMETER |
- | #define INCL_DOSMEMMGR | + | * 212 ERROR_LOCKED |
- | USHORT | + | ===== Remarks ===== |
- | USHORT | + | DosAllocHuge allows a process to allocate a large amount |
- | USHORT | + | |
- | PSEL | + | |
- | allocated (returned) */ | + | |
- | USHORT | + | |
- | USHORT | + | |
- | USHORT | + | Each segment of a huge memory allocation has a unique selector. To determine the remaining selectors of a huge memory allocation, issue [[DosGetHugeShift]], |
- | </ | + | |
- | ''' | + | |
- | This example requests | + | * 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 | ||
+ | * 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]], |
- | #define INCL_DOSMEMMGR | + | |
- | #define NUMBER_OF_SEGMENTS 4 | + | Applications should be discretionary in claiming large memory when doing so can impair system performance. To test system memory availability, |
- | #define BYTES_IN_LAST_SEGMENT 1040 | + | |
- | #define MAXIMUM_SEG_SIZE 8 | + | |
- | #define ALLOC_FLAG SEG_GIVEABLE | SEG_DISCARDABLE | + | |
- | SEL Selector; | + | Memory allocated by DosAllocHuge is freed by [[DosFreeSeg]]. One call to [[DosFreeSeg]], |
- | USHORT rc; | + | |
- | rc = DosAllocHuge(NUMBER_OF_SEGMENTS, | + | **Note:** This request may be issued from privilege level 2. However, the segment is allocated |
- | BYTES_IN_LAST_SEGMENT, | + | |
- | & | + | |
- | MAXIMUM_SEG_SIZE, | + | |
- | ALLOC_FLAG); | + | |
- | </ | + | |
- | ===MASM Binding=== | + | ===== Family API Considerations ===== |
- | < | + | |
- | EXTRN DosAllocHuge: | + | |
- | INCL_DOSMEMMGR | + | |
- | PUSH | ||
- | PUSH | ||
- | PUSH@ WORD Selector | ||
- | PUSH | ||
- | PUSH | ||
- | CALL | ||
- | Returns WORD | + | 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: |
- | </PRE> | + | |
+ | * Requested size value is rounded up to the next paragraph (16-byte) | ||
+ | * Selector is the actual segment address allocated. | ||
+ | |||
+ | ===== Example Code ===== | ||
+ | |||
+ | ==== C Binding ==== | ||
+ | |||
+ | <code c> | ||
+ | #define INCL_DOSMEMMGR | ||
+ | | ||
+ | USHORT | ||
+ | | ||
+ | USHORT | ||
+ | USHORT | ||
+ | PSEL | ||
+ | allocated (returned) */ | ||
+ | USHORT | ||
+ | USHORT | ||
+ | | ||
+ | USHORT | ||
+ | </ | ||
+ | |||
+ | ==== Example ==== | ||
+ | |||
+ | 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. | ||
+ | <code c> | ||
+ | #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 ==== | ||
+ | <code asm> | ||
+ | EXTRN DosAllocHuge: | ||
+ | INCL_DOSMEMMGR | ||
+ | | ||
+ | PUSH | ||
+ | PUSH | ||
+ | PUSH@ WORD Selector | ||
+ | PUSH | ||
+ | PUSH | ||
+ | CALL | ||
+ | | ||
+ | Returns WORD | ||
+ | </ | ||
====== Note ====== | ====== Note ====== | ||