PMGuide - How to Use this Book

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))