First Edition (September 1987) 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 infor­ mation 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 copies of this publication and for technical information about IBM products should be made to your IBM Authorized Dealer or your IBM Marketing Representative. Operating System/2 and OS/2 are trademarks of the International Business Machines Corporation. ©Copyright International Business Machines Corporation 1986, 1987 All rights reserved. No part of this publication may be reproduced or distributed in any form or by any means without prior permission in writing from the International Business Machines Corporation. Preface This book contains technical information for the IBM Operating System/2™ (OS/2™1). It provides a comprehensive and detailed description of OS/2 interfaces. This book also provides descriptions of OS/2 architecture, control structures, data structures, and 110 formats necessary to understand and use those interfaces. This book is intended for the experienced user, system programmer, and application developer. You should be knowledgeable about operating systems and be proficient in one or more of the IBM Per­ sonal Computer programming languages, as well as being familiar with the 80286 architecture. Related Publications IBM Operating System/2™ User's Reference IBM Operating System/2™ Programmer's Guide IBM Personal Computer AT®2 Technical Reference IBM Personal Computer XT™3 Model 286 Technical Reference IBM Personal System/2™ Model 501/BM Personal System/2™ Model 60 Technical Reference IBM Personal System/2™ Model 80 Technical Reference IBM Personal Computer BIOS Technical Reference IBM Personal Computer Macro Assembler/2 iAPX 286 Programmer's Reference Manual including the iAPX 286 Numeric Supplement 210498, or the iAPX 386 Programmer's Reference Manual (IBSN 1-55512-022-9) Literature Department, lnte1®4 Corporation, 3065 Bowers Avenue, Santa Clara, CA. 95051 1 IBM Operating System/2™ and OS/2 are trademarks of International Business Machines Corporation 2 Personal Computer AT is a registered trademark of International Business Machines Corporation a Personal Computer XT Model 286 and IBM Personal System/2™ are trademarks of International Business Machines Corporation 4 Intel® is a registered trademark of Intel Corporation. iii iv Contents Chapter 1. Introduction . 1-1 API Function Requests . 1-2 Memory Management . 1-2 Process Control . 1-3 Timer Services . 1-3 Multitasking . 1-3 Interprocess Communication . 1-4 Session Management . 1-4 1/0 Services . 1-4 Code Page Support . 1-5 Device Monitor Services . 1-5 Printer/Spooler Services . 1-5 DevHlp Services ................................. 1-6 OS/2 Device Driver Architecture . 1-6 OS/2 Device Drivers . 1-7 Problem Determination . 1-7 Country Support Considerations . 1-7 Chapter 2. Application Program Interface (API) . 2-1 Dynamic Linking . 2-2 PC Family API . 2-2 OS/2 Function Calls . 2-3 OS/2 Function Call Rules ......................... 2-3 OS/2 Function Call Characteristics ................... 2-4 Function Call Format . 2-4 Interface Stack Frame ........................... 2-6 Function Calling Sequence Example . 2-7 OS/2 Sample Functions . 2-8 Function DOSXAMPL .......................... 2-8 High-Level Language Interface Examples ............ 2-9 OS/2 Compatibility Considerations . 2-10 OS/2 Application Environments . 2-10 DOS Family and Full Function API . 2-11 DOS Mode Exceptions .......................... 2-19 Chapter 3. Memory Management ..................... 3-1 Use of the Segmentation Hardware . 3-1 The Protection Features of the Ring Structure ........... 3-2 OS/2 Mode Memory Management . 3-4 y Real Memory Map (Protect mode only) . 3-6 Real Mode Memory Map . 3-6 Memory Management Function Call Summary . 3-8 Memory Subal location Package (MSP) . 3-9 Memory Suballocation Example . 3-9 MSP Function Call Summary . 3-10 System Extensions . 3-11 Chapter 4. Process Control . 4-1 Timer Services .................................. 4-1 Timer Management . 4-1 Tirrie/Date ................................... 4-1 Timer Intervals ................................ 4-2 Timer Services Function Call Summary . 4-3 Multitasking . 4-3 Tasking (Processes and Threads) ................... 4-4 Multiple Independent Processes Diagram . 4-6 Multiple Threads within a Process Diagram . 4-7 Resource Management . 4-8 Tasking Function Call Summary . 4-8 Interprocess Communication (IPC) . 4-9 Communication via Signals . 4-10 Communication via Messages . 4-10 Pipes .................................... 4-10 Communicating with a Pipe . 4-12 Comparing Pipes with Files: . 4-12 Queues . 4-13 Communicating with a Queue . 4-13 Comparing Pipes and Queues . 4-14 Queue Function Calls . 4-15 Managing Queues . 4-16 The Segment for Data Storage . 4-16 Managing Data Storage Examples . 4-16 Queue Element Copy Function . 4-18 Queue Element Delete Function . 4-18 Coordinating Execution Among Several Threads . 4-19 Semaphores . 4-19 Comparison of RAM and System Semaphores . 4-20 RAM Semaphore Diagram . 4-21 General Semaphore Function Calls . 4-21 Signalling via Semaphore Function Calls . 4-21 System Semaphore Function Calls . 4-22 Starting and Stopping a Thread's Execution . 4-22 vi IPC Function Call Summary . 4-23 Asynchronous Notification . 4-24 Asynchronous Notification Function Call Summary . 4-25 Program Execution Control . 4-26 Dynamic Linking . 4-26 Demand Load . 4-27 1/0 Privilege Model . 4-27 EXE File Information . 4-28 Program Execution Control Function Call Summary . 4-29 Errors and Exceptions . 4-29 Errors from Function Requests (Return Codes) . 4-29 Hard Error Override . 4-29 Handling Machine Exceptions . 4-29 Errors and Exceptions Function Call Summary . 4-30 OS/2 Message Functions (Message Retriever) . 4-30 Message Functions Function Call Summary . 4-30 Program Startup Conventions . 4-30 Chapter 5. Session Management . 5-1 Session Manager Application Support . 5-3 Restrictions ................................ 5-4 Session Management API Function Call Summary . 5-4 Chapter 6. 1/0 Services . 6-1 ASCllZ Strings . 6-1 Filename Specification ........................... 6-1 Device Names . 6-3 Code Page Support . 6-3 Code Page Management . 6-4 Code Page Dependent Information ................. 6-5 Code Page Switching Examples ................... 6-5 Code Page Preparation ........................ 6-6 Code Page Operation . 6-8 Code Page Supported Devices . 6-10 Special Considerations and Limitations . 6-10 Code Page API Summary . 6-12 System Initialization . 6-13 Hardware Characteristics . 6-13 Device Driver Installation . 6-13 CONFIG.SYS . 6-14 Device 1/0 Function Call Summary . 6-14 File 1/0 Services . 6-14 File 1/0 Function Call Summary . 6-15 vii Video 110 Services . 6-16 Display Adapters Supported . 6-16 Video Graphics Array (VGA) . 6-16 IBM Personal System/2™ Display Adapter .......... 6-17 VIO Support by Mode . 6-17 Text Modes Supported (Mono-Compatible) . 6-17 VIO Calls Supported in Text Modes: . 6-18 Graphics Modes Supported . 6-18 VIO Calls Supported in Graphics Modes . 6-19 VIO Screen Save/Restore Operations . 6-20 VIO Code Page Support . 6-21 Video Font File Organization . 6-23 Additional VIO Considerations . 6-25 VIO Function Call Summary . ..