PMGuide - How to Use this Book

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

Conventions Used in this Book

The purpose of this reference is to give important information about functions, messages, constants, and data types. It provides language-dependent information about the functions which enables the user to call functions in the C programming language.

The following information is provided:

• The syntax and parameters for each function
• The syntax of each data type and structure

Notation Conventions

The following notation conventions are used in this reference:

NULL

The term NULL applied to a parameter is used to indicate the presence of the pointer parameter, but with no value.

NULLHANDLE

The term NULLHANDLE applied to a parameter is used to indicate the presence of the handle parameter, but with no value.

Implicit Pointer

If no entry for a data type "Pxxxxxxx" is found in then it is implicitly a pointer to the data type "xxxxxxx". See Implicit Pointer Data Types for more information about implicit pointers.

Constant Names

All constants are written in uppercase to match the header files. Where applicable, constant names have a prefix derived from the name of a function, message, or idea associated with the constant. For example:

WM_CREATE Window message
SV_CXICON System value
CF_TEXT Clipboard format.

In this book, references to a complete set of constants with a given prefix is written as shown in the following examples:

Window message WM_*
System value SV_*

Parameters and Fields

Function parameters and data structure fields are shown in italics.

Conventions Used in Function Descriptions

The documentation of each function contains these sections:

Syntax

The function syntax describes the C-language calling syntax of the function and gives a brief description.

Programming Note

The functions in this book are spelled in mixed-case for readability but are known to the system as uppercase character strings. For example, the function "GPIBeginArea" is actually the external name "GPIBEGINAREA".

If you are using a compiler that generates a mixed-case external name, you should code the functions in uppercase.

Parameters

Each parameter is listed with its C-language data type, parameter type, and a brief description.

• All data types are written in uppercase to match the header files. A data type of "Pxxxxxxx" implicitly defines a pointer to the data type "xxxxxxx".

The term NULL applied to a parameter indicates the presence of the parameter, with no value.

Refer to for a complete list of all data types and their descriptions.

• There are three parameter types:

Input - Specified by the programmer.

Output - Returned by the function.

Input/Output - Specified by the programmer and modified by the function.

• A brief description is provided with each parameter. Where appropriate, restrictions are also included. In some cases, the parameter points to a structure.

Returns

A list of possible return codes or errors (when appropriate) is included in this section. Some functions do not have return codes. Refer to for a list of error codes and their numerical values, and for a list of error codes and their descriptions.

For some functions, this section includes a statement that the function requires a message queue. This means that, before issuing a call, WinCreateMsgQueue must be issued by the same thread. For other functions, no previous WinCreateMsgQueue is required, and it is only necessary to issue WinInitialize from the same thread.

Remarks

This section contains additional information about the function, when required.

Related Functions

This list shows the functions (if any) that are related to the function being described.

Example Code

An example of how the function can be used is shown in C language.

Error Severities

Each of the error conditions given in the list of errors for each function falls into one of these areas:

Warning

The function detected a problem, but took some remedial action that enabled the function to complete successfully. The return code in this case indicates that the function completed successfully.

Error

The function detected a problem for which it could not take any sensible remedial action. The system has recovered from the problem, and the state of the system, with respect to the application, remains the same as at the time when the function was requested. The system has not even partially executed the function (other than reporting the error).

Severe Error

The function detected a problem from which the system could not reestablish its state, with respect to the application, at the time when that function was requested; that is, the system partially executed the function. This necessitates the application performing some corrective activity to restore the system to some known state.

Unrecoverable Error

The function detected some problem from which the system could not re-establish its state, with respect to the application, at the time when that call was issued. It is possible that the application cannot perform some corrective action to restore the system to some known state.

The WinGetLastError and WinGetErrorInfo functions can be used to find out more about an error (or warning) that occurs as a result of executing a call.

Header Files

All functions require an "#include" statement for the system header file OS2.H:

#include  <OS2.H>

Most functions also require a "#define" statement to select an appropriate (conditional) section of the header file, and hence, the required prototype. Where this is necessary, it is shown at the head of the function definition in the form:

#define   INCL_name

Note: These "#define" statements must precede the "#include <OS2.H>" statement.

Helper Macros

A series of macros is defined for packing data into, and extracting data from, variables of MPARAM and MRESULT data types. They are used in conjunction with the WinSendMsg and the other message functions, and also inside window and dialog procedures.

These macros always cast their arguments to the specified type, so values of any of the types specified for each macro can be passed without additional casting. NULL can be used to pass unused parameter data.

Macros for packing data into a MPARAM variable are shown below:

/* Used to pass any pointer type: */
#define MPFROMP(p)            ((MPARAM)(VOID *)(p))

/* Used to pass a window handle: */
#define MPFROMHWND(hwnd)      ((MPARAM)(HWND)(hwnd))

/* Used to pass a CHAR, UCHAR, or BYTE: */
#define MPFROMCHAR(ch)        ((MPARAM)(USHORT)(ch))

/* Used to pass a LONG, ULONG, or BOOL: */
#define MPFROMLONG(l)        ((MPARAM)(ULONG)(l))

/* Used to pass two SHORTs or USHORTs: */
#define MPFROM2SHORT(s1, s2)  ((MPARAM)MAKELONG(s1, s2))

/* Used to pass a SHORT and 2 UCHARs: (WM_CHAR msg)*/
#define MPFROMSH2CH(s, uch1, uch2)
 ((MPARAM)MAKELONG(s, MAKESHORT(uch1, uch2)))

Macros for extracting data from a MPARAM variable are shown below:

/* Used to get any pointer type: */
#define PVOIDFROMMP(mp)     ((VOID *)(mp))

/* Used to get a window handle: */
#define HWNDFROMMP(mp)      ((HWND)(mp))

/* Used to get CHAR, UCHAR, or BYTE: */
#define CHAR1FROMMP(mp)     ((UCHAR)(mp))
#define CHAR2FROMMP(mp)     ((UCHAR)((ULONG)mp >> 8))
#define CHAR3FROMMP(mp)     ((UCHAR)((ULONG)mp >> 16))
#define CHAR4FROMMP(mp)     ((UCHAR)((ULONG)mp >> 24))

/* Used to get a LONG, ULONG, or BOOL: */
#define LONGFROMMP(mp)    ((ULONG)(mp))

Macros for packing data into a MRESULT variable are shown below:

/* Used to pass any pointer type: */
#define MRFROMP(p)            ((MRESULT)(VOID *)(p))

/* Used to pass a LONG, ULONG, or BOOL: */
#define MRFROMLONG(l)        ((MRESULT)(ULONG)(l))

/* Used to pass two SHORTs or USHORTs: */
#define MRFROM2SHORT(s1, s2)  ((MRESULT)MAKELONG(s1, s2))

Macros for extracting data from a MRESULT variable are shown below:

/* Used to get any pointer type: */
#define PVOIDFROMMR(mr)     ((VOID *)(mr))

/* Used to get a LONG, ULONG, or BOOL: */
#define LONGFROMMR(mr)    ((ULONG)(mr))

The following macros are for use with DDESTRUCT and DDEINIT structures are shown below:

/* Used to return a PSZ pointing to the DDE item name: */
#define DDES_PSZITEMNAME(pddes) \
        (((PSZ)pddes) + ((PDDESTRUCT)pddes)->offszItemName)

/* Used to return a PBYTE pointing to the DDE data: */
#define DDES_PABDATA(pddes)       \
        (((PBYTE)pddes) + ((PDDESTRUCT)pddes)->offabData)

/* Used to convert a selector to a PDDESTRUCT: */
#define SELTOPDDES(sel)             ((PDDESTRUCT)MAKEP(sel, 0))

/* Used to PDDESTRUCT to a selector for freeing / reallocating: */
#define PDDESTOSEL(pddes)           (SELECTOROF(pddes))

/* Used to PDDEINIT to a selector for freeing: */
#define PDDEITOSEL(pddei)           (SELECTOROF(pddei))

Addressing Elements in Arrays

Constants defining array elements are given values that are zero-based in C; that is, the numbering of the array elements starts at zero, not one.

For example, in the DevQueryCaps function, the sixth element of the alArray parameter is CAPS_HEIGHT, which is equated to 5.

Count parameters related to such arrays always mean the actual number of elements available; therefore, again using the DevQueryCaps function as an example, if all elements up to and including CAPS_HEIGHT are provided for, lCount could be set to (CAPS_HEIGHT+1).

In functions for which the starting array element can be specified, this is always zero-based, and so the C element number constants can be used directly. For example, to start with the CAPS_HEIGHT element, the lStart parameter can be set to CAPS_HEIGHT.

Implicit Pointer Data Types

A data type name beginning with "P" (for example, PERRORCODE) is likely to be a pointer to another data type (in this instance, ERRORCODE).

In the data type summary, no explicit "typedefs" are shown for pointers; therefore, if no data type definition can be found in the summary for a data type name "Pxxxxxx", it represents a pointer to the data type "xxxxxx", for which a definition should be found in the reference.

The implicit type definition needed for such a pointer "Pxxxxxx" is:

typedef xxxxxx *Pxxxxxx;

Such definitions are provided in the header files.

Storage Mapping of Data Types

The storage mapping of the data types is dependent on the machine architecture. To be portable, applications must access the data types using the definitions supplied for the environment in which they will execute.

Double-Byte Character Set (DBCS)

Throughout this publication, you will see references to specific value for character strings. The values are for single-byte character set (SBCS). If you use the double-byte character set (DBCS), note that one DBCS character equals two SBCS characters.

Programming Considerations

This section provides information you need to consider before you begin programming with Presentation Manager functions.

Stack Size

Existing 16-bit applications (small and tiny models) must have a 4KB stack available when they enter system calls; otherwise, the stack can overflow into the data area.

Presentation Manager

The Presentation Manager component of the OS/2 operating system is based on the IBM Systems Application Architecture (SAA) Common Programming Interface-a an architecture for the design and development of applications.

The Presentation Manager component implements the Common User Access (CUA) interface, which you can use to attain consistency in the appearance and behavior of your applications.

C++ Considerations

This section contains several topics you should take into consideration if you are using C++ to develop applications.

A Few Words on Typedefs

The OS/2 header files can be used with either C or C++ compilers. If __cplusplus has been defined, the header files will produce code that is compatible with C++. This is done since several of the typedefs have been changed to support C++. For example, many items that are unsigned char in the "C header files" are char when compiled with __cplusplus. For instance,

typedef unsigned char BYTE;

has changed to

typedef char BYTE;

The existing samples that are included in the IBM Developer's Toolkit for OS/2 Warp Version 3 can be compiled with either C or C++.

Note: Prior versions of the IBM Developer's Toolkit for OS/2 Warp Version 3 provided two sets of header files: one set for use with C compilers, another set for use with C++ compilers. The same set of header files are now used by either compiler.

PCSZ Data Type

If a function takes as a parameter a string that is not changed by the function, the string parameter can be declared as a "const" string, or a PCSZ. PCSZ is defined in the header files as a "const" pointer to a NULL-delimited string.

The "const" means that the function will not change the contents of the string. The use of the "const" keyword is not specific to C++, many C compilers support it as well. However, the use of PCSZ allows for better optimization by the compiler and is more semantically compatible with C++.

The PCSZ data type is defined in addition to the PSZ data type. Existing code that calls functions that use PSZ will continue to work correctly, though they may cause warning or error messages when compiled.

LINK386

The C++ compiler will provide a dynamic link library which is be used by LINK386, or other OS/2 linker, when generating error messages. This DLL will convert a compiler generated mangled name into the function prototype. If the DLL is not present, an error message will be displayed and LINK386 will display the compiler-generated mangled name in error messages.