WinCreateAtomTable
This function creates a private empty atom table.
Syntax
WinCreateAtomTable(ulInitial, ulBuckets);
Parameters
- ulInitial (ULONG) - input
- Initial bytes.
- This parameter is ignored for version 3, or higher, of the OS/2 operating system. The ulInitial parameter is dynamically allocated. The initial number of bytes should be set to zero.
- For versions prior to version 3 of the OS/2 operating system, this parameter is the initial number of bytes to be reserved for the atom table. This is a lower bound on the amount of memory reserved. The amount of memory actually used by an atom table depends upon the actual number of atoms stored in the table. If zero, the size of the atom table is the minimum size needed to store the atom hash table. The minimum size of atom table allocated is 16+(2*ulBuckets).
- ulBuckets (ULONG) - input
- Size of the hash table.
- Used to access atoms. If zero, the default value of 37 is used. The best results are achieved if a prime number is used.
Returns
- hatomtblAtomTbl (HATOMTBL) - returns
- Atom-table handle.
- NULLHANDLE
- Call failed.
- Other
- Atom-table handle. This must be passed as a parameter in subsequent atom manager calls.
Remarks
The atom table is owned by the process from which this function is issued. It cannot be accessed directly from any other process. If it is still in existence when the process terminates, it will automatically be deleted by the system.
There is a system atom table which is created at boot time, which cannot be destroyed, and which can be accessed by any process in the system. The handle of the system atom table is queried with the WinQuerySystemAtomTable function.
Example Code
This example creates an Atom Table of default size, adds the atom "newatom" to the new table, and then destroys the table.
#define INCL_WINATOM /* Window Atom functions */ #include <os2.h> ATOM atom; /* New atom value */ HATOMTBL hatomtblAtomTbl; /* Atom-table handle */ HATOMTBL hatomtblDestroy; /* Result of destroy table */ char pszAtomName[10]; /* Atom name */ ULONG ulInitial = 0; /* Initial atom table size (use default) */ ULONG ulBuckets = 0; /* Size of hash table (use default) */ /* Create an atom table of the default size */ hatomtblAtomTbl = WinCreateAtomTable(ulInitial, ulBuckets); /* Define the name of the new atom and add it to the table */ strcpy(pszAtomName,"newatom"); atom = WinAddAtom(hatomtblAtomTbl, pszAtomName); hatomtblDestroy = WinDestroyAtomTable(hatomtblAtomTbl);
Definition
#define INCL_WINATOM /* Or use INCL_WIN, INCL_PM, */ #include <os2.h> ULONG ulInitial; /* Initial bytes. */ ULONG ulBuckets; /* Size of the hash table. */ HATOMTBL hatomtblAtomTbl; /* Atom-table handle. */ hatomtblAtomTbl = WinCreateAtomTable(ulInitial, ulBuckets);