Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
en:docs:fapi:dosallochuge [2021/08/14 10:00] – prokushev | en:docs:fapi:dosallochuge [2021/10/16 14:05] (current) – prokushev | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | {{logos:os2.gif? | + | {{page>en:templates:fapiint}} |
====== DosAllocHuge ====== | ====== DosAllocHuge ====== | ||
Line 7: | Line 8: | ||
===== Syntax ===== | ===== Syntax ===== | ||
- | | + | <code c> |
+ | DosAllocHuge (NumSeg, Size, Selector, MaxNumSeg, AllocFlags) | ||
+ | </ | ||
===== Parameters ===== | ===== 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: | + | |
- | ^ Bit ^ Description ^ | + | |
- | | 15-4 | | + | ^ Bit ^ Description ^ |
- | | 3 | If segment is shared, it can be decreased in size by [[DosReallocHuge]]. | | + | | 15-4 | Reserved and must be set to zero. | |
- | | 2 | Segment may be discarded by the system in low memory situations. | | + | | 3 | If segment is shared, it can be decreased in size by [[DosReallocHuge]]. | |
- | | 1 | Segment is shareable through [[DosGetSeg]]. | | + | | 2 | Segment may be discarded by the system in low memory situations. | |
- | | 0 | Segment is shareable through [[DosGiveSeg]]. | | + | | 1 | Segment is shareable through [[DosGetSeg]]. | |
+ | | 0 | Segment is shareable through [[DosGiveSeg]]. | | ||
+ | |||
+ | <code c> | ||
+ | #define SEG_NONSHARED | ||
+ | #define SEG_GIVEABLE | ||
+ | #define SEG_GETTABLE | ||
+ | #define SEG_DISCARDABLE | ||
+ | </ | ||
===== Return Code ===== | ===== Return Code ===== | ||
- | | + | rc ([[USHORT]]) - return |
Return code descriptions are: | Return code descriptions are: | ||
Line 40: | Line 51: | ||
Each segment of a huge memory allocation has a unique selector. To determine the remaining selectors of a huge memory allocation, issue [[DosGetHugeShift]], | 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 " | + | * 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. | + | * 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, | + | Like single segment memory allocated with [[DosAllocSeg]], huge memory can be designated as shareable by other processes and discardable by the system when no longer needed. Allocating a huge block of memory as discardable automatically locks the memory for use by the caller. When one segment of a huge allocation is discarded by the system, this forces the discard of all the other segments. See DosAllocSeg for more information relating to discardable and shared segments. |
Applications should be discretionary in claiming large memory when doing so can impair system performance. To test system memory availability, | 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, | + | Memory allocated by DosAllocHuge is freed by [[DosFreeSeg]]. One call to [[DosFreeSeg]], passing the selector returned from a DosAllocHuge, |
**Note:** This request may be issued from privilege level 2. However, the segment is allocated as a privilege level 3 segment. | **Note:** This request may be issued from privilege level 2. However, the segment is allocated as a privilege level 3 segment. | ||
- | ===Family API Considerations=== | + | ==== 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: | 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: | ||
Line 59: | Line 71: | ||
* Selector is the actual segment address allocated. | * Selector is the actual segment address allocated. | ||
- | ==Example Code== | + | ===== Example Code ===== |
- | === C Binding=== | + | |
+ | ==== C Binding | ||
+ | <code c> | ||
#define INCL_DOSMEMMGR | #define INCL_DOSMEMMGR | ||
| | ||
Line 74: | Line 88: | ||
| | ||
USHORT | USHORT | ||
+ | </ | ||
- | + | ==== Example | |
- | === 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. | 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 INCL_DOSMEMMGR | ||
| | ||
Line 95: | Line 110: | ||
MAXIMUM_SEG_SIZE, | MAXIMUM_SEG_SIZE, | ||
ALLOC_FLAG); | ALLOC_FLAG); | ||
+ | </ | ||
- | === ASM Binding === | + | ==== MASM Binding |
+ | <code asm> | ||
EXTRN DosAllocHuge: | EXTRN DosAllocHuge: | ||
INCL_DOSMEMMGR | INCL_DOSMEMMGR | ||
Line 109: | Line 126: | ||
| | ||
Returns WORD | Returns WORD | ||
- | + | </ | |
- | ====== Note ====== | + | ===== Note ===== |
Text based on [[http:// | Text based on [[http:// |