SMPProgAdd - Introduction to OS/2 Warp Server Version 4 Advanced
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
This document provides a guide for developers writing applications and device drivers exploiting the symmetrical multiprocessing capabilities of OS/2 Warp Server Version 4 Advanced.
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.
OS/2 Warp Server for SMP was developed to satisfy the need to run OS/2 on multiprocessor based CISC processors, namely the Intel x86 compatible family. The requirements for OS/2 Warp Server for SMP were that it run all existing applications, device drivers and subsystems, as well as take advantage of new multiprocessor (MP) exploitive applications and device drivers.
The emergence of low-cost MP hardware based on the 486, Pentium, and Pentium Pro processors makes OS/2 Warp Server for SMP an attractive desktop operating environment. Server and workstation environments using the x86 architecture are moving toward the more powerful emerging RISC based chip sets. These new RISC processors lack the full range of programming tools available for the x86 chip set. OS/2 Warp Server for SMP attempts to solve the problems of insufficient processor bandwidth by supporting multiple x86 processors in a single computer.
To provide increased performance, OS/2 Warp Server for SMP allows applications, file system, mass storage and network drivers to execute on any processor at any time. A number of databases and applications have been modified to take advantage of the additional features provided by OS/2 Warp Server for SMP. DB2/2 and CICS are two databases that IBM has modified to run better under OS/2 Warp Server for SMP. These applications can benefit greatly from OS/2 Warp Server for SMP because they are CPU-intensive. Other applications which can also benefit from OS/2 Warp Server for SMP are:
- Lotus Notes & cc:Mail
- NetView Series
- Novell Netware
- Scientific Applications
- Multimedia Applications
What's New Since OS/2 for SMP 2.11
OS/2 Warp Server Version 4 Advanced provides:
- High Memory Support Memory management has been enhanced to allow 32-bit applications to allocate and address linear memory objects above the 512MB boundary. This effectively breaks the 512MB memory limit in previous versions of OS/2.
- Raw File System The Raw File System provides the ability to access physical or logical drives using a UNC name. Since drive access is no longer limited to available drive letters, more than 26 physical and logical drives are now available to 32-bit applications. This allows access to up to 128 drives without incurring the serialization overhead of the OS/2 file system. In addition, the raw file system supports physical disks up to 1 TB (terabyte) in size.
- Enhanced File I/O Support With the addition of the DosListIO function, multiple locking, unlocking, seeking, and I/O operations may now be initiated at once. These can be synchronous (ordered) requests or, in the case of the Raw File System, unordered requests.
- MPS 1.4 Compliant Intel I/O APIC Support OS/2 Warp Server for SMP now recognizes multiple MPS 1.4 compliant Intel I/O Advanced Programmable Interrupt Controllers (APICs) in a system. Multiple I/O APICs increases the number of adapters allowed on the system.
- Software Trace Facility (STRACE) STRACE is a tracing tool available on Pentium-class machines which provides a software-based timing and tracing mechanism. With the addition of the DosPerfSysCall function, software running in ring 3 may now record events in the software trace buffer.
- Performance Monitoring OS/2 Warp Server for SMP provides a set of functions which allow application developers an efficient and uniform way to access system performance information and to monitor and change processor status.
- The ICAT Debugger The ICAT debugger is a source-level debugger used for remotely debugging OS/2 device drivers, kernel code, Installable File Systems (IFS), and applications running on an OS/2 Warp Server for SMP machine from another OS/2 system.
- Kernel Debugger The protocols necessary for communicating with the kernel debugger over a serial communications link have been made available for application developers.
Exploiting SMP-Specific Features
If your program or device driver will be using SMP-specific features of OS/2, such as the new DosListIO and DosPerfSysCall functions, you will need to dual-path your code so that your program can run on versions of OS/2 that do not support the new functions. It is the intent of IBM to provide these functions in non-SMP versions of OS/2 in the future.
The recommended way to determine from your program if you are running on a version of OS/2 that supports the new DosListIO and DosPerfSysCall:
- From a program: Query the exported entry point for the function using DosQueryProcAddr.
- From a device driver: Use the GetDOSVar device helper specifying first an ordinal value of 18, SMP_ACTIVE. If SMP is indicated, ordinal value 17, _cProcessors can be used to determine the number of processors available.
In addition, ordinal 19, PSDInfo.psd_flags, returns useful information about a PSD. Refer to PSDInfo in PSD.H for details.
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 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.
Conventions Used in Function Descriptions
This section provides information about the notation conventions and function descriptions used in this reference.
The documentation for 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. 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.
- 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.
- 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.
- 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 Errors for a complete list of all return 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 for each function is shown in the C programming language.
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.
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.
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 ulArray 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 lStart parameter can be set to CAPS_HEIGHT.
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.
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.
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.
C++ Considerations
This section contains several topics you should take into consideration if you are using C++.
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.
LINK386
The C++ compiler will provide a dynamic link library which is 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 the error message.