home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tolkit45.zip / os2tk45 / book / gpi1.inf (.txt) < prev    next >
OS/2 Help File  |  1999-05-12  |  20KB  |  579 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. How to Use the GPI Guide and Reference ΓòÉΓòÉΓòÉ
  3.  
  4. This reference is a detailed technical guide and reference for application 
  5. programmers. It gives reference information and code examples to enable you to 
  6. write source code using Graphical Programming Interface functions. 
  7.  
  8. Before you begin to use this information, it would be helpful to understand how 
  9. you can: 
  10.  
  11.      Expand the Contents to see all available topics 
  12.      Obtain additional information for a highlighted word or phrase 
  13.      Use action bar choices 
  14.      Use the programming information. 
  15.  
  16.  How to Use the Contents 
  17.  
  18.  When the Contents window first appears, some topics have a plus (+) sign 
  19.  beside them. The plus sign indicates that additional topics are available. 
  20.  
  21.  To expand the Contents if you are using a mouse, click on the plus sign. If 
  22.  you are using the keyboard, use the Up or Down Arrow key to highlight the 
  23.  topic, and press the plus (+) key. For example, Code Pages has a plus sign 
  24.  beside it. To see additional topics for that heading, click on the plus sign 
  25.  or highlight that topic and press the plus (+) key. 
  26.  
  27.  To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  28.  to highlight the topic, and then press the Enter key). 
  29.  
  30.  How to Obtain Additional Information 
  31.  
  32.  After you select a topic, the information for that topic appears in a window. 
  33.  Highlighted words or phrases indicate that additional information is 
  34.  available. You will notice that certain words and phrases are highlighted in 
  35.  green letters, or in white letters on a black background. These are called 
  36.  hypertext terms. If you are using a mouse, double-click on the highlighted 
  37.  word. If you are using a keyboard, press the Tab key to move to the 
  38.  highlighted word, and then press the Enter key. Additional information then 
  39.  appears in a window. 
  40.  
  41.  How to Use Action Bar Choices 
  42.  
  43.  Several choices are available for managing information presented in the 
  44.  Graphics Programming Interface Programming Reference. There are three 
  45.  pull-down menus on the action bar:  the Services menu, the Options menu, and 
  46.  the Help menu. 
  47.  
  48.  The actions that are selectable from the Services menu operate on the active 
  49.  window currently displayed on the screen. These actions include the following: 
  50.  
  51.  Bookmark 
  52.     Allows you to set a placeholder so you can retrieve information of interest 
  53.     to you. 
  54.  
  55.     When you place a bookmark on a topic, it is added to a list of bookmarks 
  56.     you have previously set. You can view the list, and you can remove one or 
  57.     all bookmarks from the list. If you have not set any bookmarks, the list is 
  58.     empty. 
  59.  
  60.     To set a bookmark, do the following: 
  61.  
  62.       1. Select a topic from the Contents. 
  63.  
  64.       2. When that topic appears, choose the Bookmark option from the Services 
  65.          pull-down. 
  66.  
  67.       3. If you want to change the name used for the bookmark, type the new 
  68.          name in the field. 
  69.  
  70.       4. Click on the Place radio button (or press the Up or Down Arrow key to 
  71.          select it). 
  72.  
  73.       5. Click on OK (or select it and press Enter). The bookmark is then added 
  74.          to the bookmark list. 
  75.  
  76.  Search 
  77.     Allows you to find occurrences of a word or phrase in the current topic, 
  78.     selected topics, or all topics. 
  79.  
  80.     You can specify a word or phrase to be searched. You can also limit the 
  81.     search to a set of topics by first marking the topics in the Contents list. 
  82.  
  83.     To search for a word or phrase in all topics, do the following: 
  84.  
  85.       1. Choose the Search option from the Services pull-down. 
  86.  
  87.       2. Type the word or words to be searched for. 
  88.  
  89.       3. Click on All sections (or press the Up or Down Arrow keys to select 
  90.          it). 
  91.  
  92.       4. Click on Search (or select it and press Enter) to begin the search. 
  93.  
  94.       5. The list of topics where the word or phrase appears is displayed. 
  95.  
  96.  Print 
  97.     Allows you to print one or more topics. You can also print a set of topics 
  98.     by first marking the topics in the Contents list. 
  99.  
  100.     To print the document Contents list, do the following: 
  101.  
  102.       1. Choose Print from the Services pull-down. 
  103.  
  104.       2. Click on Contents (or press the Up or Down Arrow key to select it). 
  105.  
  106.       3. Click on Print (or select it and press Enter). 
  107.  
  108.       4. The Contents list is printed on your printer. 
  109.  
  110.  Copy 
  111.     Allows you to copy a topic that you are viewing to the System Clipboard or 
  112.     to a file that you can edit. You will find this particularly useful for 
  113.     copying syntax definitions and program samples into the application that 
  114.     you are developing. 
  115.  
  116.     You can copy a topic that you are viewing in two ways: 
  117.  
  118.         Copy copies the topic that you are viewing into the System Clipboard. 
  119.          If you are using a Presentation Manager editor (for example, the 
  120.          System Editor) that copies or cuts (or both) to the System Clipboard, 
  121.          and pastes to the System Clipboard, you can easily add the copied 
  122.          information to your program source module. 
  123.  
  124.         Copy to file copies the topic that you are viewing into a temporary 
  125.          file named TEXT.TMP. You can later edit that file by using any editor. 
  126.          You will find TEXT.TMP in the directory where your viewable document 
  127.          resides. 
  128.  
  129.          To copy a topic, do the following: 
  130.  
  131.            1. Expand the Contents list and select a topic. 
  132.  
  133.            2. When the topic appears, choose Copy to file from the Services 
  134.               pull-down. 
  135.  
  136.            3. The system puts the text pertaining to that topic into the 
  137.               temporary file named TEXT.TMP. 
  138.  
  139.     For information on one of the other choices in the Services pull-down, 
  140.     highlight the choice and press the F1 key. 
  141.  
  142.  The actions that are selectable from the Options menu allow you to change the 
  143.  way your Contents list is displayed. To expand the Contents and show all 
  144.  levels for all topics, choose Expand all from the Options pull-down. You can 
  145.  also press the Ctrl and * keys together. For information on one of the other 
  146.  choices in the Options pull-down, highlight the choice and press the F1 key. 
  147.  
  148.  The actions that are selectable from the Help menu allow you to select 
  149.  different types of help information. You can also press the F1 key for help 
  150.  information about the Information Presentation Facility (IPF). 
  151.  
  152.  How to Use the Programming Information 
  153.  
  154.  This document consists of guide and reference information that provides a 
  155.  detailed description of each function, message, constant, and data type. It 
  156.  provides language-dependent information about the functions which enable the 
  157.  user to generate call statements in the C Language. 
  158.  
  159.  Graphical Programming Interface programming information is presented by 
  160.  component, such as Graphics Functions, Graphics Orders, and Data Types, for 
  161.  example: 
  162.  
  163.        ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  164.        Γöé            Contents                     Γöé
  165.        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  166.        Γöé                                         Γöé
  167.        Γöé  + Graphics Functions                   Γöé
  168.        Γöé  + Graphics Orders                      Γöé
  169.        Γöé  + Data Types                           Γöé
  170.        Γöé                                         Γöé
  171.        ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  172.  
  173.  By clicking on the plus sign beside "Graphics Functions", you see an 
  174.  alphabetic list of the Graphical Programming Interface functions. Selecting a 
  175.  function takes you directly into the reference information for that function. 
  176.  
  177.  Units of reference information are presented in selectable multiple windows or 
  178.  viewports. A viewport is a Presentation Manager window that can be sized, 
  179.  moved, minimized, maximized, or closed. By selecting a unit (in this case, an 
  180.  entry on the Contents list), you will see two windows displayed: 
  181.  
  182.      ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  183.      Γöé Unit Title         Γöé      Selection Title     Γöé
  184.      Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  185.      Γöé Select an item     Γöé                          Γöé
  186.      Γöé                    Γöé                          Γöé
  187.      Γöé Syntax             Γöé                          Γöé
  188.      Γöé Returns            Γöé                          Γöé
  189.      Γöé Notes              Γöé                          Γöé
  190.      Γöé Example Code       Γöé                          Γöé
  191.      Γöé Related Functions  Γöé                          Γöé
  192.      Γöé Glossary           Γöé                          Γöé
  193.      Γöé                    Γöé                          Γöé
  194.      ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  195.  
  196.  The window on the left is the primary window. It contains a list of items that 
  197.  are always available to you. The window on the right is the secondary window. 
  198.  It contains a "snapshot" of the unit information. For reference units (that 
  199.  is, function descriptions), this window contains the Function Syntax. 
  200.  
  201.  All of the information needed to understand a reference unit (or topic) is 
  202.  readily available to you through the primary window. The information is 
  203.  divided into discrete information groups, and only the appropriate information 
  204.  group appears for the topic that you are viewing. 
  205.  
  206.  The information groups for a reference unit (that is, a function description) 
  207.  can include all or some of the following: 
  208.  
  209.      Syntax 
  210.      Parameters 
  211.      Returns 
  212.      Errors 
  213.      Notes 
  214.      Example Code 
  215.      Related Functions 
  216.      Graphic Elements and Orders 
  217.      Glossary 
  218.  
  219.  This list may vary. Some topics may be omitted when they do not apply. 
  220.  
  221.  Information groups are displayed in separate viewports that are stacked in a 
  222.  third window location that overlaps the secondary window. By selecting an item 
  223.  (information group) in the primary window, the item is displayed in the third 
  224.  window location, as follows: 
  225.  
  226.    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  227.    Γöé Unit Title     Γöé   Selection Γöé   Glossary       Γöé
  228.    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  229.    Γöé Select an item Γöé             Γöé Select a startingΓöé
  230.    Γöé                Γöé             Γöé letter of        Γöé
  231.    Γöé    .           Γöé             Γöé glossary terms   Γöé
  232.    Γöé    .           Γöé             Γöé                  Γöé
  233.    Γöé    .           Γöé             Γöé A    N           Γöé
  234.    Γöé    .           Γöé             Γöé B    O           Γöé
  235.    Γöé    .           Γöé             Γöé C    P           Γöé
  236.    Γöé Glossary       Γöé             Γöé .    .           Γöé
  237.    Γöé                Γöé             Γöé .    .           Γöé
  238.    Γöé                Γöé             Γöé .    .           Γöé
  239.    Γöé                Γöé             Γöé M    Z           Γöé
  240.    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  241.  
  242.  By selecting successive items from the primary window, additional windows are 
  243.  displayed on top of the previous windows displayed in the third window 
  244.  location. For example, in a function description, Parameters and Return Values 
  245.  are items listed in the primary window. When selected, they appear one on top 
  246.  of the other in the third window location. Because of this, you may move the 
  247.  first selected (topmost) window to the left before selecting the next item. 
  248.  This allows simultaneous display of two related pieces of information from the 
  249.  "stack" of windows in the third window location, as follows: 
  250.  
  251.    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  252.    Γöé Unit Title     Γöé  Parameters  Γöé  Return Values  Γöé
  253.    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  254.    Γöé Select an item Γöé              Γöé                 Γöé
  255.    Γöé    .           Γöé              Γöé                 Γöé
  256.    Γöé    .           Γöé              Γöé                 Γöé
  257.    Γöé    .           Γöé              Γöé                 Γöé
  258.    Γöé Returns        Γöé              Γöé                 Γöé
  259.    Γöé Errors         Γöé              Γöé                 Γöé
  260.    Γöé    .           Γöé              Γöé                 Γöé
  261.    Γöé    .           Γöé              Γöé                 Γöé
  262.    Γöé    .           Γöé              Γöé                 Γöé
  263.    Γöé                Γöé              Γöé                 Γöé
  264.    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  265.  
  266.  Each window can be individually closed from its system menu. All windows are 
  267.  closed when you close the primary window. 
  268.  
  269.  Some secondary windows may have the appearance of a split screen. For example, 
  270.  an illustration may appear in the left half of the window, and scrollable, 
  271.  explanatory information may appear in the right half of the window. Because 
  272.  illustrations may not necessarily fit into the small window size on your 
  273.  screen, you may maximize the secondary window for better readability. 
  274.  
  275.  
  276. ΓòÉΓòÉΓòÉ 1.1. Conventions Used in this Reference ΓòÉΓòÉΓòÉ
  277.  
  278. The purpose of this reference is to give information about functions, 
  279. constants, and data types. It provides information about the functions which 
  280. enables the user to call functions in the C programming language. 
  281.  
  282. The following information is provided: 
  283.  
  284.      The syntax and parameters for each function. 
  285.      The syntax of each data type and structure 
  286.  
  287.  
  288. ΓòÉΓòÉΓòÉ 1.2. Notation Conventions ΓòÉΓòÉΓòÉ
  289.  
  290. The following notation conventions are used in this reference: 
  291.  
  292.  NULL                  The term NULL applied to a parameter is used to indicate 
  293.                        the presence of the pointer parameter, but with no 
  294.                        value. 
  295.  
  296.  NULLHANDLE            The term NULLHANDLE applied to a parameter is used to 
  297.                        indicate the presence of the handle parameter, but with 
  298.                        no value. 
  299.  
  300.  Implicit Pointer      If no entry for a data type "Pxxxxxxx" is found in Data 
  301.                        Types, then it is implicitly a pointer to the data type 
  302.                        "xxxxxxx". See Implicit Pointer Data Types for more 
  303.                        information about implicit pointers. 
  304.  
  305.  Constant Names        All constants are written in uppercase to match the 
  306.                        header files. Where applicable, constant names have a 
  307.                        prefix derived from the name of a function, message, or 
  308.                        idea associated with the constant. For example: 
  309.  
  310.                        WM_CREATE          Window message 
  311.                        SV_CXICON          System value 
  312.                        CF_TEXT            Clipboard format. 
  313.  
  314.                        In this reference, references to a complete set of 
  315.                        constants with the same prefix is written as shown in 
  316.                        the following examples: 
  317.  
  318.                        Window message       WM_* 
  319.                        System value         SV_* 
  320.  
  321.  Parameters and Fields Function parameters and data structure fields are shown 
  322.                        in italics. 
  323.  
  324.  
  325. ΓòÉΓòÉΓòÉ 1.3. Conventions Used in Function Descriptions ΓòÉΓòÉΓòÉ
  326.  
  327. The documentation of each function contains the following sections: 
  328.  
  329.  Syntax 
  330.       The function syntax describes the C-language calling syntax of the 
  331.       function and gives a brief description. 
  332.  
  333.       Programming Note 
  334.                         The functions in this book are spelled in mixed-case 
  335.                         for readability but are known to the system as 
  336.                         uppercase character strings. For example, the function 
  337.                         "GPIBeginArea" is actually the external name 
  338.                         "GPIBEGINAREA". 
  339.  
  340.       If you are using a compiler that generates a mixed-case external name, 
  341.       you should code the functions in uppercase. 
  342.  
  343.  Parameters 
  344.       Each parameter is listed with its C-language data type, parameter type, 
  345.       and a brief description. 
  346.  
  347.           All data types are written in uppercase to match the header files. A 
  348.            data type of "Pxxxxxxx" implicitly defines a pointer to the data 
  349.            type "xxxxxxx". 
  350.  
  351.            The term NULL applied to a parameter indicates the presence of the 
  352.            parameter, with no value. 
  353.  
  354.            Refer to Data Types for a complete list of all data types and their 
  355.            descriptions. 
  356.  
  357.           There are three parameter types: 
  358.  
  359.            Input              Specified by the programmer. 
  360.            Output             Returned by the function. 
  361.            Input/Output       Specified by the programmer and modified by the 
  362.                               function. 
  363.  
  364.           A brief description is provided with each parameter. Where 
  365.            appropriate, restrictions are also included. In some cases, the 
  366.            parameter points to a structure. 
  367.  
  368.  Returns 
  369.       A list of possible return codes or errors (when appropriate) is included 
  370.       in this section. Some functions do not have return codes. Refer to Error 
  371.       Number and Name for a list of error codes and their numerical values, and 
  372.       Error Name and Explanation for a list of error codes and their 
  373.       descriptions. 
  374.  
  375.  Remarks 
  376.       This section contains additional information about the function, when 
  377.       required. 
  378.  
  379.  Related Functions 
  380.       This list shows the functions (if any) that are related to the function 
  381.       being described. 
  382.  
  383.  Example Code 
  384.       An example of how the function can be used is shown in C language. 
  385.  
  386.  
  387. ΓòÉΓòÉΓòÉ 1.4. Error Severities ΓòÉΓòÉΓòÉ
  388.  
  389. Each of the error conditions given in the list of errors for each function 
  390. falls into one of these areas: 
  391.  
  392.  Warning 
  393.     The function detected a problem, but took some remedial action that enabled 
  394.     the function to complete successfully. The return code in this case 
  395.     indicates that the function completed successfully. 
  396.  
  397.  Error 
  398.     The function detected a problem for which it could not take any sensible 
  399.     remedial action. The system has recovered from the problem, and the state 
  400.     of the system, with respect to the application, remains the same as at the 
  401.     time when the function was requested. The system has not even partially 
  402.     executed the function (other than reporting the error). 
  403.  
  404.  Severe Error 
  405.     The function detected a problem from which the system could not reestablish 
  406.     its state, with respect to the application, at the time when that function 
  407.     was requested; that is, the system partially executed the function. This 
  408.     necessitates the application performing some corrective activity to restore 
  409.     the system to some known state. 
  410.  
  411.  Unrecoverable Error 
  412.     The function detected some problem from which the system could not 
  413.     re-establish its state, with respect to the application, at the time when 
  414.     that call was issued. It is possible that the application cannot perform 
  415.     some corrective action to restore the system to some known state. 
  416.  
  417.  The WinGetLastError and WinGetErrorInfo functions can be used to find out more 
  418.  about an error (or warning) that occurs as a result of executing a call. 
  419.  
  420.  
  421. ΓòÉΓòÉΓòÉ 1.5. Header Files ΓòÉΓòÉΓòÉ
  422.  
  423. All functions require an "#include" statement for the system header file OS2.H: 
  424.  
  425.  
  426. #include  <OS2.H>
  427.  
  428. Most functions also require a "#define" statement to select an appropriate 
  429. (conditional) section of the header file, and hence, the required prototype. 
  430. Where this is necessary, it is shown at the head of the function definition in 
  431. the form: 
  432.  
  433.  
  434. #define   INCL_name
  435.  
  436. Note:  These "#define" statements must precede the "#include <OS2.H>" 
  437.        statement. 
  438.  
  439.  
  440. ΓòÉΓòÉΓòÉ 1.6. Addressing Elements in Arrays ΓòÉΓòÉΓòÉ
  441.  
  442. Constants defining array elements are given values that are zero-based in C; 
  443. that is, the numbering of the array elements starts at zero, not one. 
  444.  
  445. For example, in the DevQueryCaps function, the sixth element of the alArray 
  446. parameter is CAPS_HEIGHT, which is equated to 5. 
  447.  
  448. Count parameters related to such arrays always mean the actual number of 
  449. elements available; therefore, again using the DevQueryCaps function as an 
  450. example, if all elements up to and including CAPS_HEIGHT are provided for, 
  451. lCount could be set to (CAPS_HEIGHT+1). 
  452.  
  453. In functions for which the starting array element can be specified, this is 
  454. always zero-based, and so the C element number constants can be used directly. 
  455. For example, to start with the CAPS_HEIGHT element, the DevQueryCaps parameter 
  456. can be set to CAPS_HEIGHT. 
  457.  
  458.  
  459. ΓòÉΓòÉΓòÉ 1.7. Implicit Pointer Data Types ΓòÉΓòÉΓòÉ
  460.  
  461. A data type name beginning with "P" (for example, PERRORCODE) is likely to be a 
  462. pointer to another data type (in this instance, ERRORCODE). 
  463.  
  464. In the data type summary, Data Types, no explicit "typedefs" are shown for 
  465. pointers; therefore, if no data type definition can be found in the summary for 
  466. a data type name "Pxxxxxx", it represents a pointer to the data type "xxxxxx", 
  467. for which a definition should be found in the reference. 
  468.  
  469. The implicit type definition needed for such a pointer "Pxxxxxx" is: 
  470.  
  471.  
  472. typedef xxxxxx *Pxxxxxx;
  473.  
  474. Such definitions are provided in the header files. OS2.H. 
  475.  
  476.  
  477. ΓòÉΓòÉΓòÉ 1.8. Storage Mapping of Data Types ΓòÉΓòÉΓòÉ
  478.  
  479. The storage mapping of the data types is dependent on the machine architecture. 
  480. To be portable, applications must access the data types using the definitions 
  481. supplied for the environment in which they will execute. 
  482.  
  483.  
  484. ΓòÉΓòÉΓòÉ 1.9. Double-Byte Character Set (DBCS) ΓòÉΓòÉΓòÉ
  485.  
  486. Throughout this publication, you will see references to specific value for 
  487. character strings. The values are for single-byte character set (SBCS). If you 
  488. use the double-byte character set (DBCS), note that one DBCS character equals 
  489. two SBCS characters. 
  490.  
  491.  
  492. ΓòÉΓòÉΓòÉ 1.10. Programming Considerations ΓòÉΓòÉΓòÉ
  493.  
  494. This section provides information you need to consider before you begin 
  495. programming with GPI functions. 
  496.  
  497.  
  498. ΓòÉΓòÉΓòÉ 1.10.1. Stack Size ΓòÉΓòÉΓòÉ
  499.  
  500. Existing 16-bit applications (small and tiny models) must have a 4KB stack 
  501. available when they enter system calls; otherwise, the stack can overflow into 
  502. the data area. 
  503.  
  504.  
  505. ΓòÉΓòÉΓòÉ 1.10.2. Presentation Manager ΓòÉΓòÉΓòÉ
  506.  
  507. The Presentation Manager component of the OS/2* operating system is based on 
  508. the IBM Systems Application Architecture* (SAA*) Common Programming Interface-a 
  509. an architecture for the design and development of applications. 
  510.  
  511. The Presentation Manager component implements the Common User Access* (CUA*) 
  512. interface, which you can use to attain consistency in the appearance and 
  513. behavior of your applications. 
  514.  
  515.  
  516. ΓòÉΓòÉΓòÉ 1.10.3. C++ Considerations ΓòÉΓòÉΓòÉ
  517.  
  518. This section contains several topics you should take into consideration if you 
  519. are using C++ **. 
  520.  
  521.  
  522. ΓòÉΓòÉΓòÉ 1.10.3.1. C++ Header Files ΓòÉΓòÉΓòÉ
  523.  
  524. OS/2 functions that used to take a PSZ as a parameter, and that do not modify 
  525. the contents of the passed string, have been updated in the C++ header files to 
  526. take a PCSZ data type parameter. The use of PCSZ allows for better optimization 
  527. by the compiler and is more semantically compatible with C++. Existing code 
  528. that calls functions that use PSZ will continue to work correctly. 
  529.  
  530. Several of the typedefs have been changed in the C++ header files. For example, 
  531. many items that are unsigned char in the C header files are char in the C++ 
  532. header files. For instance, 
  533.  
  534.  
  535. typedef unsigned char BYTE;
  536.  
  537. has changed to 
  538.  
  539.  
  540. typedef char BYTE;
  541.  
  542. The existing samples that are included in the IBM Developer's Toolkit for OS/2 
  543. Warp, Version 3 can be used with either set of the header files. 
  544.  
  545.  
  546. ΓòÉΓòÉΓòÉ 1.10.3.2. PCSZ Data Type ΓòÉΓòÉΓòÉ
  547.  
  548. Note:  The PCSZ data type is defined in the C++ header files included with this 
  549.        product. The use of the "const" keyword is not necessarily specific to 
  550.        C++. Certain C compilers support it as well. 
  551.  
  552.  If a function takes as a parameter a string that is not changed by the 
  553.  function, the string parameter can be declared as a "const" string, or a PCSZ. 
  554.  PCSZ is defined in the C++ header files as a "const" pointer to a 
  555.  NULL-delimited string. The "const" means that the function will not change the 
  556.  contents of the string. 
  557.  
  558.  Declaring the parameter as PCSZ informs the C++ compiler that the function 
  559.  will not change the string. Therefore, the compiler simply passes a pointer to 
  560.  the string in the function parameter list. If the parameter is declared as a 
  561.  normal PSZ (not "const"), the compiler assumes that the function might change 
  562.  the string. Under these circumstances the compiler will add code to make a 
  563.  copy of the string then pass a pointer to the copy, rather than pass a pointer 
  564.  to the original string. 
  565.  
  566.  A smaller, faster executable is often produced if the data item passed in a 
  567.  parameter list is declared as "const". 
  568.  
  569.  If the data item is declared as "const" then it must not be changed by the 
  570.  function. 
  571.  
  572.  
  573. ΓòÉΓòÉΓòÉ 1.10.3.3. LINK386 ΓòÉΓòÉΓòÉ
  574.  
  575. The C++ compiler will provide a dynamic link library which is be used by 
  576. LINK386 when generating error messages. This DLL will convert a compiler 
  577. generated mangled name into the function prototype. If the DLL is not present, 
  578. an error message will be displayed and LINK386 will display the 
  579. compiler-generated mangled name in error messages.