OS/2 Shareware BBS: 10 Tools/10-Tools.zip/VSCPPv4.zip/VACPP/IBMCPP/HELP/GPI1.INF

OS/2 Help File | 1995-03-14 | 24KB | 671 lines

ΓòÉΓòÉΓòÉ 1. Notices ΓòÉΓòÉΓòÉ

First Edition (October 1994)

The following paragraph does not apply to the United Kingdom or any country
where such provisions are inconsistent with local law:  INTERNATIONAL BUSINESS
MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states
do not allow disclaimer of express or implied warranties in certain
transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time.

It is possible that this publication may contain reference to, or information
about, IBM products (machines and programs), programming, or services that are
not announced in your country.  Such references or information must not be
construed to mean that IBM intends to announce such IBM products, programming,
or services in your country.

Requests for technical information about IBM products should be made to your
IBM authorized reseller or IBM marketing representative.


ΓòÉΓòÉΓòÉ 1.1. Copyright Notices ΓòÉΓòÉΓòÉ

COPYRIGHT LICENSE: This publication contains printed sample application
programs in source language, which illustrate OS/2 programming techniques. You
may copy, modify, and distribute these sample programs in any form without
payment to IBM, for the purposes of developing, using, marketing or
distributing application programs conforming to the OS/2 application
programming interface.

Each copy of any portion of these sample programs or any derivative work, which
is distributed to others, must include a copyright notice as follows: "(C)
(your company name) (year).  All rights reserved."

(C) Copyright International Business Machines Corporation 1994. All rights
reserved.
Note to U.S. Government Users - Documentation related to restricted rights -
Use, duplication or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.


ΓòÉΓòÉΓòÉ 1.2. Disclaimers ΓòÉΓòÉΓòÉ

References in this publication to IBM products, programs, or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program or service is not intended
to state or imply that only IBM's product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe any
of IBM's intellectual property rights or other legally protectable rights may
be used instead of the IBM product, program, or service. Evaluation and
verification of operation in conjunction with other products, programs, or
services, except those expressly designated by IBM, are the user's
responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to the IBM Director
of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A.


ΓòÉΓòÉΓòÉ 1.3. Trademarks ΓòÉΓòÉΓòÉ

The following terms are trademarks of the IBM Corporation in the United States
or other countries:

IBM
PM
Presentation Manager
OS/2
SAA
System Application Architecture
Workplace Shell

The following terms are trademarks of other companies:

 C++                 AT&T, Inc.
 Helvetica           Linotype


ΓòÉΓòÉΓòÉ 1.4. 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.


ΓòÉΓòÉΓòÉ 2. How to Use the GPI Guide and Reference ΓòÉΓòÉΓòÉ

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 Graphical Programming Interface functions.

Before you begin to use this information, it would be helpful to understand how
you can:

   o  Expand the Contents to see all available topics
   o  Obtain additional information for a highlighted word or phrase
   o  Use action bar choices
   o  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
 Graphics Programming Interface 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:

   1. Select a topic from the Contents.

   2. When that topic appears, choose the Bookmark option from the Services
      pull-down.

   3. If you want to change the name used for the bookmark, type the new name
      in the field.

   4. Click on the Place radio button (or press the Up or Down Arrow key to
      select it).

   5. 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:

   1. Choose the Search option from the Services pull-down.

   2. Type the word or words to be searched for.

   3. Click on All sections (or press the Up or Down Arrow keys to select it).

   4. Click on Search (or select it and press Enter) to begin the search.

   5. 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:

   1. Choose Print from the Services pull-down.

   2. Click on Contents (or press the Up or Down Arrow key to select it).

   3. Click on Print (or select it and press Enter).

   4. 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:

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

   o  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:

        1. Expand the Contents list and select a topic.

        2. When the topic appears, choose Copy to file from the Services
           pull-down.

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

 Graphical Programming Interface programming information is presented by
 component, such as Graphics Functions, Graphics Orders, and Data Types, for
 example:

       ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
       Γöé            Contents                     Γöé
       Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
       Γöé                                         Γöé
       Γöé  + Graphics Functions                   Γöé
       Γöé  + Graphics Orders                      Γöé
       Γöé  + Data Types                           Γöé
       Γöé                                         Γöé
       ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 By clicking on the plus sign beside "Graphics Functions", you see an
 alphabetic list of the Graphical Programming Interface functions. Selecting a
 function takes you directly into the reference information for that function.

 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:

     ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
     Γöé Unit Title         Γöé      Selection Title     Γöé
     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
     Γöé Select an item     Γöé                          Γöé
     Γöé                    Γöé                          Γöé
     Γöé Syntax             Γöé                          Γöé
     Γöé Returns            Γöé                          Γöé
     Γöé Notes              Γöé                          Γöé
     Γöé Example Code       Γöé                          Γöé
     Γöé Related Functions  Γöé                          Γöé
     Γöé Glossary           Γöé                          Γöé
     Γöé                    Γöé                          Γöé
     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 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:

   o  Syntax
   o  Parameters
   o  Returns
   o  Errors
   o  Notes
   o  Example Code
   o  Related Functions
   o  Graphic Elements and Orders
   o  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:

   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
   Γöé Unit Title     Γöé   Selection Γöé   Glossary       Γöé
   Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
   Γöé Select an item Γöé             Γöé Select a startingΓöé
   Γöé                Γöé             Γöé letter of        Γöé
   Γöé    .           Γöé             Γöé glossary terms   Γöé
   Γöé    .           Γöé             Γöé                  Γöé
   Γöé    .           Γöé             Γöé A    N           Γöé
   Γöé    .           Γöé             Γöé B    O           Γöé
   Γöé    .           Γöé             Γöé C    P           Γöé
   Γöé Glossary       Γöé             Γöé .    .           Γöé
   Γöé                Γöé             Γöé .    .           Γöé
   Γöé                Γöé             Γöé .    .           Γöé
   Γöé                Γöé             Γöé M    Z           Γöé
   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 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:

   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
   Γöé Unit Title     Γöé  Parameters  Γöé  Return Values  Γöé
   Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
   Γöé Select an item Γöé              Γöé                 Γöé
   Γöé    .           Γöé              Γöé                 Γöé
   Γöé    .           Γöé              Γöé                 Γöé
   Γöé    .           Γöé              Γöé                 Γöé
   Γöé Returns        Γöé              Γöé                 Γöé
   Γöé Errors         Γöé              Γöé                 Γöé
   Γöé    .           Γöé              Γöé                 Γöé
   Γöé    .           Γöé              Γöé                 Γöé
   Γöé    .           Γöé              Γöé                 Γöé
   Γöé                Γöé              Γöé                 Γöé
   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

 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.


ΓòÉΓòÉΓòÉ 2.1. Conventions Used in this Reference ΓòÉΓòÉΓòÉ

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

The following information is provided:

   o  The syntax and parameters for each function.
   o  The syntax of each data type and structure


ΓòÉΓòÉΓòÉ 2.2. 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, 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 reference, references to a complete set of
                       constants with the same 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.


ΓòÉΓòÉΓòÉ 2.3. Conventions Used in Function Descriptions ΓòÉΓòÉΓòÉ

The documentation of each function contains the following 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.

   o  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 for a complete list of all data types and their
      descriptions.

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

   o  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 Error
      Number and Name for a list of error codes and their numerical values, and
      Error Name and Explanation for a list of error codes and their
      descriptions.

 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.


ΓòÉΓòÉΓòÉ 2.4. 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.


ΓòÉΓòÉΓòÉ 2.5. 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.


ΓòÉΓòÉΓòÉ 2.6. 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 DevQueryCaps parameter
can be set to CAPS_HEIGHT.


ΓòÉΓòÉΓòÉ 2.7. 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, 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. OS2.H.


ΓòÉΓòÉΓòÉ 2.8. 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.


ΓòÉΓòÉΓòÉ 2.9. 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.


ΓòÉΓòÉΓòÉ 2.10. Programming Considerations ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 2.10.1. 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.


ΓòÉΓòÉΓòÉ 2.10.2. 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.


ΓòÉΓòÉΓòÉ 2.10.3. C++ Considerations ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 2.10.3.1. C++ Header Files ΓòÉΓòÉΓòÉ

OS/2 functions that used to take a PSZ as a parameter, and that do not modify
the contents of the passed string, have been updated in the C++ header files to
take a PCSZ data type parameter. The use of PCSZ allows for better optimization
by the compiler and is more semantically compatible with C++. Existing code
that calls functions that use PSZ will continue to work correctly.

Several of the typedefs have been changed in the C++ header files. For example,
many items that are unsigned char in the C header files are char in the C++
header files. 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 used with either set of the header files.


ΓòÉΓòÉΓòÉ 2.10.3.2. PCSZ Data Type ΓòÉΓòÉΓòÉ

Note:  The PCSZ data type is defined in the C++ header files included with this
       product. The use of the "const" keyword is not necessarily specific to
       C++. Certain C compilers support it as well.

 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 C++ 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.

 Declaring the parameter as PCSZ informs the C++ compiler that the function
 will not change the string. Therefore, the compiler simply passes a pointer to
 the string in the function parameter list. If the parameter is declared as a
 normal PSZ (not "const"), the compiler assumes that the function might change
 the string. Under these circumstances the compiler will add code to make a
 copy of the string then pass a pointer to the copy, rather than pass a pointer
 to the original string.

 A smaller, faster executable is often produced if the data item passed in a
 parameter list is declared as "const".

 If the data item is declared as "const" then it must not be changed by the
 function.


ΓòÉΓòÉΓòÉ 2.10.3.3. LINK386 ΓòÉΓòÉΓòÉ

The C++ compiler will provide a dynamic link library which is be used by
LINK386 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.