WinQueryAtomName
This function returns an atom name associated with an atom.
Syntax
WinQueryAtomName(hatomtblAtomTbl, atom, pszBuffer, ulBufferMax)
Parameters
- hatomtblAtomTbl (HATOMTBL) - input
- Atom-table handle.
- The handle returned from a previous WinCreateAtomTable or WinQuerySystemAtomTable function.
- atom (ATOM) - input
- Identifies the character string to be retrieved.
- pszBuffer (PSZ) - output
- Buffer to receive the character string.
- ulBufferMax (ULONG) - input
- Buffer size in bytes.
Returns
- ulretlen (ULONG) - returns
- Return codes.
- Length of retrieved character string.
- The specified atom or the atom table is invalid.
- Other
- The number of bytes copied to the buffer excluding the terminating zero.
Errors
Possible returns from WinGetLastError
- PMERR_INVALID_HATOMTBL (0x1013)
- An invalid atom-table handle was specified.
- PMERR_INVALID_ATOM (0x1014)
- The specified atom does not exist in the atom table.
- PMERR_INVALID_STRING_PARM (0x100B)
- The specified string parameter is invalid.
Remarks
For integer atoms, the format of the string is "#ddddd" where "ddddd" are decimal digits in the system code page (an ASCII code page). No leading zeros are generated, and the length can be from 3 through 7 characters.
Example Code
This function obtains the name of an atom given the atom id.
#define INCL_WINATOM
#include <OS2.H>
HATOMTBL atomtbl;
char atomname[256];
ATOM atom = 25;
WinQueryAtomName(atomtbl,
atom,
atomname,
sizeof(atomname));
Definition
#define INCL_WINATOM /* Or use INCL_WIN, INCL_PM, */ #include <os2.h> HATOMTBL hatomtblAtomTbl; /* Atom-table handle. */ ATOM atom; /* Identifies the character string to be retrieved. */ PSZ pszBuffer; /* Buffer to receive the character string. */ ULONG ulBufferMax; /* Buffer size in bytes. */ ULONG ulretlen; /* Length of retrieved character string. */ ulretlen = WinQueryAtomName(hatomtblAtomTbl, atom, pszBuffer, ulBufferMax);