DosAllocSeg

Bindings:  C, MASM 

This call allocates a segment of memory to a requesting process. 

 DosAllocSeg     (Size, Selector, AllocFlags) 
 

 Size (USHORT) - input 
    Number of bytes requested.  The value specified must be less than or 
    equal to 65535.  A value of zero indicates 65536 bytes. 

 Selector (PSEL) - output 
    Address where the selector of the segment allocated is returned. 

 AllocFlags (USHORT) - input 
    Bit indicators describing the characteristics of the segment being 
    allocated.  The bits that can be set and their meanings are: 

    Bit       Description 
    15-4      Reserved and must be set to zero. 
    3         If segment is shared, it can be decreased in size by 
              DosReallocSeg. 
    2         Segment may be discarded by the system in low memory 
              situations. 
    1         Segment is shareable through DosGetSeg. 
    0         Segment is shareable through DosGiveSeg. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    8         ERROR_NOT_ENOUGH_MEMORY 
    87        ERROR_INVALID_PARAMETER 
 
 Remarks 

 DosAllocSeg allows a process to allocate a data segment up to 64KB in 
 size, which is movable and swappable by the system. If your application 
 needs to accommodate a large data structure that exceeds the 64KB limit, 
 DosAllocHuge may be issued to allocate multiple segments as one huge 
 block of memory. 

 A segment allocated by DosAllocSeg with AllocFlags bit 2 set can be 
 discarded by the system to remedy a low memory situation when the segment 
 is not in use. Upon allocation, a discardable segment is locked and ready 
 for access. The caller issues DosUnlockSeg when it is finished using the 
 segment. The next time the caller needs to access the segment, it must 
 issue DosLockSeg. During the time a segment is locked, it cannot be 
 discarded, but it can still be swapped. 

 Allocate memory as discardable when it is needed to hold data for only 
 short periods of time; for example, saved bit map images for obscured 
 windows. Once the system discards a segment, the caller must reallocate 
 the segment with DosReallocSeg and regenerate the data. Reallocating the 
 segment automatically locks it for the first access.   

 A segment may also be designated as shared with another process. If a 
 process issues DosAllocSeg with AllocFlags bit 0 set, then the segment 
 allocated is shareable through DosGiveSeg. To share the segment in this 
 manner, the owning process can then issue DosGiveSeg to obtain a selector 
 for the sharer to use. The owning process then passes the selector to the 
 sharer using some means of interprocess communication. The sharing 
 process can use the selector to access the shared segment. If the shared 
 segment has been designated discardable (AllocFlags bit 2 is also set), 
 the sharer must issue DosLockSeg to lock the segment. 

 Memory allocated with DosAllocSeg is freed by a call to DosFreeSeg. 

 Note:  This request may be issued from privilege level 2.  However, the 
        segment is allocated as a privilege level 3 segment. 

 
 Family API Considerations 

 Some options operate differently in the DOS mode than in the OS/2 mode. 
  Therefore, the following restrictions apply to DosAllocSeg when coding 
 for the DOS mode: 

 o Requested Size value is rounded up to the next paragraph (16-byte). 
 o Selector is the actual segment address allocated. 
 o AllocFlags must be set to zero.