═══ 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 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 " 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.