PDRREF:Syntax Conventions

From EDM2
Jump to: navigation, search
Presentation Device Driver Reference for OS/2
  1. Introduction to OS/2 Presentation Drivers
  2. Design Considerations for All Drivers
  3. Graphics Engine/Presentation Driver Design Changes
  4. Design Considerations for Display Drivers
  5. Design Considerations for Hardcopy Drivers
  6. Display Drivers
  7. Distributed Console Access Facility (DCAF) Architecture
  8. Graphics Engine Hardcopy Drivers
  9. Queue Drivers
  10. Port Drivers
  11. Presentation Manager Function Categories
  12. Exported Driver Function Reference
  13. Mandatory and Simulated Graphics Engine Function Reference
  14. Device Support Function Reference
  15. DBIDI Command Structures and Command Flow

Appendixes

A - OS/2 Version Compatibility Considerations
B - Syntax Conventions
C - Format of the Journal File
D - Bit-Map Simulation for 16-Bit Hardcopy Drivers
E - Data Types
F - Notices

Miscellaneous

G - Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

The programming statements in this book use the C language syntax. Support for code written in C is provided in header files identified by the filename extension ".h". Assembler support is provided in the include files identified by the filename extension ".INC".

Parameters Names

Parameter names are constructed to show the data type of the parameter and to indicate its use:

  • A lowercase prefix of one or more characters that indicates the data type.
  • An optional qualifier starting with an uppercase letter.

Where possible, standard names have been used to describe parameters. Where multiple word qualifiers are used, the order of the words is not significant.

For example:

hdc          /* device context handle         */
pszFilename  /* pointer to a character string */

The following standard base tags and their associated type names are defined:

Tag Data Type Description
f BOOL Flag or Boolean variable. The qualifier describes the condition associated with the flag when it is TRUE. For example, fSuccess is TRUE if successful and FALSE if not; whereas fError is TRUE if an error occurred and FALSE if no error occurred. For objects of type BOOL, the value 0 implies FALSE and any nonzero value implies TRUE.
ch CHAR Signed eight-bit quantity; a character.
s SHORT Signed 16-bit quantity; a SHORT. This is often used in place of us when it does not matter whether the value is signed or unsigned.
l LONG Signed 32-bit quantity; a LONG. This is often used in place of ul when it does not matter whether the value is signed or unsigned.
uch UCHAR Unsigned eight-bit quantity; a byte. Same as b.
us USHORT Unsigned 16-bit quantity.
ul ULONG Unsigned 32-bit quantity.
b BYTE Unsigned eight-bit quantity; a byte. Same as uch.
sz CHAR[ ] NULL-terminated string of characters.
fb UCHAR Byte of flags, that is, an array of flags packed in a BYTE.
fs USHORT SHORT of flags, that is, an array of flags packed in a USHORT.
fl ULONG LONG of flags, that is, an array of flags packed in a ULONG. The three preceding types are used when more than one flag is combined into a byte, SHORT or LONG. Typically, the values are combined with the OR operator and are always unsigned.
r REAL Real number, single precision 32-bits.
rd DOUBLE Real number, double precision 64-bits.
pfn Pointer to a function.
x X-coordinate.
y Y-coordinate.

The following standard prefixes are also defined:

Prefix Description
p 32-bit pointer for an 80386 microprocessor. For example, pch is a pointer to a character.
a Array. For example, ach is an array of characters.
i Index to an array. For example, an ich is used to index an ach.
c Count. For example, cch is a count of characters.
d Delta or difference between instances of a type. For example, dx is the difference between two values of x.
h Handle. A value that uniquely identifies an object but cannot directly be used to access it. For example, hps is a PS handle.
mp Mapping array. This prefix is always followed by two base types rather than one and represents the most general case of an array. Mathematically, an array is a function mapping the index to the value stored in the array. The prefix mp is an abbreviation of map. In the construct mpab, a is the type of the index and b is the type of the value stored in the array. In most cases, the only type that is important is the type of the value. The index is usually an integer with no other meaning (the a prefix is used in this instance).
off Offset. Generally used as an offset within a data structure. The actual address of the element within the data structure is derived by adding an offset to a pointer, which points to the beginning of the data structure. Normally, OFF is a byte offset. For example: pfoo = (FOO *)((BYTE *)pfooBase + 0fff00)
id Identifier. This is generally used for values that identify some object. Usually the association of the ID value and the object are established by the programmer. For example, all windows are identified by their Window ID, which can be set and queried by the programmer.
cmd Command. Used for command values, typically as function parameters.

Some parameters are used in pairs; the qualifiers that are used reflect the relationship between the two variables. For example:

Parameter Description
First/Last First and last elements in a set. These are typically used with indexes or pointers (pchFirst, pchLast). Both values represent valid values (compare with Min/Max below). For all valid values of x: xFirst <= x <= xLast. The use of > with First or < with Last is almost always an "off-by-one" error.

For example, to determine whether an ich is within ichFirst and ichLast:

if (ich >= ichFirst && ich <= ichLast)
...

A typical loop:

for (ich = ichFirst; ich <= ichLast; ich++)
...
Min/Max Similar to First/Last except that Max is not a valid value in the set (Min is a valid value). For all valid values of x in the set: xMin < = x < xMax. The use of > with Min or < = with Max is almost always an "off-by-one" error.

For example, to determine whether an ich is within ichMin and ichMax:

if (ich >= ichMin && ich < ichMax)
...

A typical loop:

for (ich = ichMin; ich < /* or != */ ichMax; ich++)
...
Cur The current value (Cur) qualifier can be used with Min and Max when Min or Max can change over time (for example, pbStackMaxCur).
Old/New Old and new. Typically used for values or states when it is necessary to compare the old and new states of the value.
Next/Prev Next and previous. Typically used in situations in which items are being enumerated, such as with linked lists.
Src/Dst Source and destination. Typically used in transfer operations.
T A temporary value.
Save A temporary saved value. Typically used when saving and restoring some state.

The base types and their prefixes are defined as follows:

Data Type Prefix
PSZ psz
PCH pch
HAB hab
HPS hps
HDC hdc
HRGN hrgn
HBITMAP hbmp
PLONG pl
POINTL ptl
POINTL pt
RECTL rcl
RECTL rc
HWND hwnd
WPOINT wpt
WRECT wrc
FIXED fx

Parameters for defined structures are the defined parameter names. For example:

    AREADEFS struct
             {
                   defSet
                   fFlags
                   CodePage
             }AREADEFS

System-defined constants and flags are represented as two or more uppercase WORDs or mnemonic abbreviations separated by underscores. For example, SYS_CONSTANT and SYS_FLAG.

Return Values

Function handling routines pass full 32-bit return codes back to the calling function. In MASM**, the return code is passed in the EAX Register.

Register Content Preservation

Registers EAX, ECX, and EDX can be destroyed. All other registers must be preserved.

Handles

All handles and pointers are 32-bit values.

Coordinates

All coordinates are passed as signed 32-bit values unless stated otherwise. World, model, and presentation-page space coordinates are restricted to the 28 low-order bits and lie within the range F8000000h through 07FFFFFFh. Device space coordinates are restricted to the 16 low-order bits and lie within the range FFFF0000h through 0000FFFFh.