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);