WinAddAtom: Difference between revisions
No edit summary |
|||
| Line 7: | Line 7: | ||
;hatomtblAtomTbl (HATOMTBL) - input:Atom-table handle. | ;hatomtblAtomTbl (HATOMTBL) - input:Atom-table handle. | ||
:This is the handle returned by a previous call to [[WinCreateAtomTable]] or [[WinQuerySystemAtomTable]]. | :This is the handle returned by a previous call to [[WinCreateAtomTable]] or [[WinQuerySystemAtomTable]]. | ||
;AtomName (PSZ) - input:Atom name. | ;AtomName ([[PSZ]]) - input:Atom name. | ||
:This is a character string to be added to the table. | :This is a character string to be added to the table. | ||
:If the string begins with an "#" character, the five ASCII digits that follow are converted into an integer atom. If this integer is a valid integer atom, this function returns that atom, without modifying the atom table. | :If the string begins with an "#" character, the five ASCII digits that follow are converted into an integer atom. If this integer is a valid integer atom, this function returns that atom, without modifying the atom table. | ||
Revision as of 03:56, 6 April 2025
This function adds an atom to an atom table.
Syntax
WinAddAtom(hatomtblAtomTbl, AtomName)
Parameters
- hatomtblAtomTbl (HATOMTBL) - input
- Atom-table handle.
- This is the handle returned by a previous call to WinCreateAtomTable or WinQuerySystemAtomTable.
- AtomName (PSZ) - input
- Atom name.
- This is a character string to be added to the table.
- If the string begins with an "#" character, the five ASCII digits that follow are converted into an integer atom. If this integer is a valid integer atom, this function returns that atom, without modifying the atom table.
- If the string begins with an "!" character, the next four bytes are interpreted as an atom. If it is an integer atom, that atom is returned. If it is not an integer atom and it is a valid atom for the given atom table (that is, it has an atom name and use count associated with it) the use count of that atom is incremented by one and the atom is returned. Otherwise 0 is returned.
- If the high order word of the string is minus one, the low order word is an atom. If it is an integer atom, that atom is returned. If it is not an integer atom and it is a valid atom for the given atom table (that is, it has an atom name and use count associated with it) the use count of that atom is incremented by one and the atom is returned. Otherwise 0 is returned.
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.
Sample Code
This example creates an Atom Table and then adds the atom "newatom" to the new table; it then checks the count for this new atom to verify that it is 1.
#define INCL_WINATOM /* Window Atom Functions */ #include <os2.h> ATOM atom; /* new atom value */ 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) */ ULONG ulCount; /* atom usage count */ BOOL atomCount1 = FALSE;/* indicates atom count != 1 */ /* 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); ulCount = WinQueryAtomUsage(hatomtblAtomTbl, atom); /* verify that usage count is 1 */ if (ulCount == 1) atomCount1 = TRUE;