CPGuide - Introduction to the Control Program
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
The purpose of this reference is to give information about functions, constants, and data structures. It provides information about the functions which enable the user to call functions in the C programming language.
The following information is provided:
- The syntax and parameters for each function
- The syntax of each data type and structure
Control Program Fundamentals
OS/2 is an advanced, multitasking, operating system for personal computers. OS/2 has a rich application programming interface (API) that supports:
- Multitasking
- Interprocess communication
- Error and exception handling
- Dynamic (run-time) linking
- Graphical user interface (GUI)
OS/2 also provides advanced file system features such as installable file systems, extended file attributes, and long file names.
OS/2 runs on and takes full advantage of the 80386 microprocessor. Features based on the 80386 microprocessor include:
- 32-bit operands and operations
- Flat (non-segmented) 4 gigabyte address space
- 32-bit memory pointers
- Hardware-based memory protection and task management
OS/2 provides a windowed, graphical user interface called the Presentation Manager* (PM*).
Control Program Functionality
The lowest-level functions supplied by the OS/2 operating system are those provided by the kernel and the kernel's subsystems-the control programs of the operating system. The Control Program functions involve the most basic aspects of program execution, such as memory management, file handling, and process, thread, and session management. They also involve more sophisticated programming tasks, such as exception handling and interprocess communications. The names of all the system functions in the Control Program API are prefixed with the letters "Dos", as in DosAllocMem.
This book describes the following topics from the operating system's Control Program API:
- File and disk management
- Memory management
- Program execution control (Process and session management)
- Semaphores
- Pipes
- Queues
- Timing functions
- Error handling
- Exception handling
- Device I/O support
- Message management
- National language support and code page management
- Debugging
- Dynamic Linking
File System and File Management
The file system is the component of the operating system that supports storing information on mass storage devices, such as hard disks and diskettes. Applications view a file as a logical sequence of data; the file system manages the physical locations of data on the storage device for the application and specifies how the device and the stored information are formatted.
The file system also manages file I/O operations. Applications use file system functions to open, read, write, and close disk files. File system functions enable an application to maintain the disk that holds the files-volumes, directories, and files on the disks of the computer. Applications also use OS/2 file system functions to perform I/O operations to pipes and peripheral devices connected to the computer, such as the printer.
The file system also supports redirection of input and output, for example redirecting output from the display to a disk file or to the printer.
There are two types of file systems supported by the OS/2 operating system. The first is the File Allocation Table (FAT) file system. The FAT file system is the file system used by DOS The second type of file system supported by the operating system is the installable file system (IFS). Installable file systems are external to the base operating system and are loaded by the operating system when the computer is started. The High Performance File System (HPFS) included with the OS/2 operating system is an installable file system.
Memory Management
The key features of OS/2 memory management are paged virtual memory and a 32-bit linear (flat) address space that is mapped through page tables to physical memory. This is in contrast to the segmented memory model used in previous versions of the operating system.
An application can allocate memory for its own use or to be shared with other applications.
Program Execution and Control
Multitasking is the ability of the operating system to manage the execution of more than one application at a time. For the programmer, this includes the ability to multitask your own programs.
The OS/2 operating system supports two forms of multitasking for programs. An application can start other programs that will execute concurrently with the application. These programs can be a new copy of the application, a related program that is designed to work with the application, or an unrelated program. The operating system provides functions to communicate with and control the programs started by the application.
The OS/2 operating system also enables applications to run multiple threads of execution within the same application; separate activities can be multitasked within the application. An example of this is dispatching a separate subroutine to load a file and having the subroutine execute at the same time the main routine continues to monitor and respond to user input.
Semaphores
Semaphores signal the beginning and ending of an operation and provide mutually exclusive ownership of resources. Typically, semaphores are used to prevent more than one process or thread within a process from accessing a resource, such as shared memory, at the same time.
Semaphores are defined by the system and reside in an internal memory buffer. They are divided into three types, according to the functionality they provide:
- Event semaphores enable a thread to notify waiting threads that an event has occurred.
- Mutual exclusion (mutex) semaphores enable threads to serialize their access to shared resources.
- Multiple Wait (muxwait) semaphores enable threads to wait either for multiple events to occur, or for multiple resources to become available.
Pipes
A pipe is a named or unnamed buffer used to pass data between processes. A process writes to or reads from a pipe as though the pipe were standard input or standard output. A parent process can use pipes to control the input that a child process receives and to receive the output that the child process produces. There are two types of pipes-named and unnamed.
Queues
A queue is a named, ordered list of elements that is used to pass information between related or unrelated processes. The owner of the queue (the server process) can choose the order in which to read incoming information and can examine queue elements without removing them from the queue. Queue elements can be added and accessed in First-In-First-Out (FIFO), Last-In-First-Out (LIFO), or priority-based order.
Timers
Timers enable an application to suspend operation for a specific length of time, to block a thread of execution until an interval has elapsed, or to post an event semaphore at repeated intervals.
Error Management
The OS/2 operating system provides functions to facilitate error processing. DosErrClass returns a classification of the error and a recommended action. DosError enables an application to prevent the operating system from displaying the default error message in a pop-up window when either a hard error or a software exception occurs.
Exception Management
A multitasking operating system must manage applications carefully. A serious error (such as an attempt to access protected memory) occurring in one application cannot be permitted to damage any other application in the system. To manage errors that might damage other applications, the OS/2 operating system defines a class of error conditions called exceptions and defines default actions for those errors.
An exception is an abnormal condition that can occur during program execution. Common causes of exceptions include I/O errors and access protection violations. When an exception is caused by the user pressing Ctrl+Break or Ctrl+C, the exception is called a signal exception.
When an exception occurs, the default action usually taken by the operating system is to terminate the application that caused the exception. An application can register its own exception handling routine and try to handle the exception itself. It might be possible for the application to correct the condition that caused the exception and continue execution.
Device I/O
A device is a piece of hardware used for input and output. Devices used with computers include the keyboard, video display, mouse, diskette and hard disk drives, and external systems, such as modems and printers. The operating system supplies functions that can be used to access and control such devices.
Message Management
For full-screen applications, text messages-used by an application to display information to the user-can be held in a message file. Keeping an application's messages in a message file simplifies changing those messages, which, for example, can facilitate marketing an application in several countries simultaneously.
National Language Support and Code Page Management
Many applications must support more than one national language, for example, French and German. This requirement is simplified through the use of such resources as string tables, menu templates, dialog templates, and accelerator tables.
A code page is a table that defines how characters are encoded. Code page management enables a user to select a code page for keyboard input, and screen and printer output before starting an application, a system command, or a utility program in the OS/2 multitasking environment.
Debugging
Debugging is the process of detecting, diagnosing, and eliminating errors in programs. A debugger program is designed to interact with the application that it is debugging. Because of the protected mode architecture of the OS/2 operating system, special steps must be taken to allow a debugging program to perform its functions in the program being debugged. DosDebug enables one application to control the execution of another application for debugging purposes.
I/O Control Functions
The OS/2 operating system provides functions to allow an application or subsystem to send device-specific control commands to a physical device driver. These IOCtls are subfunctions issued through the DosDevIOCtl function.
For a complete listing of IOCtl functions, see Generic IOCtl Commands.
Dynamic Linking
Dynamic linking permits several applications to use a single copy of an executable module. The executable module is completely separate from the applications that use it. Several functions can be built into a DLL, and applications can use these functions as though they were part of the application's executable code. You can change the dynamically-linked functions without recompiling or relinking the application.
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_CREATEWindow
- :message
- SV_CXICONSystem
- :value
- CF_TEXTClipboard
- :format.
- In this book, references to a complete set of constants with a given prefix is written as shown in the following examples:
- Window message
- :WM_*
- System value
- :SV_*
Parameters and Fields Function parameters and data structure fields are shown in italics.