View source for WPSProgRef - How to Use this Book

{{WPSProgRef}}
{{IBM-Reprint}}

== How to Use this Book ==
This reference is a detailed technical guide and reference for application programmers. It gives reference information and code examples to enable you to write source code using Workplace classes and methods.

Before you begin to use this information, it would be helpful to understand how you can:
* Expand the Contents to see all available topics
* Obtain additional information for a highlighted word or phrase
* Use action bar choices
* Use the programming information.

=== How to Use the Contents ===
When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign indicates that additional topics are available.

To expand the Contents if you are using a mouse, click on the plus sign. If you are using the keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus (+) key. For example, '''Code Pages''' has a plus sign beside it. To see additional topics for that heading, click on the plus sign or highlight that topic and press the plus (+) key.

To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press the Enter key).

=== How to Obtain Additional Information ===
After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words and phrases are highlighted in green letters, or in white letters on a black background. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information then appears in a window.

=== How to Use Action Bar Choices ===
Several choices are available for managing information presented in the '''Workplace Shell Programming Reference'''. There are three pull-down menus on the action bar: the '''Services''' menu, the '''Options''' menu, and the '''Help''' menu.

The actions that are selectable from the '''Services''' menu operate on the active window currently displayed on the screen. These actions include the following:

'''Bookmark''' Allows you to set a placeholder so you can retrieve information of interest to you.

When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty.

To set a bookmark, do the following:
# Select a topic from the Contents.
# When that topic appears, choose the '''Bookmark''' option from the '''Services''' pull-down.
# If you want to change the name used for the bookmark, type the new name in the field.
# Click on the '''Place''' radio button (or press the Up or Down Arrow key to select it).
# Click on '''OK''' (or select it and press Enter). The bookmark is then added to the bookmark list.

'''Search''' Allows you to find occurrences of a word or phrase in the current topic, selected topics, or all topics.

You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list.

To search for a word or phrase in all topics, do the following:
# Choose the '''Search''' option from the '''Services''' pull-down.
# Type the word or words for which to search.
# Click on '''All sections''' (or press the Up or Down Arrow keys to select it).
# Click on '''Search''' (or select it and press Enter) to begin the search.
# The list of topics where the word or phrase appears is displayed.

'''Print''' Allows you to print one or more topics. You can also print a set of topics by first marking the topics in the Contents list.

To print the document Contents list, do the following:
# Choose '''Print''' from the '''Services''' pull-down.
# Click on '''Contents''' (or press the Up or Down Arrow key to select it).
# Click on '''Print''' (or select it and press Enter).
# The Contents list is printed on your printer.

'''Copy''' Allows you to copy a topic that you are viewing to the System Clipboard or to a file that you can edit. You will find this particularly useful for copying syntax definitions and program samples into the application that you are developing.

You can copy a topic that you are viewing in two ways:
* '''Copy''' copies the topic that you are viewing into the System Clipboard. If you are using a Presentation Manager* editor (for example, the System Editor) that copies or cuts (or both) to the System Clipboard, and pastes to the System Clipboard, you can easily add the copied information to your program source module.
* '''Copy to file''' copies the topic that you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using any editor. You will find TEXT.TMP in the directory where your viewable document resides.

To copy a topic, do the following:
# Expand the Contents list and select a topic.
# When the topic appears, choose '''Copy to file''' from the '''Services''' pull-down.
# The system puts the text pertaining to that topic into the temporary file named TEXT.TMP.

For information on one of the other choices in the '''Services''' pull-down, highlight the choice and press the F1 key.

The actions that are selectable from the '''Options''' menu allow you to change the way your Contents list is displayed. To expand the Contents and show all levels for all topics, choose '''Expand all''' from the '''Options''' pull-down. You can also press the Ctrl and * keys together. For information on one of the other choices in the '''Options''' pull-down, highlight the choice and press the F1 key.

The actions that are selectable from the '''Help''' menu allow you to select different types of help information. You can also press the F1 key for help information about the Information Presentation Facility (IPF).

=== How to Use the Programming Information ===
This document consists of guide and reference information that provides a detailed description of each function, message, constant, and data type. It provides language-dependent information about the functions which enable the user to generate call statements in the C Language.

Workplace Shell programming information is presented by component, such as Workplace Classes, Instance Methods, and Class Methods, for example:
<pre>
     ┌──────────────────────────────┐
     │           Contents           │
     └──────────────────────────────┘
     │                              │
     │ + Workplace Classes          │
     │ + Instance Methods           │
     │ + Class Methods              │
     │                              │
     └──────────────────────────────┘
</pre>

By clicking on the plus sign beside "Instance Methods", you see an alphabetic list of the Workplace Shell instance methods. Selecting an instance method takes you directly into the reference information for that method.

Units of reference information are presented in selectable multiple windows or viewports. A viewport is a Presentation Manager window that can be sized, moved, minimized, maximized, or closed. By selecting a unit (in this case, an entry on the Contents list), you will see two windows displayed:
<pre>
   ┌───────────────────┬─────────────────────────┐
   │Unit Title         │     Selection Title     │
   └───────────────────┴─────────────────────────┘
   │Select an item     │                         │
   │                   │                         │
   │Syntax             │                         │
   │Returns            │                         │
   │Notes              │                         │
   │Related Methods    │                         │
   │Override           │                         │
   │Glossary           │                         │
   │                   │                         │
   └───────────────────┴─────────────────────────┘
</pre>

The window on the left is the primary window. It contains a list of items that are always available to you. The window on the right is the secondary window. It contains a "snapshot" of the unit information. For reference units (that is, function descriptions), this window contains the Function Syntax.

All of the information needed to understand a reference unit (or topic) is readily available to you through the primary window. The information is divided into discrete information groups, and only the appropriate information group appears for the topic that you are viewing.

The information groups for a reference unit (that is, a function description) can include all or some of the following:
* Syntax
* Parameters
* Returns
* Notes
* Related Methods
* Usage
* Override
* Glossary

This list may vary. Some topics may be omitted when they do not apply.

Information groups are displayed in separate viewports that are stacked in a third window location that overlaps the secondary window. By selecting an item (information group) in the primary window, the item is displayed in the third window location, as follows:
<pre>
 ┌───────────────┬────────────┬───────────────┐
 │Unit Title     │  Selection │  Glossary     │
 └───────────────┴────────────┴───────────────┘
 │Select an item │            │Select a starting│
 │               │            │letter of        │
 │   .           │            │glossary terms   │
 │   .           │            │                 │
 │   .           │            │A    N           │
 │   .           │            │B    O           │
 │Glossary       │            │C    P           │
 │               │            │.    .           │
 │               │            │.    .           │
 │               │            │.    .           │
 │               │            │M    Z           │
 └───────────────┴────────────┴───────────────┘
</pre>

By selecting successive items from the primary window, additional windows are displayed on top of the previous windows displayed in the third window location. For example, in a function description, Parameters and Return Values are items listed in the primary window. When selected, they appear one on top of the other in the third window location. Because of this, you may move the first selected (topmost) window to the left before selecting the next item. This allows simultaneous display of two related pieces of information from the "stack" of windows in the third window location, as follows:
<pre>
 ┌───────────────┬─────────────┬──────────────┐
 │Unit Title     │ Parameters  │ Return Values│
 └───────────────┴─────────────┴──────────────┘
 │Select an item │             │              │
 │   .           │             │              │
 │   .           │             │              │
 │   .           │             │              │
 │Returns        │             │              │
 │Errors         │             │              │
 │   .           │             │              │
 │   .           │             │              │
 │   .           │             │              │
 │               │             │              │
 └───────────────┴─────────────┴──────────────┘
</pre>

Each window can be individually closed from its system menu. All windows are closed when you close the primary window.

Some secondary windows may have the appearance of a split screen. For example, an illustration may appear in the left half of the window, and scrollable, explanatory information may appear in the right half of the window. Because illustrations may not necessarily fit into the small window size on your screen, you may maximize the secondary window for better readability.

== Conventions Used in this Reference ==
The purpose of this reference is to give information about classes, methods, constants, and data types. It provides information about the methods which enables the user to call functions in the C programming language.

The following information is provided:
* The syntax and parameters for each method.
* 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 [[#Data_Types|Data Types]], then it is implicitly a pointer to the data type "xxxxxxx". See [[#Implicit_Pointer_Data_Types|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 Method Descriptions ==
The documentation of each function contains these sections:

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

'''Programming Note'''

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

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 [[#Data_Types|Data Types]] for a complete list of all data types and their descriptions.

* There toutes parameter types:
Input Specified by the programmer.
Output Returned by the method.
Input/Output Specified by the programmer and modified by the method.

* 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 is included in this section.

'''Remarks''' This section contains additional information about the method, when required.

'''Related Methods''' This list shows the methods (if any) that are related to the method being described.

'''Usage''' This section describes any restrictions for using the method.

'''Override''' This section describes when the method can be overridden.

== 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 skin to skin contact 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, therefore, 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 reestablish 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.

== Header Files ==
All functions require an "#include" statement for the system header file OS2.H:
<pre>
#include  <OS2.H>
</pre>

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:
<pre>
#define   INCL_name
</pre>

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

== 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, [[#Data_Types|Data Types]], 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:
<pre>
typedef xxxxxx *Pxxxxxx;
</pre>

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.

== Message Queues ==
Usually when an application thread uses a PM function, a message queue must be available for that thread. This means that before calling the function, WinCreateMsgQueue must be called by the same thread.

It is recommended that you create a message queue for every thread that calls any method, since a PM function might be used by the methods you are calling.

== Programming Considerations ==
This section provides information you need to consider before you begin programming with Workplace Shell methods.

=== Method Considerations ===
When including the "OBJECTID=<...>" keyname/value pair in a setup string, it must be specified as the last entry in the string.

=== 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.

=== 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,
<pre>
typedef unsigned char BYTE;
</pre>
has changed to
<pre>
typedef char BYTE;
</pre>

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]]. [[#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|PCSZ]] allows for better optimization by the compiler and is more semantically compatible with C++.

The [[#PCSZ|PCSZ]] data type is defined in addition to the [[#PSZ|PSZ]] data type. Existing code that calls functions that use [[#PSZ|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.