DOCERR: BUFFER.CREATE Command Not Documented

• Microsoft Win32 Software Development Kit (SDK), version 3.5

SUMMARY

This article documents the BUFFER.CREATE command. This is a command that Microsoft added, so it is not documented in IBM LAN Technical Reference.

MORE INFORMATION

The AcsLan function topic in the Win32 Help file indicates that there are some differences between Windows NT DLC and the CCB2 interface documented in the IBM LAN Technical Reference. The most notable is that the buffer pool must be specified on an open adapter instance basis, not per SAP. After an adapter has been opened by using the DIR.OPEN.ADAPTER command, a buffer pool must be given to the DLC driver by using BUFFER.CREATE.

The IBM LAN Technical Reference manual has no reference to BUFFER.CREATE. However, the DLCAPI.H file contains the following structure with no other information explaining how to use it:

typedef struct {

    HANDLE hBufferPool;                // handle of new buffer pool
    PVOID pBuffer;                     // any buffer in memory
    ULONG cbBufferSize;                // buffer size in bytes
    ULONG cbMinimumSizeThreshold;      // minimum locked size

Unlike DLC as described in IBM LAN Technical Reference, Windows NT DLC does not support a buffer pool per SAP, but rather a buffer pool per process. All buffers given to the application are allocated from the same pool. (You can also allocate send buffers from the buffer pool, but this is not the case in general.)

The application gives the buffer pool to DLC by using the BUFFER.CREATE request. The parameters are:

• hBufferPool: the returned handle of the buffer pool. Supposedly, DLC can share buffer pools between processes but it doesn't, so it's useless.
• pBuffer: the pointer to application allocated buffer pool. This can be allocated by any scheme you wish and can be any size.
• cbBufferSize: the size of pBuffer.
• cbMinimumSizeThreshold: the minimum locked size.

DLC aligns the buffer to a page boundary, discarding any partial page buffer after the last page. This is not a problem unless you allocate a buffer less than a page, or one that is not page-aligned. In these cases, you are in danger of not having a buffer.

Because the buffer must be mapped to system space, DLC needs to lock the buffers into memory when receiving or sending from the buffers. To increase performance, DLC tries to keep a certain amount of buffer locked at all times. It will lock successive pages as the need arises. (In Windows NT, the smallest lockable region is a page.) You can control the initial locked area by setting the cbMinimumSizeThreshold value. If DLC does indeed lock your pages in excess of cbMinimumSizeThreshold, it will try to unlock them as they are freed up.