View source for PDRREF:Syntax Conventions

{{PDRREF}}
{{IBM-Reprint}}

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: 
<PRE>
┌──────────┬──────────┬────────────────────────────────────────┐
│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.                           │
└──────────┴──────────┴────────────────────────────────────────┘
</PRE>

The following standard prefixes are also defined: 
<PRE>
┌──────────┬──────────────────────────────────────────────────┐
│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.                              │
└──────────┴──────────────────────────────────────────────────┘
</PRE>

Some parameters are used in pairs; the qualifiers that are used reflect the relationship between the two variables. For example: 
<PRE>
┌────────────┬───────────────────────────────────────────────────────────────────┐
│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++)            │
│            │        ...                                                        │
├────────────┼───────────────────────────────────────────────────────────────────┤
│            │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.                                                        │
├────────────┼───────────────────────────────────────────────────────────────────┤
│Cur         │Current value.                                                     │
└────────────┴───────────────────────────────────────────────────────────────────┘
</PRE>

The base types and their prefixes are defined as follows: 
<PRE>
┌──────────┬──────────────────────────────────────────────────┐
│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                                                │
└──────────┴──────────────────────────────────────────────────┘
</PRE>

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.