WinFindAtom

This function finds an atom in the atom table.

Syntax

WinFindAtom(hatomtblAtomTbl, pszAtomName)

Parameters

hatomtblAtomTbl (HATOMTBL) - input: Atom-table handle returned from a previous WinCreateAtomTable or WinQuerySystemAtomTable function.
pszAtomName (PSZ) - input: Atom name, a null terminated character string to be found in the table.; If the string begins with a "#" character, the five ASCII digits that follow are converted into an integer atom.; If the string begins with a "!" character, the next two bytes are interpreted as an atom.; If the high order word of the string is -1, the low order word is an atom.

Returns

atom (ATOM) - returns

Atom value.

Atom: The atom associated with the passed string

0: Invalid atom table handle or invalid atom name specified.

Errors

Possible returns from WinGetLastError

PMERR_INVALID_HATOMTBL (0x1013): An invalid atom-table handle was specified.
PMERR_INVALID_INTEGER_ATOM (0x1016): The specified atom is not a valid integer atom.
PMERR_INVALID_ATOM_NAME (0x1015): An invalid atom name string was passed.
PMERR_ATOM_NAME_NOT_FOUND (0x1017): The specified atom name is not in the atom table.

Remarks

This function is identical to the WinAddAtom function, except that:

If the atom name is not found in the table, it is not added to the table and 0 is returned.
If the atom name is found in the table, the use count is not incremented.

Because integer atoms do not have a use count and do not actually occupy memory in the atom table, this function is identical to WinAddAtom with respect to integer atoms.

Example Code

This example queries an Atom Table for the atom name of a newly created atom "newatom" and then verifies that the atom value returned by the query matches the atom value returned by WinAddAtom.

#define INCL_WINATOM            /* Window Atom Functions        */
#include <os2.h>

ATOM  atom;             /* new atom value                       */
ATOM  atomFound;        /* atom value from WinFindAtom          */
HATOMTBL  hatomtblAtomTbl; /* atom-table handle                 */
char   pszAtomName[10]; /* atom name                            */
ULONG   ulInitial = 0;  /* initial atom table size (use default)*/
ULONG   ulBuckets = 0;  /* size of hash table (use default)     */
BOOL atomMatch = FALSE; /* indicates atom values match          */

/* create atom table of default size */
hatomtblAtomTbl = WinCreateAtomTable(ulInitial, ulBuckets);

/* define name for new atom and add to table */
strcpy(pszAtomName,"newatom");
atom = WinAddAtom(hatomtblAtomTbl, pszAtomName);

atomFound = WinFindAtom(hatomtblAtomTbl, pszAtomName);

/* verify that the atom values match */
if (atom == atomFound)
   atomMatch = TRUE;

Definition

#define INCL_WINATOM /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HATOMTBL    hatomtblAtomTbl;  /*  Atom-table handle. */
PSZ         pszAtomName;      /*  Atom name. */
ATOM        atom;             /*  Atom value. */

atom = WinFindAtom(hatomtblAtomTbl, pszAtomName);

Related Functions