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/09/14 14:17] – 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 13: | Line 14: | ||
===== Parameters ===== | ===== Parameters ===== | ||
- | * NumSeg (USHORT) - input : Number of 65536-byte segments to be allocated. | + | * 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. | + | * 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. | + | * 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. | + | * 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: | + | * AllocFlags ([[USHORT]]) - input : Bit indicators describing the characteristics of the segment allocated. The bits that can be set and their meanings are: |
- | ^ Bit ^ Description ^ | + | ^ Bit ^ Description ^ |
- | | 15-4 | | + | | 15-4 | Reserved and must be set to zero. | |
- | | 3 | If segment is shared, it can be decreased in size by [[DosReallocHuge]]. | | + | | 3 | If segment is shared, it can be decreased in size by [[DosReallocHuge]]. | |
- | | 2 | Segment may be discarded by the system in low memory situations. | | + | | 2 | Segment may be discarded by the system in low memory situations. | |
- | | 1 | Segment is shareable through [[DosGetSeg]]. | | + | | 1 | Segment is shareable through [[DosGetSeg]]. | |
- | | 0 | Segment is shareable through [[DosGiveSeg]]. | | + | | 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 44: | Line 52: | ||
* Assume DosAllocHuge is issued with NumSeg equal to 3, and that the number 63 is returned for the selector of the first segment. | * 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 62: | 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> | <code c> | ||
Line 80: | Line 90: | ||
</ | </ | ||
- | === 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. | ||
Line 102: | Line 112: | ||
</ | </ | ||
- | === ASM Binding === | + | ==== MASM Binding ==== |
<code asm> | <code asm> | ||
EXTRN DosAllocHuge: | EXTRN DosAllocHuge: | ||
Line 116: | Line 127: | ||
Returns WORD | Returns WORD | ||
</ | </ | ||
- | ====== Note ====== | + | ===== Note ===== |
Text based on [[http:// | Text based on [[http:// |