Programming Reference: Programming Considerations

# Programming Reference

## Programming Considerations

This section provides information you need to consider before you begin calling OpenDoc functions and methods.

### Header Files

All functions and methods require an include directive for the class header file. The following list shows each class and its corresponding header file. The include files can be case-sensitive depending of the system-platform.

OpenDoc Class Name | Include File Name
ODArbitrator | Arbitrat.xh
ODBinding | ODBindng.xh
ODCanvas | Canvas.xh
ODClipboard | Clipbd.xh
ODContainer | ODCtr.xh
ODDispatcher | Disptch.xh
ODDispatchModule | DispMod.xh
ODDocument | Document.xh
ODDraft | Draft.xh
ODDragAndDrop | DragDrp.xh
ODDragItemIterator | DgItmIt.xh
ODEmbeddedFramesIterator | EmbFrItr.xh
ODExtension | Extensn.xh
ODFacet | Facet.xh
ODFacetIterator | FacetItr.xh
ODFocusModule | FocusMod.xh
ODFocusOwnerIterator | FocusOwn.xh
ODFocusSet | FocusSet.xh
ODFocusSetIterator | FocusItr.xh
ODFrame | Frame.xh
ODFrameFacetIterator | FrFaItr.xh
ODInfo | Info.xh
ODLink | Link.xh
ODLinkManager | LinkMgr.xh
ODLinkSource | LinkSrc.xh
ODLinkSpec | LinkSpec.xh
ODMenuBar | MenuBar.xh
ODNameSpace | NamSpac.xh
ODNameSpaceManager | NmSpcMg.xh
ODObject | ODObject.xh
ODObjectIterator | ObjctItr.xh
ODObjectNameSpace | ObjectNS.xh
ODPart | Part.xh
ODPersistentObject | PstObj.xh
ODPlatformTypeList | PfTypLs.xh
ODPlatformTypeListIterator | PfTLItr.xh
ODRefCntObject | RefCtObj.xh
ODSession | ODSessn.xh
ODSettingsExtension | Settings.xh
ODShape | Shape.xh
ODStorageSystem | ODStor.xh
ODStorageUnit | StorageU.xh
ODStorageUnitCursor | SUCursor.xh
ODStorageUnitRefIterator | SURefItr.xh
ODStorageUnitView | SUView.xh
ODTransform | Trnsform.xh
ODTranslation | Translt.xh
ODTypeList | TypeList.xh
ODTypeListIterator | TypLsItr.xh
ODUndo | Undo.xh
ODValueIterator | ValueItr.xh
ODValueNameSpace | ValueNS.xh
ODWindow | Window.xh
ODWindowIterator | WinIter.xh
ODWindowState | WinStat.xh

### Implicit Pointer Data Types

A data-type name beginning with "P" is a pointer to data of another type, unless defined otherwise in the header files. For example, PPartKindInfo is a pointer to data of type PartKindInfo.

In the data-type summary, Appendix A. "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 data types is dependent on the machine architecture. To be portable, applications must access data using the type definitions supplied for the environment in which they execute.

### Message Queues

Usually, when an application thread calls a Presentation Manager (PM) function, a message queue must be available for that thread. This means that, before calling the function, WinCreateMsgQueue must be called by the same thread.

Create a message queue for every thread that calls an OpenDoc method, because a PM function might be used by the methods you are calling.

### Stack Size

Existing 16-bit applications (small and tiny models) must have a 4KB stack available when they enter system calls; otherwise, the stack can overflow into the data area.

### C++ Considerations

This section contains several topics you should take into consideration if you are using C++.

#### C++ Header Files

Several of the typedefs have been changed in the C++ header files. For example, `unsigned char` in the C header files are `char` in the C++ header files.

#### PCSZ Data Type

OS/2 functions with parameters for type PSZ that do not modify the contents of the passed string, have been updated in the C++ header files as parameters of type PCSZ. The use of PCSZ data types allows for better optimization by the compiler and is more semantically compatible with C++. Existing code that calls functions with parameters of type PSZ continues to work correctly.

Note:

> The PCSZ data type is defined in the C++ header files included with this product. The use of the "const" keyword is not necessarily specific to C++. Certain C compilers support it as well.

> A smaller, faster executable is often produced if the data item passed in a parameter list is declared as "const."

> If the data item is declared as "const," then it must not be changed by the function.

If a function has a string as a parameter that is not changed by the function, the string parameter can be declared as a "const" string, or a PCSZ. PCSZ is defined in the C++ header files as a "const" pointer to a null-delimited string. The "const" means that the function does not change the contents of the string. The compiler simply passes a pointer to the string in the function parameter list. If the parameter is declared as a normal PSZ (not "const"), the compiler assumes that the function might change the string. Under these circumstances, the compiler adds code to make a copy of the string and then passes a pointer to the copy, rather than passing a pointer to the original string.

#### LINK386

The C++ compiler provides a dynamic link library to be used by LINK386 when generating error messages. This DLL converts a compiler-generated mangled name into the function prototype. If the DLL is not present, an error message is displayed, and LINK386 displays the compiler-generated mangled name in error messages.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]