SMPProgAdd - How to Use the SMP Programming Addendum
The SMP Programming Addendum is a detailed technical guide and reference for application programmers who wish to exploit the symmetric multiprocessor support in the OS/2 operating system. It gives reference information and code examples to enable you to write source code using OS/2 functions and tools.
Before you begin to use this information, it would be helpful to understand how you can:
- Expand the Contents to see all available topics
- Obtain additional information for a highlighted word or phrase
- Use action bar choices
- Use the programming information.
How to Use the Contents
When the Contents window first appears, some topics have a plus (+) sign beside them. The plus sign indicates that additional topics are available.
To expand the Contents if you are using a mouse, click on the plus sign. If you are using the keyboard, use the Up or Down Arrow key to highlight the topic, and press the plus (+) key. For example, File System has a plus sign beside it. To see additional topics for that heading, click on the plus sign or highlight that topic and press the plus (+) key.
To view a topic, double-click on the topic (or press the Up or Down Arrow key to highlight the topic, and then press the Enter key).
How to Obtain Additional Information
After you select a topic, the information for that topic appears in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words and phrases are highlighted in green letters, or in white letters on a black background. These are called hypertext terms. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word, and then press the Enter key. Additional information then appears in a window.
How to Use Action Bar Choices
Several choices are available for managing information presented in the OS/2 operating system SMP Programming Addendum. There are three pull-down menus on the action bar: the Services menu, the Options menu, and the Help menu.
The actions that are selectable from the Services menu operate on the active window currently displayed on the screen. These actions include the following:
- Bookmark
- Allows you to set a placeholder so you can retrieve information of interest to you.
When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty.
To set a bookmark, do the following:
- Select a topic from the Contents.
- When that topic appears, choose the Bookmark option from the Services pull-down.
- If you want to change the name used for the bookmark, type the new name in the field.
- Click on the Place radio button (or press the Up or Down Arrow key to select it).
- Click on OK (or select it and press Enter). The bookmark is then added to the bookmark list.
- Search
- Allows you to find occurrences of a word or phrase in the current topic, selected topics, or all topics.
You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics in the Contents list.
To search for a word or phrase in all topics, do the following:
- Choose the Search option from the Services pull-down.
- Type the word or words to be searched for.
- Click on All sections (or press the Up or Down Arrow keys to select it).
- Click on Search (or select it and press Enter) to begin the search.
- The list of topics where the word or phrase appears is displayed.
- Allows you to print one or more topics. You can also print a set of topics by first marking the topics in the Contents list.
To print the document Contents list, do the following:
- Choose Print from the Services pull-down.
- Click on Contents (or press the Up or Down Arrow key to select it).
- Click on Print (or select it and press Enter).
- The Contents list is printed on your printer.
- Copy
- Allows you to copy a topic that you are viewing to the System Clipboard or to a file that you can edit. You will find this particularly useful for copying syntax definitions and program samples into the application that you are developing.
You can copy a topic that you are viewing in two ways:
- Copy copies the topic that you are viewing into the System Clipboard. If you are using a Presentation Manager (PM) editor (for example, the System Editor) that copies or cuts (or both) to the System Clipboard, and pastes to the System Clipboard, you can easily add the copied information to your program source module.
- Copy to file copies the topic that you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using any editor. You will find TEXT.TMP in the directory where your viewable document resides.
To copy a topic, do the following:
- Expand the Contents list and select a topic.
- When the topic appears, choose Copy to file from the Services pull-down.
- The system puts the text pertaining to that topic into the temporary file named TEXT.TMP.
For information on one of the other choices in the Services pull-down, highlight the choice and press the F1 key.
The actions that are selectable from the Options menu allow you to change the way your Contents list is displayed. To expand the Contents and show all levels for all topics, choose Expand all from the Options pull-down. You can also press the Ctrl and * keys together. For information on one of the other choices in the Options pull-down, highlight the choice and press the F1 key.
The actions that are selectable from the Help menu allow you to select different types of help information. You can also press the F1 key for help information about the Information Presentation Facility (IPF).
How to Use the Programming Information
The SMP Programming Addendum consists of guide and reference information that provides a detailed description of each system function that has been added or changed to support the symmetric multiprocessing capabilities of OS/2.
Programming information is presented by component, such as Error Management, Exception Management, and File System, for example:
┌─────────────────────────────────────────┐
│ Contents │
├─────────────────────────────────────────┤
│ │
│ + Error Management │
│ + Exception Management │
│ + File System │
│ │
└─────────────────────────────────────────┘
By clicking on the plus sign beside "File System", you see an alphabetic list of the functions for the file system. Selecting a function takes you directly into the reference information for that function.
Units of reference information are presented in selectable multiple windows or viewports. A viewport is a Presentation Manager window that can be sized, moved, minimized, maximized, or closed. By selecting a unit (in this case, an entry on the Contents list), you will see two windows displayed:
┌────────────────────┬──────────────────────────┐ │ Unit Title │ Selection Title │ ├────────────────────┼──────────────────────────┤ │ Select an item │ │ │ │ │ │ Function Syntax │ │ │ Parameters │ │ │ Return Values │ │ │ Notes │ │ │ Example │ │ │ Related Functions │ │ │ Glossary │ │ │ │ │ └────────────────────┴──────────────────────────┘
The window on the left is the primary window. It contains a list of items that are always available to you. The window on the right is the secondary window. It contains a 'snapshot' of the unit information. For reference units (that is, function descriptions), this window contains the Function Syntax.
All of the information needed to understand a reference unit (or topic) is readily available to you through the primary window. The information is divided into discrete information groups, and only the appropriate information group appears for the topic that you are viewing.
The information groups for a reference unit (that is, a function description) can include the following:
Function Syntax Parameters Return Values Notes Example Related Functions Glossary
This list may vary. Some topics may be omitted when they do not apply.
Information groups are displayed in separate viewports that are stacked in a third window location that overlaps the secondary window. By selecting an item (information group) in the primary window, the item is displayed in the third window location, as follows:
┌────────────────┬─────────────┬──────────────────┐ │ Unit Title │ Selection │ Glossary │ ├────────────────┼─────────────┼──────────────────┤ │ Select an item │ │ Select a starting│ │ │ │ letter of │ │ . │ │ glossary terms │ │ . │ │ │ │ . │ │ A N │ │ . │ │ B O │ │ . │ │ C P │ │ Glossary │ │ . . │ │ │ │ . . │ │ │ │ . . │ │ │ │ M Z │ └────────────────┴─────────────┴──────────────────┘
By selecting successive items from the primary window, additional windows are displayed on top of the previous windows displayed in the third window location. For example, in a function description, Parameters and Return Values are items listed in the primary window. When selected, they appear one on top of the other in the third window location. Because of this, you may move the first selected (topmost) window to the left before selecting the next item. This allows simultaneous display of two related pieces of information from the "stack" of windows in the third window location, as follows:
┌────────────────┬──────────────┬─────────────────┐ │ Unit Title │ Parameters │ Return Values │ ├────────────────┼──────────────┼─────────────────┤ │ Select an item │ │ │ │ . │ │ │ │ . │ │ │ │ . │ │ │ │ Parameters │ │ │ │ Return Values │ │ │ │ . │ │ │ │ . │ │ │ │ . │ │ │ │ │ │ │ └────────────────┴──────────────┴─────────────────┘
Each window can be individually closed from its system menu. All windows are closed when you close the primary window.
Some secondary windows may have the appearance of a split screen. For example, an illustration may appear in the left half of the window, and scrollable, explanatory information may appear in the right half of the window. Because illustrations may not necessarily fit into the small window size on your screen, you may maximize the secondary window for better readability.