WinQueryAtomName: Difference between revisions

Latest revision as of 03:50, 6 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);

Related Functions

@@ Line 7: / Line 7: @@
 ;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.
+;atom ([[ATOM]]) - input:Identifies the character string to be retrieved.
-;pszBuffer (PSZ) - output:Buffer to receive the character string.
+;pszBuffer ([[PSZ]]) - output:Buffer to receive the character string.
-;ulBufferMax (ULONG) - input:Buffer size in bytes.
+;ulBufferMax ([[ULONG]]) - input:Buffer size in bytes.
 ==Returns==