WinQueryAtomName: Difference between revisions
Created page with "This function returns an atom name associated with an atom. ==Syntax== WinQueryAtomName(hatomtblAtomTbl, atom, pszBuffer, ulBufferMax) ==Parameters== ;hatomtblAtomTbl (HAT..." |
mNo edit summary |
||
| Line 1: | Line 1: | ||
This function returns an atom name associated with an atom. | This function returns an atom name associated with an atom. | ||
==Syntax== | ==Syntax== | ||
| Line 5: | Line 5: | ||
==Parameters== | ==Parameters== | ||
;hatomtblAtomTbl (HATOMTBL) - input | ;hatomtblAtomTbl (HATOMTBL) - input:Atom-table handle. | ||
:Atom-table handle. | :The handle returned from a previous WinCreateAtomTable or WinQuerySystemAtomTable function. | ||
: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== | ==Returns== | ||
;ulretlen (ULONG) - returns | ;ulretlen (ULONG) - returns:Return codes. | ||
:Return codes. | |||
:;Length of retrieved character string. | :;Length of retrieved character string. | ||
:;The specified atom or the atom table is invalid. | :;The specified atom or the atom table is invalid. | ||
:;Other | :;Other | ||
::The number of bytes copied to the buffer excluding the terminating zero. | ::The number of bytes copied to the buffer excluding the terminating zero. | ||
| Line 27: | Line 20: | ||
==Errors== | ==Errors== | ||
Possible returns from WinGetLastError | Possible returns from WinGetLastError | ||
;PMERR_INVALID_HATOMTBL (0x1013) | ;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_ATOM (0x1014) | ;PMERR_INVALID_STRING_PARM (0x100B):The specified string parameter is invalid. | ||
;PMERR_INVALID_STRING_PARM (0x100B) | |||
==Remarks== | ==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. | 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== | ==Example Code== | ||
This function obtains the name of an atom given the atom id. | This function obtains the name of an atom given the atom id. | ||
| Line 48: | Line 40: | ||
atomname, | atomname, | ||
sizeof(atomname)); | sizeof(atomname)); | ||
</pre> | </pre> | ||
Definition | Definition | ||
<pre> | <pre> | ||
| Line 73: | Line 63: | ||
* [[WinQueryAtomLength]] | * [[WinQueryAtomLength]] | ||
* [[WinQueryAtomUsage]] | * [[WinQueryAtomUsage]] | ||
* [[WinQuerySystemAtomTable]] | * [[WinQuerySystemAtomTable]] | ||
[[Category:Win]] | [[Category:Win]] | ||
Revision as of 18:57, 5 April 2025
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);