home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tolkit45.zip / os2tk45 / book / usetlkt.inf (.txt) < prev    next >
OS/2 Help File  |  1999-05-12  |  208KB  |  6,127 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. How To Use This Book ΓòÉΓòÉΓòÉ
  3.  
  4. The following topics explain how to use this book: 
  5.  
  6.      Using the Contents 
  7.      Getting Additional Information 
  8.      Using Menu Bar Choices 
  9.      Documentation Conventions 
  10.  
  11.  
  12. ΓòÉΓòÉΓòÉ 1.1. Using the Contents ΓòÉΓòÉΓòÉ
  13.  
  14. When the Contents window is first displayed, some topics have a plus (+) sign 
  15. beside them. The plus sign indicates that additional topics are available. 
  16.  
  17. To expand the Contents if you are using a mouse, click on the plus sign. If you 
  18. are using the keyboard, use the Up or Down Arrow key to highlight the topic, 
  19. and press the Plus (+) key. For example, Toolkit Roadmap has a plus sign beside 
  20. it. To see additional topics for that heading, click on the plus sign or 
  21. highlight that topic and press the Plus (+) key. 
  22.  
  23. To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  24. to highlight the topic, and then press Enter). 
  25.  
  26.  
  27. ΓòÉΓòÉΓòÉ 1.2. Getting Additional Information ΓòÉΓòÉΓòÉ
  28.  
  29. After you select a topic, the information for that topic is displayed in a 
  30. window. Highlighted words or phrases indicate that additional information is 
  31. available. You will notice that certain words and phrases are highlighted in 
  32. blue letters, or in white letters on a black background. These are called 
  33. hypertext terms. If you are using a mouse, double-click on the highlighted 
  34. word. If you are using a keyboard, press the Tab key to move to the highlighted 
  35. word, and then press Enter. Additional information is then displayed in a 
  36. window. 
  37.  
  38.  
  39. ΓòÉΓòÉΓòÉ 1.3. Using Menu Bar Choices ΓòÉΓòÉΓòÉ
  40.  
  41. Several choices are available for managing information presented in this book. 
  42. There are three menus on the menu bar: 
  43.  
  44.      Services menu 
  45.      Options menu 
  46.      Help menu 
  47.  
  48.  
  49. ΓòÉΓòÉΓòÉ 1.3.1. Services Menu ΓòÉΓòÉΓòÉ
  50.  
  51. The actions that are selectable from the Services menu operate on the active 
  52. window currently displayed on the screen. These actions include the following: 
  53.  
  54.      Search 
  55.      Print 
  56.      Bookmark 
  57.      Copy 
  58.  
  59.  
  60. ΓòÉΓòÉΓòÉ 1.3.1.1. Search ΓòÉΓòÉΓòÉ
  61.  
  62. Search enables you to find occurrences of a word or phrase in the current 
  63. topic, selected topics, or all topics. You can specify a word or phrase to be 
  64. searched. You can also limit the search to a set of topics by first marking the 
  65. topics in the Contents list. 
  66.  
  67. To search for a word or phrase in all topics, do the following: 
  68.  
  69.    1. Select Search from the Services menu. Type the word or words to be 
  70.       searched for. 
  71.  
  72.    2. Click on All sections or press the Up or Down Arrow keys to select it. 
  73.  
  74.    3. Click on Search (or select it and press Enter) to begin the search. 
  75.  
  76.    4. The list of topics where the word or phrase appears is displayed. 
  77.  
  78.  
  79. ΓòÉΓòÉΓòÉ 1.3.1.2. Print ΓòÉΓòÉΓòÉ
  80.  
  81. Print enables you to print one or more topics. You can also print a set of 
  82. topics by first marking the topics in the Contents list. To print the document 
  83. contents list do the following: 
  84.  
  85.    1. Select Print from the Services menu. 
  86.  
  87.    2. Click on Contents (or press the Up or Down Arrow key to select it). 
  88.  
  89.    3. Click on Print (or select it and press Enter). 
  90.  
  91.    4. The Contents list is printed on your printer. 
  92.  
  93.  
  94. ΓòÉΓòÉΓòÉ 1.3.1.3. Bookmark ΓòÉΓòÉΓòÉ
  95.  
  96. Bookmark enables you to set a placeholder so you can retrieve information of 
  97. interest to you. When you place a bookmark on a topic, it is added to a list of 
  98. bookmarks you have previously set. You can view the list, and you can remove 
  99. one or all bookmarks from the list. If you have not set any bookmarks, the list 
  100. is empty. To set a bookmark, do the following: 
  101.  
  102.    1. Select a topic from the Contents. 
  103.  
  104.    2. When that topic is displayed, select Bookmark from the Services menu. 
  105.  
  106.    3. If you want to change the name used for the bookmark, type the new name 
  107.       in the field. 
  108.  
  109.    4. Click on the Place radio button or press the Up or Down Arrow key to 
  110.       select it. 
  111.  
  112.    5. Click on OK and press Enter. The bookmark is then added to the bookmark 
  113.       list. 
  114.  
  115.  
  116. ΓòÉΓòÉΓòÉ 1.3.1.4. Copy ΓòÉΓòÉΓòÉ
  117.  
  118. Copy enables you to copy a topic that you are viewing to the System Clipboard 
  119. or to a file that you can edit. You will find this particularly useful for 
  120. copying syntax definitions and program samples into the application that you 
  121. are developing. 
  122.  
  123. You can copy a topic that you are viewing in two ways: 
  124.  
  125.      Copy copies the topic that you are viewing into the System Clipboard. If 
  126.       you are using a Presentation Manager editor (for example, the System 
  127.       Editor) that copies or cuts (or both) to the System Clipboard and pastes 
  128.       to the System Clipboard, you can easily add the copied information to 
  129.       your program source module. 
  130.  
  131.      Copy to file copies the topic that you are viewing into a temporary file 
  132.       named TEXT.TMP. You can later edit that file by using any editor. You 
  133.       will find TEXT.TMP in the directory where your viewable document resides. 
  134.  
  135.  To copy a topic, do the following: 
  136.  
  137.    1. Expand the Contents list and select a topic. 
  138.  
  139.    2. When the topic is displayed, select Copy to file from the Services menu. 
  140.  
  141.    3. The system puts the text pertaining to that topic into the temporary file 
  142.       named TEXT.TMP. 
  143.  
  144.  For information on one of the other choices in the Services menu, highlight 
  145.  the choice and press the F1 key. 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ 1.3.2. Options Menu ΓòÉΓòÉΓòÉ
  149.  
  150. The actions that are selectable from the Options menu allow you to change the 
  151. way your Contents list is displayed. To expand the Contents and show all levels 
  152. for all topics, choose Expand all from the Options menu. You can also press 
  153. Ctrl+*. For information on one of the other choices in the Options menu, 
  154. highlight the choice and press the F1 key. 
  155.  
  156.  
  157. ΓòÉΓòÉΓòÉ 1.3.3. Help Menu ΓòÉΓòÉΓòÉ
  158.  
  159. The actions that are selectable from the Help menu allow you to select 
  160. different types of help information. You can also press the F1 key for help 
  161. information about the Information Presentation Facility (IPF). 
  162.  
  163.  
  164. ΓòÉΓòÉΓòÉ 1.4. Documentation Conventions ΓòÉΓòÉΓòÉ
  165.  
  166. Throughout Using Your Toolkit, the following conventions distinguish the 
  167. different elements of text: 
  168.  
  169.  plain text                    Function names, structure names, data type 
  170.                                names, message names, enumerated types, and 
  171.                                constant names. 
  172.  
  173.  Initial capitalization        Key names, group-box controls, drop-down list 
  174.                                boxes, dialog windows, combo-boxes, single-line 
  175.                                entry (SLE) and multiple-line entry (MLE) 
  176.                                fields. 
  177.  
  178.  UPPERCASE                     File names and error codes. 
  179.  
  180.  monospace                     Programming examples and user input at the 
  181.                                command line prompt or into an entry field. 
  182.  
  183.  bold                          Push buttons, check boxes, radio buttons, spin 
  184.                                buttons, menu bar choices, and menu items. 
  185.  
  186.  italics                       Parameters, structure fields, titles of 
  187.                                documents, and first occurrences of words with 
  188.                                special meaning. 
  189.  
  190.  
  191. ΓòÉΓòÉΓòÉ 2. Introduction ΓòÉΓòÉΓòÉ
  192.  
  193. Welcome to the IBM Developer's Toolkit for OS/2 Warp (OS/2 Warp Toolkit). This 
  194. book documents the following: 
  195.  
  196.      Additions and updates made to the OS/2 Warp Toolkit as listed in the 
  197.       What's New section 
  198.  
  199.      Descriptions of online documentation, code samples, and tools 
  200.  
  201.      Programming considerations that have been changed or added 
  202.  
  203.      Toolkit roadmap that covers the folder hierarchy and the contents and 
  204.       directory structure 
  205.  
  206.      Toolkit support information that assists you in installing or using the 
  207.       OS/2 Warp Toolkit, or reporting suspected system defects as a result of 
  208.       installing the OS/2 Warp Toolkit 
  209.  
  210.  
  211. ΓòÉΓòÉΓòÉ 3. README ΓòÉΓòÉΓòÉ
  212.  
  213.  
  214. ΓòÉΓòÉΓòÉ 4. Toolkit Desktop Objects ΓòÉΓòÉΓòÉ
  215.  
  216. To restore your Toolkit Desktop objects, insert the CD or diskette that 
  217. contains the Toolkit Installation program (TKINSTAL.EXE), start the program, 
  218. and follow these steps: 
  219.  
  220.    1. Click on Options to open Installation options. 
  221.  
  222.    2. Deselect Install selected files and Write CONFIG.SYS updates to: (only 
  223.       Register WPS classes and Create desktop objects should be selected). 
  224.  
  225.    3. Click on OK to close Installation options. 
  226.  
  227.    4. Highlight the root (top-most) component in the component tree, and then 
  228.       fill in the Destination: field with the location of your Toolkit 
  229.       subdirectory. 
  230.  
  231.    5. Click on Install. 
  232.  
  233.  
  234. ΓòÉΓòÉΓòÉ 5. What's New ΓòÉΓòÉΓòÉ
  235.  
  236. What's New provides information about the latest release of the OS/2 Warp 
  237. Toolkit. 
  238.  
  239.      The following sections provide information about updates and additions: 
  240.  
  241.         -  TCP/IP Toolkit Enhancements 
  242.         -  New APIs in OS/2 Warp Server for e-business 
  243.         -  Debugging and Serviceability Enhancements 
  244.  
  245.      The following tools have been removed from the Toolkit: 
  246.  
  247.         -  IBM no longer supports SOM; however, the information about SOM 
  248.            remains in the Toolkit. 
  249.  
  250.         -  The ICAT Debugger is no longer included in the Toolkit; however, you 
  251.            can download the debugger from the following Web site: 
  252.  
  253.            http://service.boulder.ibm.com/icat/ 
  254.  
  255.         -  OpenDoc is no longer included in the Toolkit; however, information 
  256.            concerning OpenDoc is available at the following Web site: 
  257.  
  258.            http://www.software.ibm.com/ad/opendoc/ 
  259.  
  260.         -  The Universal Resource Editor (URE) is no longer included in the 
  261.            Toolkit.  This tool has been replaced by the Integrated Resource 
  262.            Editor (IRE), which is included in IBM C++ Professional Version 4.0. 
  263.            Information about this product is available at the following Web 
  264.            site: 
  265.  
  266.            http://www.ibmlink.ibm.com 
  267.  
  268.  You should also review Important Information  before using the tools and 
  269.  sample programs in the Toolkit. 
  270.  
  271.  
  272. ΓòÉΓòÉΓòÉ 5.1. TCP/IP Toolkit Enhancements ΓòÉΓòÉΓòÉ
  273.  
  274. The TCP/IP Toolkit has been upgraded to version 4.21. Enhancements to the 
  275. TCP/IP Toolkit are: 
  276.  
  277.      New APIs: 
  278.  
  279.         -  accept_and_recv() 
  280.  
  281.         -  send_file 
  282.  
  283.      A new 32-bit version of the ring-0 library (R0LIB32), which enables 
  284.       device drivers to call the new 32-bit networking kernel (socket.sys) 
  285.       without the 16-bit to 32-bit thunk layer. 
  286.  
  287.  For information about the new TCP/IP samples added to this Toolkit, refer to 
  288.  TCP/IP Samples . 
  289.  
  290.  
  291. ΓòÉΓòÉΓòÉ 5.2. New APIs in OS/2 Warp Server for e-business ΓòÉΓòÉΓòÉ
  292.  
  293. OS/2 Warp Server for e-business includes some new and some revised APIs.  These 
  294. APIs relate to control programming functions, particularly those that are 
  295. affected by Logical Volume Manager (LVM), and to performance and RAS functions. 
  296. For more information, refer to the online book, OS/2 Programming Guide and 
  297. Reference Addendum for OS/2 Warp Server for e-business. 
  298.  
  299.  
  300. ΓòÉΓòÉΓòÉ 5.3. Debugging and Serviceability ΓòÉΓòÉΓòÉ
  301.  
  302. Major enhancements to the system diagnostic tools (RAS Enhancements) are 
  303. provided in FixPak 35 for OS/2 Warp 3.0, FixPak 10 for OS/2 Warp 4.0, and OS/2 
  304. Warp Server for e-business. They provide major functional enhancements to the 
  305. System Trace and Process Dump facilities, a summary of which is given below. 
  306. Full details of these enhancements are provided in the following documents that 
  307. are included with the operating system: 
  308.  
  309.      OS2\SYSTEM\RAS\TRACE.DOC 
  310.  
  311.      OS2\SYSTEM\RAS\DTRACE.DOC 
  312.  
  313.      OS2\SYSTEM\RAS\PROCDUMP.DOC 
  314.  
  315.      OS2\SYSTEM\RAS\TRSPOOL.DOC 
  316.  
  317.  Detailed information on debugging techniques and the use of system debugging 
  318.  is provided in The OS2 Debugging Handbook (SG244640.INF), which is distributed 
  319.  with this TOOLKIT. 
  320.  
  321.  Any changes and enhancements to serviceability tools introduced with a FixPak 
  322.  are documented \OS2\INSTALL\README.DBG. 
  323.  
  324.  
  325. ΓòÉΓòÉΓòÉ 6. Important Information ΓòÉΓòÉΓòÉ
  326.  
  327. This section describes some items that can affect your development efforts when 
  328. using the OS/2 Toolkit. 
  329.  
  330.      Compiling with IBM C/2 
  331.      Compiling with IBM VisualAge C++ for OS/2 
  332.      Installing IBM VisualAge C++ for OS/2 
  333.      VoiceType Developer's Toolkit Updates 
  334.  
  335.  
  336. ΓòÉΓòÉΓòÉ 6.1. Compiling with IBM C/2 ΓòÉΓòÉΓòÉ
  337.  
  338. The OS/2 Toolkit for OS/2 Warp Version 4.0  and later versions of the Toolkit 
  339. are not intended to be used with the IBM C/2, Version 1.1 compiler. If you 
  340. choose to use that compiler, you should use version 1.3 of the Toolkit. 
  341.  
  342. The OS/2 Warp Toolkit is intended to be used with the IBM VisualAge C++ 
  343. compiler. 
  344.  
  345.  
  346. ΓòÉΓòÉΓòÉ 6.2. Compiling with IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
  347.  
  348. The latest version of the C Set ++ compiler (now called VisualAge C++) has been 
  349. released. VisualAge C++ includes its own version of the OS/2 Warp Toolkit, 
  350. which includes updated sample makefiles. Changes to the sample makefiles relate 
  351. to the new linker (ILINK) and to the new library (CPPOM30.LIB). 
  352.  
  353. With this version of the OS/2 Warp Toolkit, the same sample makefile changes 
  354. have been made so that you can use VisualAge C++. 
  355.  
  356. You can compile the samples included with the OS/2 Warp Toolkit with C Set ++ 
  357. (using LINK386) by changing any reference to CPPOM30.LIB to: 
  358.  
  359. DDE4MBS.LIB
  360.  
  361. and changing any reference to ILINK to: 
  362.  
  363. LINK386
  364.  
  365. Note:  The /nofree option must be removed from the LINK386 statement. 
  366.  
  367.  
  368. ΓòÉΓòÉΓòÉ 6.3. Installing IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
  369.  
  370. Installing your compiler first and the OS/2 Warp Toolkit last prevents 
  371. unexpected results due to environment variable changes (automatic updates to 
  372. CONFIG.SYS). 
  373.  
  374. To avoid a downlevel SOM Runtime installed by the VisualAge C++ 3.0 compiler, 
  375. follow these steps for installation: 
  376.  
  377.    1. Start the installation program for VisualAge C++ 3.0. 
  378.  
  379.    2. Deselect the OS/2 Warp Toolkit entries in the installation screen and 
  380.       proceed with the installation. 
  381.  
  382.    3. After completing the installation of VisualAge C++ but before restarting 
  383.       the system, edit CONFIG.SYS and modify the LIBPATH statement by moving 
  384.       x:\ IBMCPP\DLL after y:\OS2\DLL, where x is the drive where the VisualAge 
  385.       C++ compiler is installed and y is the drive where the system files for 
  386.       OS/2 Warp Version 4 or later are installed. This prevents the SOM Runtime 
  387.       installed by VisualAge C++ from overwriting the SOM Runtime shipped with 
  388.       OS/2 Warp. 
  389.  
  390.    4. Save the modified CONFIG.SYS and restart your system. 
  391.  
  392.    5. Install the the OS/2 Toolkit and restart your system. 
  393.  
  394.  
  395. ΓòÉΓòÉΓòÉ 6.4. VoiceType Developer's Toolkit Updates ΓòÉΓòÉΓòÉ
  396.  
  397. The header files and libraries, samples, tools, and documentation associated 
  398. with the VoiceType Developer's Toolkit are located in the \TOOLKIT\SPEECH 
  399. subdirectories. 
  400.  
  401. The VoiceType Developer's Toolkit includes: 
  402.  
  403.      Grammar compiler and its associated documentation 
  404.      Utilities to be used with grammars 
  405.      SMAPI.DLL 
  406.  
  407.  
  408. ΓòÉΓòÉΓòÉ 7. Toolkit Contents ΓòÉΓòÉΓòÉ
  409.  
  410. This section describes the contents of the OS/2 Warp Toolkit. It contains the 
  411. following topics: 
  412.  
  413.      Toolkit Roadmap -- provides the directory hierarchy and the folder 
  414.       hierarchy of the Toolkit. 
  415.  
  416.      Header Files -- describes special programming considerations for various 
  417.       header files included with the OS/2 Warp Toolkit. 
  418.  
  419.      Sample Programs -- provides descriptions of the code samples that are 
  420.       included in the OS/2 Warp Toolkit. 
  421.  
  422.      Tools -- provides descriptions of the Presentation Manager, Multimedia, 
  423.       SOM, TCP/IP, Workplace Shell, and XPG4 tools. It also introduces you to 
  424.       the interface that installs the debug kernel, symbol files, and debug 
  425.       version of PM and Workplace Shell and describes tools that support your 
  426.       debugging efforts. 
  427.  
  428.      Online Documentation -- describes the online books of the OS/2 Warp 
  429.       Toolkit. 
  430.  
  431.  
  432. ΓòÉΓòÉΓòÉ 7.1. Toolkit Roadmap ΓòÉΓòÉΓòÉ
  433.  
  434. The tools, samples, and technical documentation in the OS/2 Warp Toolkit are 
  435. available in two ways.  You can access them through the Toolkit folder and its 
  436. subfolders on the Desktop, or you can access them using an OS/2 window or OS/2 
  437. full-screen session and changing into the \TOOLKIT subdirectory and its 
  438. subdirectories. 
  439.  
  440.  
  441. ΓòÉΓòÉΓòÉ 7.1.1. Directory Hierarchy ΓòÉΓòÉΓòÉ
  442.  
  443. The OS/2 Warp Toolkit package has the following directory structure: 
  444.  
  445.   \TOOLKIT     - Root subdirectory for the Toolkit
  446.     Γöé
  447.     Γö£ΓöÇ\BIN     - Programming tools
  448.     Γö£ΓöÇ\BITMAP  - Sample multimedia bitmaps
  449.     Γö£ΓöÇ\BOOK    - Online technical information
  450.     Γö£ΓöÇ\DLL     - Toolkit dynamic link library (DLL) files
  451.     Γö£ΓöÇ\H       - C, C++, and DTS header files
  452.     Γö£ΓöÇ\HELP    - Toolkit help (HLP) files
  453.     Γö£ΓöÇ\ICON    - Toolkit icon (ICO) files
  454.     Γö£ΓöÇ\IDL     - Workplace Shell interface definition language (IDL) files
  455.     Γö£ΓöÇ\INC     - Assembler header (INC) files
  456.     Γö£ΓöÇ\IPFC    - Information Presentation Facility Compiler (IPFC) files
  457.     Γö£ΓöÇ\LIB     - Import library (LIB) files
  458.     Γö£ΓöÇ\SAMPLES - Samples  programs
  459.     Γö£ΓöÇ\SOM     - SOM subdirectories
  460.     ΓööΓöÇ\SPEECH  - VoiceType Developer's Toolkit
  461.  
  462.  
  463. ΓòÉΓòÉΓòÉ 7.1.2. Folder Hierarchy ΓòÉΓòÉΓòÉ
  464.  
  465. The OS/2 Warp Toolkit package has the following Workplace Shell folder 
  466. hierarchy: 
  467.  
  468.  IBM Developer's Toolkit            - Root folder of the Toolkit
  469.  for OS/2 Warp                        (contains the README file and the
  470.   Γöé                                   other Toolkit folders)
  471.   Γöé
  472.   Γö£ΓöÇDevelopment Tools               - Programming tools
  473.   Γö£ΓöÇMultimedia Bitmaps              - Sample multimedia bitmaps
  474.   Γö£ΓöÇMultimedia Sample Programs      - Multimedia sample programs
  475.   Γö£ΓöÇOpen32 Samples                  - Open32 sample programs
  476.   Γö£ΓöÇOpenGL Samples                  - OpenGL sample programs
  477.   Γö£ΓöÇOS/2 Sample Programs            - Control Program sample programs
  478.   Γö£ΓöÇPM Sample Programs              - Presentation Manager (PM) sample programs
  479.   Γö£ΓöÇREXX Sample Programs            - REXX sample programs
  480.   Γö£ΓöÇToolkit Information             - Online technical books
  481.   Γö£ΓöÇVoiceType Developer's Toolkit   - VoiceType tools, samples, and online books
  482.   ΓööΓöÇWorkplace Shell Sample Programs - Workplace Shell (WPS) sample programs
  483.  
  484.  
  485. ΓòÉΓòÉΓòÉ 7.2. Header Files ΓòÉΓòÉΓòÉ
  486.  
  487. You should be aware of special programming considerations in the following sets 
  488. of header files: 
  489.  
  490.      Control Program 
  491.      Multimedia 
  492.      OS/2 
  493.  
  494.  Note:  For compatibility with VisualAge C++, the #pragma checkout directives 
  495.         in all header files have been changed to #pragma info. The #pragma 
  496.         checkout directive is no longer supported by VisualAge C++. Because the 
  497.         #pragma info directive provides similar function to #pragma checkout, 
  498.         the header file changes should not affect code that uses the header 
  499.         files. If you use the #pragma checkout directive with VisualAge C++, it 
  500.         generates an "unsupported pragma" error for both C and C++ compilers. 
  501.         Refer to the VisualAge C++ Language Reference for more details. 
  502.  
  503.  
  504. ΓòÉΓòÉΓòÉ 7.2.1. Control Program Header Files ΓòÉΓòÉΓòÉ
  505.  
  506. DosSetDOSProperty() and DosQueryDOSProperty() in BSEDOS.H are not supported. Do 
  507. not use these functions. 
  508.  
  509.  
  510. ΓòÉΓòÉΓòÉ 7.2.2. Multimedia Header Files ΓòÉΓòÉΓòÉ
  511.  
  512. The multimedia header files listed below are delivered in two different 
  513. versions. One version uses conventions compatible with the standard OS/2 
  514. header-file format. The other version uses conventions compatible with 
  515. Microsoft Windows header files. The Windows-style headers are currently 
  516. included for compatibility with earlier multimedia applications, but will be 
  517. removed from the Toolkit in the future. 
  518.  
  519. Use the OS/2-style header files for new applications and modify the source code 
  520. for existing applications that use the Windows-style headers. 
  521.  
  522.  Windows-Style       OS/2-Style 
  523.  CDAUDIO.H           CDAUDOS2.H 
  524.  MCIDRV.H            MMDRVOS2.H 
  525.  MIDI.H              MIDIOS2.H 
  526.  MMIO.H              MMIOOS2.H 
  527.  MMSYSTEM.H          MCIOS2.H 
  528.  
  529.  
  530. ΓòÉΓòÉΓòÉ 7.2.3. OS/2 Header Files ΓòÉΓòÉΓòÉ
  531.  
  532. Instead of using the SELECTOROF macro in the OS2DEF.H header file, use one of 
  533. the following two macros to obtain the selector of a 16:16 address : 
  534.  
  535.   #define SELECTOROF(p)   (((PUSHORT)&(p))[1])
  536.   OR
  537.   #define SELECTOROF(p)   ((ULONG)(p)>>16)
  538.  
  539. If you use the selector returned from one of the above macros with the OFFSETOF 
  540. and MAKEP macros in the OS2DEF.H header file, you can successfully convert a 
  541. 16:16 address to a 0:32 address. 
  542.  
  543.  
  544. ΓòÉΓòÉΓòÉ 7.3. Sample Programs ΓòÉΓòÉΓòÉ
  545.  
  546. This section describes the sample programs available with the OS/2 Warp 
  547. Toolkit. 
  548.  
  549. The sample programs are categorized as follows: 
  550.  
  551.      BIDI (Bidirectional) 
  552.      LAN Server 
  553.      Multimedia 
  554.      Open32 
  555.      OpenGL 
  556.      OS/2 
  557.      Presentation Manager 
  558.      Problem Determination 
  559.      REXX 
  560.      TCP/IP 
  561.      Workplace Shell 
  562.  
  563.  Most sample programs are written in C language and demonstrate the use of the 
  564.  functions of the control program (CP, base OS/2 operating system), the PM 
  565.  interface, the multimedia (MM) interface, and the Workplace Shell (WPS). 
  566.  
  567.  Each sample program serves as a template that can be easily modified for your 
  568.  own purposes. These programs let you investigate the best way to implement 
  569.  your own application requirements. 
  570.  
  571.  Some of the sample programs require specific hardware devices. When 
  572.  appropriate, the hardware is listed following the program descriptions. 
  573.  Without these devices, you can still compile and run the sample programs; 
  574.  however, you might not receive the full effect of the program. For example, if 
  575.  a multimedia sample program has audio, you will not hear it unless you have an 
  576.  audio adapter supported by OS/2 multimedia and speakers installed. 
  577.  
  578.  Most samples also contain the overhead routines necessary to create a PM 
  579.  application, as well as stubs for the basic menu items that all applications 
  580.  should have. 
  581.  
  582.  There are many comments within the source code that clarify technical 
  583.  information. 
  584.  
  585.  Note:  Names of the sample programs, in most cases, correspond to their 
  586.         Toolkit subdirectory names. 
  587.  
  588.  
  589. ΓòÉΓòÉΓòÉ 7.3.1. Starting Sample Programs ΓòÉΓòÉΓòÉ
  590.  
  591. There are two ways to start a sample program: 
  592.  
  593.      From the Desktop: 
  594.  
  595.       When installed, all sample programs (with the exception of the 
  596.       bidirectional samples, TCP/IP samples, Problem Determination samples, LAN 
  597.       Server samples, some of the Multimedia samples, and some of the Workplace 
  598.       Shell samples) appear in the sample programs folders located within the 
  599.       Toolkit folder. To start a sample program, open the Toolkit folder, open 
  600.       the folder representing the type of samples you wish to execute, and then 
  601.       select the appropriate sample program. 
  602.  
  603.      From an OS/2 command prompt: 
  604.  
  605.       Change to the subdirectory where the sample is located, type the name of 
  606.       the executable file and press Enter. 
  607.  
  608.  Most samples include a description file (or makefile) that you can use to 
  609.  build the sample yourself. The name of the makefile is either MAKEFILE or 
  610.  filename.MAK, where filename refers to the name of the sample. To build the 
  611.  sample, 
  612.  
  613.    1. Go to an OS/2 command prompt and change to the subdirectory where the 
  614.       makefile is located. 
  615.  
  616.       You must execute these commands from the subdirectory where the makefile 
  617.       is located in order to build the sample correctly. 
  618.  
  619.    2. Enter one of the following, depending on the name of the makefile: 
  620.  
  621.           When the name of the makefile is MAKEFILE, type: 
  622.  
  623.                         NMAKE
  624.  
  625.           When the name of the makefile is filename.MAK, type: 
  626.  
  627.                         NMAKE /f filename.MAK
  628.  
  629.  For information about the NMAKE tool, refer to the Tools Reference. 
  630.  
  631.  Note:  The makefile assumes that you are using the IBM VisualAge C++ for OS/2 
  632.         compiler for code compilation. 
  633.  
  634.  
  635. ΓòÉΓòÉΓòÉ 7.3.2. BIDI Sample Programs ΓòÉΓòÉΓòÉ
  636.  
  637. These samples demonstrate the use of the Bidirectional Language support 
  638. available in the Arabic and Hebrew versions of OS/2. There are two sets of 
  639. samples provided: one set for the Arabic language and the other set for the 
  640. Hebrew language. For both languages, there are two samples: 
  641.  
  642.      STYLE 
  643.      TELDIR 
  644.  
  645.  Note:  Programs that use the bidirectional support functions will run only on 
  646.         the Arabic and Hebrew versions of the OS/2 operating system.  These are 
  647.         currently the only versions of the operating system that support the 
  648.         bidirectional support functions. 
  649.  
  650.  
  651. ΓòÉΓòÉΓòÉ 7.3.2.1. STYLE Sample Program ΓòÉΓòÉΓòÉ
  652.  
  653. STYLE is a sample program that demonstrates the bidirectional language support 
  654. features of PM controls and other system components. 
  655.  
  656. Note:  The Arabic versions of this sample (located in 
  657.        \TOOLKIT\SAMPLES\BIDI\ARABIC), require the Arabic version of OS/2 to 
  658.        run, and the Hebrew versions of this sample (located in 
  659.        \TOOLKIT\SAMPLES\BIDI\HEBREW), require the Hebrew version of OS/2 to 
  660.        run. 
  661.  
  662.  
  663. ΓòÉΓòÉΓòÉ 7.3.2.2. TELDIR Sample Program ΓòÉΓòÉΓòÉ
  664.  
  665. TELDIR is a simple bilingual telephone directory application that demonstrates 
  666. how language and orientation selections can be set dynamically by an 
  667. application that uses bidirectional functions. 
  668.  
  669. Note:  The Arabic versions of this sample require the Arabic version of OS/2 to 
  670.        run, and the Hebrew versions of this sample require the Hebrew version 
  671.        of OS/2 to run. 
  672.  
  673.  
  674. ΓòÉΓòÉΓòÉ 7.3.3. Device Driver Sample Programs ΓòÉΓòÉΓòÉ
  675.  
  676. Physical device driver (PDD) and virtual device driver (VDD) samples are not 
  677. included in the OS/2 Warp Toolkit. See the Developer Connection Device Driver 
  678. Kit for OS/2 for device driver samples. 
  679.  
  680.  
  681. ΓòÉΓòÉΓòÉ 7.3.4. LAN Server Sample Programs ΓòÉΓòÉΓòÉ
  682.  
  683. The LAN Server sample programs are as follows: 
  684.  
  685.      ACCESS32 - Access Control Profile Sample 
  686.      ALIAS32 - File Resource Alias Sample 
  687.      FILEEN32 - Server Open Files Sample 
  688.      MESSAG32 - Network Message Sample 
  689.      MLOGON32 - Network Logon Sample 
  690.      SADMIN32 - Server Administration Sample 
  691.      USER32 - User Account Sample 
  692.  
  693.  
  694. ΓòÉΓòÉΓòÉ 7.3.4.1. ACCESS32 ΓòÉΓòÉΓòÉ
  695.  
  696. ACCESS32 (located in \TOOLKIT\SAMPLES\LANSERV\ACCESS32) returns all the access 
  697. control profiles (ACPs) for a particular resource. You may alter any given ACP 
  698. by specifying the user and the new permissions. 
  699.  
  700. ACCESS32 demonstrates how to use the following NetAPI functions: 
  701. Net32AccessAdd, Net32AccessGetInfo, and Net32AccessSetInfo. 
  702.  
  703. This program can operate both locally and remotely. The machine running this 
  704. program must be logged on to the LAN with administrator authority. 
  705.  
  706.  
  707. ΓòÉΓòÉΓòÉ 7.3.4.1.1. Starting ACCESS32 ΓòÉΓòÉΓòÉ
  708.  
  709. To query a resource's ACP, type: 
  710.  
  711. access32 <resource>
  712.  
  713. To change the ACP for a user, type: 
  714.  
  715. access32 <resource> <name:permissions> <name:permissions> ...
  716.  
  717.  
  718. ΓòÉΓòÉΓòÉ 7.3.4.2. ALIAS32 ΓòÉΓòÉΓòÉ
  719.  
  720. ALIAS32 (located in \TOOLKIT\SAMPLES\LANSERV\ALIAS32) adds a file resource 
  721. alias and shares it, gives the USERS group read-only access to the resource, 
  722. and adds a directory limit to the resource. 
  723.  
  724. ALIAS32 demonstrates how to use the following NetAPI functions: 
  725.  
  726.       Net32WkstaGetInfo 
  727.       Net32ServerEnum2 
  728.       Net32GetDCName 
  729.       Net32AliasAdd 
  730.       Net32AliasDel 
  731.       Net32ShareAdd 
  732.       Net32AccessAdd 
  733.       Net32AccessGetInfo 
  734.       Net32AccessSetInfo 
  735.       Net32DASDAdd 
  736.  
  737.  
  738. ΓòÉΓòÉΓòÉ 7.3.4.2.1. Starting ALIAS32 ΓòÉΓòÉΓòÉ
  739.  
  740. To start ALIAS32 from a command line, type: 
  741.  
  742. alias32 aliasname resourcename
  743.  
  744. or 
  745.  
  746. alias32 aliasname servername resourcename
  747.  
  748. where: 
  749.  
  750.  aliasname           Is an 8-byte name that is not currently in use. 
  751.  
  752.  servername          Specifies the server that the alias resource resides on. 
  753.                      If not specified, it is assumed that the alias resource 
  754.                      resides on the local machine. 
  755.  
  756.  resourcename        Is a fully qualified path name. 
  757.  
  758.  ALIAS32 checks that the device is shared and returns basic information on the 
  759.  device type. 
  760.  
  761.  
  762. ΓòÉΓòÉΓòÉ 7.3.4.3. FILEEN32 ΓòÉΓòÉΓòÉ
  763.  
  764. FILEEN32 (located in \TOOLKIT\SAMPLES\LANSERV\FILEEN32) returns information on 
  765. open files on a specific server. You can choose to view a list of all open 
  766. files or to restrict the list by device path or user. You can leave both the 
  767. path and the user ID unspecified to get information on all files opened by all 
  768. users on the specified server. 
  769.  
  770. FILEEN32 demonstrates how to use the following NetAPI function: Net32FileEnum2. 
  771.  
  772.  
  773. ΓòÉΓòÉΓòÉ 7.3.4.3.1. Starting FILEEN32 ΓòÉΓòÉΓòÉ
  774.  
  775. To start FILEEN32 for a remote server, type: 
  776.  
  777. fileen32 servername basepath
  778.  
  779. To start FILEEN32 for a local server, type: 
  780.  
  781. fileen32 basepath username
  782.  
  783. where: 
  784.  
  785.  servername          Indicates the machine where open files will be enumerated. 
  786.                      If a  servername is specified, it must be the first 
  787.                      parameter specified.  If no servername is specified, open 
  788.                      files at the local server will be enumerated. 
  789.  
  790.  basepath            Is in the form of: 
  791.  
  792.                                           drive:\pathname
  793.  
  794.                      Only open files matching this basepath will be enumerated. 
  795.                      If basepath is not specified, all open files are 
  796.                      enumerated. 
  797.  
  798.  username            Is the name of an existing user.  If username is 
  799.                      specified, only files opened by this user are enumerated. 
  800.                      The username must be specified as the last parameter. 
  801.  
  802.  If no parameters are specified, all open files at the local server are 
  803.  enumerated. 
  804.  
  805.  This program must be run by an administrator.  The opened files that are to be 
  806.  listed must be on a redirected drive on the target server. 
  807.  
  808.  
  809. ΓòÉΓòÉΓòÉ 7.3.4.4. MESSAG32 ΓòÉΓòÉΓòÉ
  810.  
  811. MESSAG32 (located in \TOOLKIT\SAMPLES\LANSERV\MESSAG32) is designed to send 
  812. simple messages through the messenger service.  You can send messages from the 
  813. local machine or a remote server.  You can send messages to specific users or a 
  814. domain group, or broadcast to an entire LAN. 
  815.  
  816. MESSAG32 uses Net32MessageBufferSend to send the message. 
  817.  
  818.  
  819. ΓòÉΓòÉΓòÉ 7.3.4.4.1. Starting MESSAG32 ΓòÉΓòÉΓòÉ
  820.  
  821. To start MESSAG32 from the command line, type: 
  822.  
  823. messag32
  824.  
  825. MESSAG32 prompts the user for where the message should be sent from: 
  826.  
  827. 1 - the local machine
  828. 2 - a remote server
  829.  
  830. If the message is being sent from a remote server, MESSAG32 prompts the user 
  831. for a servername.  MESSAG32 then prompts the user for who the message should be 
  832. sent to as follows: 
  833.  
  834. 1 - a user
  835. 2 - a domain
  836. 3 - all the requesters on the LAN
  837.  
  838. If the message is being sent to a user or domain, MESSAG32 prompts the user for 
  839. the name of the user or domain to send the message to. Finally, MESSAG32 
  840. prompts the user to enter a text string for the message. 
  841.  
  842.  
  843. ΓòÉΓòÉΓòÉ 7.3.4.5. MLOGON32 ΓòÉΓòÉΓòÉ
  844.  
  845. MLOGON32 (located in \TOOLKIT\SAMPLES\LANSERV\MLOGON32) logs on a user, waits 
  846. for the user to press the Spacebar, and logs off the user.  The user name, 
  847. password (if required), and domain name are passed as command line parameters 
  848. to the program. 
  849.  
  850.  
  851. ΓòÉΓòÉΓòÉ 7.3.4.5.1. Starting MLOGON32 ΓòÉΓòÉΓòÉ
  852.  
  853. To start MLOGON32 from the command line, type: 
  854.  
  855. mlogon32 username password domainname
  856.  
  857. or 
  858.  
  859. mlogon32 username domainname
  860.  
  861.  
  862. ΓòÉΓòÉΓòÉ 7.3.4.6. SADMIN32 ΓòÉΓòÉΓòÉ
  863.  
  864. SADMIN32 (located in \TOOLKIT\SAMPLES\LANSERV\SADMIN32) executes a command on a 
  865. remote or local server. The command to be executed on the server is passed as a 
  866. command line parameter to this program, but it must reside on a disk visible to 
  867. the target server. 
  868.  
  869. SADMIN32 demonstrates how to use NetServerAdminCommand, which is a NetAPI 
  870. function. 
  871.  
  872.  
  873. ΓòÉΓòÉΓòÉ 7.3.4.6.1. Starting SADMIN32 ΓòÉΓòÉΓòÉ
  874.  
  875. To start SADMIN32 from the command line, type: 
  876.  
  877. sadmin32 \\targetservername command
  878.  
  879.  
  880. ΓòÉΓòÉΓòÉ 7.3.4.7. USER32 ΓòÉΓòÉΓòÉ
  881.  
  882. USER32 (located in \TOOLKIT\SAMPLES\LANSERV\USER32) is designed to access and 
  883. control user account information. USER32 can display information about a user, 
  884. delete a user, or create a new user.  When a new user is created, USER32 
  885. creates a new alias, gives the user access to it, and makes it a logon 
  886. assignment for the user; creates a new group and adds the user to it; creates a 
  887. private application definition and assigns that too to the user. 
  888.  
  889. USER32 demonstrates how to use the following NetAPI functions: 
  890.  
  891.       Net32AccessAdd 
  892.       Net32AccessGetInfo 
  893.       Net32AccessSetInfo 
  894.       Net32AliasAdd 
  895.       Net32AliasDel 
  896.       Net32AliasGetInfo 
  897.       Net32AppAdd 
  898.       Net32GetDCName 
  899.       Net32GroupAdd 
  900.       Net32GroupAddUser 
  901.       Net32GroupDel 
  902.       Net32GroupGetInfo 
  903.       Net32ServerEnum2 
  904.       Net32WkstaGetInfo 
  905.       Net32UserAdd 
  906.       Net32UserDCDBInit 
  907.       Net32UserDel 
  908.       Net32UserGetGroups 
  909.       Net32UserGetInfo 
  910.       Net32UserGetLogonAsn 
  911.       Net32UserSetAppSel 
  912.       Net32UserSetLogonAsn 
  913.  
  914.  NetStatisticsGet2 retrieves information from both the requester and the server 
  915.  portions of a server machine.  Note that these two sets of information, even 
  916.  when they are in the same machine, are quite different. 
  917.  
  918.  
  919. ΓòÉΓòÉΓòÉ 7.3.4.7.1. Starting USER32 ΓòÉΓòÉΓòÉ
  920.  
  921. To display information about a user, type: 
  922.  
  923. user32 username
  924.  
  925. To delete a user, type: 
  926.  
  927. user32 username /DELETE
  928.  
  929. To create a new user, type: 
  930.  
  931. user32 username /ADD
  932.  
  933. where username is the user ID of the account. 
  934.  
  935.  
  936. ΓòÉΓòÉΓòÉ 7.3.5. Multimedia Sample Programs ΓòÉΓòÉΓòÉ
  937.  
  938. The Multimedia sample programs are as follows: 
  939.  
  940.      ADMCT 
  941.      ASYMREC 
  942.      AVCINST 
  943.      BEEHIVE 
  944.      CAPSAMP 
  945.      CAPTION 
  946.      CASECONV 
  947.      CDMCIDRV 
  948.      Control File Templates 
  949.      CLOCK 
  950.      CODEC 
  951.      DAUDIO 
  952.      DIVE 
  953.      DOUBPLAY 
  954.      DUET1 
  955.      DUET2 
  956.      FSDIVE 
  957.      FSSHT 
  958.      MCD Command Tables 
  959.      MCDTEMP 
  960.      MCISPY 
  961.      MCISTRNG 
  962.      MIDISAMP 
  963.      MMBROWSE 
  964.      MMOTTK 
  965.      MOVIE 
  966.      RECORDER 
  967.      Short Control File Templates 
  968.      SHRC 
  969.      TUNER 
  970.      ULTIEYES 
  971.      ULIOT 
  972.  
  973.  
  974. ΓòÉΓòÉΓòÉ 7.3.5.1. ADMCT Sample Program ΓòÉΓòÉΓòÉ
  975.  
  976. ADMCT (located in \TOOLKIT\SAMPLES\MM\ADMCT) is an example of a media control 
  977. driver (MCD) that demonstrates how to control a streaming device. Streaming 
  978. devices use the services of the sync/stream manager (SSM) of OS/2 multimedia to 
  979. control the data stream from a source location to a target location. 
  980.  
  981.  
  982. ΓòÉΓòÉΓòÉ 7.3.5.2. ASYMREC Sample Program ΓòÉΓòÉΓòÉ
  983.  
  984. ASYMREC (located in \TOOLKIT\SAMPLES\MM\ASYMREC) illustrates how to include 
  985. asymmetric recording function in your multimedia application. Modules include 
  986. source code extracted from the Video IN recorder application, which enables 
  987. frame-step recording using Ultimotion compression techniques. 
  988.  
  989.  
  990. ΓòÉΓòÉΓòÉ 7.3.5.3. AVCINST I/O Procedure Sample ΓòÉΓòÉΓòÉ
  991.  
  992. AVCINST (located in \TOOLKIT\SAMPLES\MM\AVCINST) illustrates how an application 
  993. can install and remove an I/O procedure to use multimedia input/output (MMIO) 
  994. file services. The AVC I/O procedure installation sample is a simple PM 
  995. application that enables you to install or remove the audio AVC I/O procedure, 
  996. AVCAPROC.DLL. 
  997.  
  998. Hardware requirements: 
  999.  
  1000.      Computer capable of running OS/2 Warp 
  1001.  
  1002.  Software requirements: 
  1003.  
  1004.      OS/2 Warp 
  1005.      Multimedia support 
  1006.  
  1007.  
  1008. ΓòÉΓòÉΓòÉ 7.3.5.4. BEEHIVE Sample Program ΓòÉΓòÉΓòÉ
  1009.  
  1010. BEEHIVE demonstrates the power of compiled sprites by comparing the performance 
  1011. of a typical sprite algorithm against a compiled sprite. 
  1012.  
  1013. When the application first starts, it will display a single sprite moving in a 
  1014. random path around the application window. You can add sprites by holding down 
  1015. the H key. As the sprite count increases, the effects on the frame rate will 
  1016. become evident. The actual frame rate will be displayed on the title bar. 
  1017.  
  1018. You will be able to switch the application from compiled sprites to normal 
  1019. sprites using a menu. As the number of sprites increases, the difference in 
  1020. performance from compiled to normal sprites becomes more dramatic. 
  1021.  
  1022. While DIVE offers a high-performance API for blitting images to the screen, it 
  1023. was not designed for implementing sprites. BEEHIVE demonstrates a technique for 
  1024. implementing high-performance sprites in an OS/2 Warp/DIVE environment. The 
  1025. source code provided offers a good starting point for building a 
  1026. high-performance sprite engine. 
  1027.  
  1028. Hardware Requirements: 
  1029.  
  1030.      Computer capable of running OS/2 Warp 
  1031.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  1032.  
  1033.  Software Requirements: 
  1034.  
  1035.      OS/2 Warp Version 3 or later 
  1036.      Multimedia support 
  1037.  
  1038.  
  1039. ΓòÉΓòÉΓòÉ 7.3.5.4.1. Starting BEEHIVE ΓòÉΓòÉΓòÉ
  1040.  
  1041. You can start BEEHIVE in two ways: 
  1042.  
  1043.      From the command line, change to the TOOLKIT\SAMPLES\MM\BEEHIVE 
  1044.       subdirectory and type: 
  1045.  
  1046.               BEEHIVE
  1047.  
  1048.      From the Desktop, open the Toolkit folder and then: 
  1049.  
  1050.         1. Open the Multimedia Samples folder. 
  1051.  
  1052.         2. Open the Video Samples folder. 
  1053.  
  1054.         3. Double-click on Beehive. 
  1055.  
  1056.  
  1057. ΓòÉΓòÉΓòÉ 7.3.5.5. CAPSAMP Sample Program ΓòÉΓòÉΓòÉ
  1058.  
  1059. CAPSAMP (located in \TOOLKIT\SAMPLES\MM\CAPSAMP) and the caption utility 
  1060. functions (located in \TOOLKIT\SAMPLES\MM\CAPDLL) are part of the sample 
  1061. captioning system provided with the OS/2 Warp Toolkit. CAPSAMP demonstrates how 
  1062. captioning can be integrated into applications using caption files in 
  1063. conjunction with the caption utility functions. 
  1064.  
  1065. Hardware requirements: 
  1066.  
  1067.      Computer capable of running OS/2 Warp 
  1068.      Speaker or headphones 
  1069.      Sound card 
  1070.  
  1071.  Software requirements: 
  1072.  
  1073.      OS/2 Warp 
  1074.      Multimedia support 
  1075.  
  1076.  
  1077. ΓòÉΓòÉΓòÉ 7.3.5.6. CAPTION Sample Program ΓòÉΓòÉΓòÉ
  1078.  
  1079. CAPTION (located in \TOOLKIT\SAMPLES\MM\CAPTION) is part of the sample 
  1080. captioning system provided with the OS/2 Warp Toolkit. The caption creation 
  1081. utility program creates a "caption" file. It enables you to synchronize an 
  1082. audio file with a text file. 
  1083.  
  1084. This concept can be extended beyond audio and text to apply to many 
  1085. possibilities, such as synchronizing audio and video or synchronizing video and 
  1086. text. 
  1087.  
  1088. Note:  In order for the Caption sample to work correctly, captioning must be 
  1089.        enabled in the operating system. To enable captioning proceed as 
  1090.        follows: 
  1091.  
  1092.      Open the Multimedia Setup object in the Multimedia folder 
  1093.      Go to the System page 
  1094.      Place a check mark in the Captioning check box. 
  1095.  
  1096.  
  1097. ΓòÉΓòÉΓòÉ 7.3.5.7. CASECONV I/O Procedure Sample ΓòÉΓòÉΓòÉ
  1098.  
  1099. CASECONV (located in \TOOLKIT\SAMPLES\MM\CASECONV) provides a simple example of 
  1100. how to write a file format I/O procedure (without illustrating the use of data 
  1101. translation). This sample performs case conversion of text. 
  1102.  
  1103.  
  1104. ΓòÉΓòÉΓòÉ 7.3.5.8. CDMCT Sample Program ΓòÉΓòÉΓòÉ
  1105.  
  1106. CDMCT (located in \TOOLKIT\SAMPLES\MM\CDMCIDRV) is an example of a media 
  1107. control driver (MCD) that demonstrates how to control a non-streaming device. 
  1108. Non-streaming devices stream data within the device. 
  1109.  
  1110.  
  1111. ΓòÉΓòÉΓòÉ 7.3.5.9. Control File Templates ΓòÉΓòÉΓòÉ
  1112.  
  1113. The \TOOLKIT\SAMPLES\MM\CF subdirectory contains control file templates you can 
  1114. utilize when installing a program using MINSTALL. 
  1115.  
  1116.  
  1117. ΓòÉΓòÉΓòÉ 7.3.5.10. CLOCK Sample Program ΓòÉΓòÉΓòÉ
  1118.  
  1119. CLOCK (located in \TOOLKIT\SAMPLES\MM\CLOCK) illustrates the use of the memory 
  1120. playlist feature of OS/2 multimedia. The memory playlist feature provides for 
  1121. easy manipulation of multimedia in memory to create unique effects based on 
  1122. user input or other dynamic events. 
  1123.  
  1124. Hardware requirements: 
  1125.  
  1126.      Computer capable of running OS/2 Warp 
  1127.      Speaker or headphones 
  1128.      Sound card 
  1129.  
  1130.  Software requirements: 
  1131.  
  1132.      OS/2 Warp 
  1133.      Multimedia support 
  1134.  
  1135.  
  1136. ΓòÉΓòÉΓòÉ 7.3.5.11. CODEC Sample Program ΓòÉΓòÉΓòÉ
  1137.  
  1138. CODEC (located in \TOOLKIT\SAMPLES\MM\CODEC) illustrates how to write a CODEC 
  1139. procedure to include compression and decompression routines in your multimedia 
  1140. applications. A CODEC procedure operates on data within a file or buffer. 
  1141.  
  1142.  
  1143. ΓòÉΓòÉΓòÉ 7.3.5.12. DAUDIO Sample Program ΓòÉΓòÉΓòÉ
  1144.  
  1145. DAUDIO (direct audio) demonstrates the use of the direct audio interface. This 
  1146. high speed audio interface enables an application to send audio data directly 
  1147. to the amp-mixer device. The sample demonstrates the steps required to set up 
  1148. and use this new interface for playing and recording digital audio data. 
  1149.  
  1150. See the Multimedia Application Programming Guide and the Multimedia Programming 
  1151. Reference for more information on the direct audio interface. 
  1152.  
  1153. Hardware requirements: 
  1154.  
  1155.      Computer capable of running OS/2 Warp 
  1156.      Sound card 
  1157.      Speakers or headphones 
  1158.  
  1159.  Software requirements: 
  1160.  
  1161.      OS/2 Warp Version 4 or later 
  1162.      Multimedia support 
  1163.  
  1164.  
  1165. ΓòÉΓòÉΓòÉ 7.3.5.12.1. Starting DAUDIO ΓòÉΓòÉΓòÉ
  1166.  
  1167. You can start DAUDIO in two ways: 
  1168.  
  1169.      From the command line, change to the TOOLKIT\SAMPLES\MM\DAUDIO 
  1170.       subdirectory and type: 
  1171.  
  1172.               DAUDIO
  1173.  
  1174.      From the Desktop, open the Toolkit folder and then: 
  1175.  
  1176.         1. Open the Multimedia Samples folder. 
  1177.  
  1178.         2. Open the Audio Samples folder. 
  1179.  
  1180.         3. Double-click on Direct Audio. 
  1181.  
  1182.  
  1183. ΓòÉΓòÉΓòÉ 7.3.5.13. DIVE Sample Program ΓòÉΓòÉΓòÉ
  1184.  
  1185. DIVE (located in \TOOLKIT\SAMPLES\MM\DIVE) illustrates the use of the direct 
  1186. interface video extensions. DIVE provides optimized blitting performance for 
  1187. motion video subsystems and applications that perform rapid screen updates in 
  1188. the OS/2 PM and full-screen environments. Using DIVE interfaces, applications 
  1189. can either write directly to video memory or use the DIVE blitter. The DIVE 
  1190. blitter takes advantage of acceleration hardware when present and applicable to 
  1191. the function being performed. 
  1192.  
  1193. Note:  The DIVE sample requires OS/2 Warp Version 3 or later in order to 
  1194.        execute properly. The files for the samples will be installed when the 
  1195.        samples are selected, but Workplace Shell objects will not be created 
  1196.        for them if the installed operating system is not OS/2 Warp Version 3 or 
  1197.        higher. 
  1198.  
  1199. The OS/2 Warp color support defaults to 16 colors. This means that your setup 
  1200. needs to be updated; otherwise, the DIVE sample will not run. 
  1201.  
  1202. The maximum window size of this sample has been limited to 640x480 because 
  1203. larger window sizes can cause excessive swapping on machines with less than 
  1204. 16MB. 
  1205.  
  1206.  Hardware requirements: 
  1207.  
  1208.      Computer capable of running OS/2 Warp 
  1209.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  1210.  
  1211.  Software requirements: 
  1212.  
  1213.      OS/2 Warp 
  1214.      Multimedia support 
  1215.      Software motion video 
  1216.  
  1217.  
  1218. ΓòÉΓòÉΓòÉ 7.3.5.14. DOUBPLAY Sample Program ΓòÉΓòÉΓòÉ
  1219.  
  1220. DOUBPLAY (located in \TOOLKIT\SAMPLES\MM\DOUBPLAY) enables an application to 
  1221. play audio files directly from application memory buffers. An array of multiple 
  1222. playlist structures that combines playlist commands with data buffers can be 
  1223. constructed to perform complex operations on multiple buffers. 
  1224.  
  1225. This sample takes a single wave file, MYWAVE.WAV, and plays it using a memory 
  1226. playlist. The playlist is constructed as a circular buffer composed of a series 
  1227. of small buffers, the sum of which might be larger than the size of the .WAV 
  1228. file. This circular buffer is used to repeatedly play an audio file when the 
  1229. PLAY button is selected. As each buffer in the playlist is expended, the 
  1230. application refills the expended buffer with new data from the .WAV file. When 
  1231. all the buffers in the playlist have been expended, the playlist branches back 
  1232. to the first buffer to play the new data. This circular buffering process 
  1233. continues until the STOP button is selected or the application is closed. 
  1234.  
  1235. Hardware requirements: 
  1236.  
  1237.      Computer capable of running OS/2 Warp 
  1238.      Speakers or headphones 
  1239.      Sound card 
  1240.  
  1241.  Software requirements: 
  1242.  
  1243.      OS/2 Warp 
  1244.      Multimedia support 
  1245.  
  1246.  
  1247. ΓòÉΓòÉΓòÉ 7.3.5.15. DUET1 Sample Program ΓòÉΓòÉΓòÉ
  1248.  
  1249. DUET1 (located in \TOOLKIT\SAMPLES\MM\DUET1) illustrates the OS/2 multimedia 
  1250. concept of device grouping and integrating multimedia into an application's 
  1251. help information. This sample demonstrates the concepts of grouping two 
  1252. streaming devices. 
  1253.  
  1254. Note:  The Streaming Device Duet sample (DUET1, located in 
  1255.        \TOOLKIT\SAMPLES\MM\DUET1) requires that the IBM M-Audio Capture and 
  1256.        Playback Adapter card be installed in order for the sample to execute 
  1257.        properly. 
  1258.  
  1259.  Hardware requirements: 
  1260.  
  1261.      Computer capable of running OS/2 Warp 
  1262.      Speaker or headphones 
  1263.      Sound card (capable of playing two mono wave files simultaneously such as 
  1264.       the IBM M-AUDIO card) 
  1265.  
  1266.  Software requirements: 
  1267.  
  1268.      OS/2 Warp 
  1269.      Multimedia support 
  1270.  
  1271.  
  1272. ΓòÉΓòÉΓòÉ 7.3.5.16. DUET2 Sample Program ΓòÉΓòÉΓòÉ
  1273.  
  1274. DUET2 (located in \TOOLKIT\SAMPLES\MM\DUET2) illustrates the OS/2 multimedia 
  1275. concept of device grouping and integrating multimedia into an application's 
  1276. help information. This sample demonstrates how one of the devices in the 
  1277. multimedia device group can be a non-streaming device. 
  1278.  
  1279. Hardware requirements: 
  1280.  
  1281.      Computer capable of running OS/2 Warp 
  1282.      Speaker or headphones 
  1283.      Sound card 
  1284.      CD-ROM drive 
  1285.  
  1286.  Software requirements: 
  1287.  
  1288.      OS/2 Warp 
  1289.      Multimedia support 
  1290.  
  1291.  
  1292. ΓòÉΓòÉΓòÉ 7.3.5.17. FSDIVE Sample Program ΓòÉΓòÉΓòÉ
  1293.  
  1294. FSDIVE (full-screen DIVE) demonstrates the use of multimedia's direct interface 
  1295. video extensions (DIVE) by repeatedly displaying a short animation sequence. 
  1296. The animation is performed by sequentially displaying a series of up to 16 
  1297. bitmaps in a PM window. You can display the default bitmaps that are included 
  1298. with the sample or specify the bitmaps by passing the file names as command 
  1299. line parameters. 
  1300.  
  1301. After the application is started, you can move or resize the window and observe 
  1302. the effects on the frame rate of the animation (displayed on the title bar). 
  1303.  
  1304. The latest version of the DIVE interface has been enhanced to allow an 
  1305. application to take over the display and change the resolution. This enables an 
  1306. application to run in a full screen without paying the performance penalty of 
  1307. maintaining a high-resolution Desktop. Full-screen DIVE can be activated by 
  1308. using the Alt+Home hot key. 
  1309.  
  1310. Note:  To run the full-screen DIVE sample on an OS/2 Warp Version 3 system, you 
  1311.        must first install full-screen support by running GSRVINST.EXE (located 
  1312.        in \TOOLKIT\SAMPLES\MM\FSDIVE). See the GAMESRVR.DOC file in the same 
  1313.        directory for more details. This installation is not necessary on an 
  1314.        OS/2 Warp Version 4 or later system. 
  1315.  
  1316.  Hardware Requirements: 
  1317.  
  1318.      Computer capable of running OS/2 Warp 
  1319.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  1320.  
  1321.  Software Requirements: 
  1322.  
  1323.      OS/2 Warp Version 3 or later 
  1324.      Multimedia support 
  1325.      Software motion video 
  1326.  
  1327.  The maximum window size of this sample has been limited to 640x480 because 
  1328.  larger window sizes can cause excessive swapping on machines with less than 
  1329.  16MB. 
  1330.  
  1331.  
  1332. ΓòÉΓòÉΓòÉ 7.3.5.17.1. Starting FSDIVE ΓòÉΓòÉΓòÉ
  1333.  
  1334. You can start FSDIVE in two ways: 
  1335.  
  1336.      From the command line, change to the TOOLKIT\SAMPLES\MM\FSDIVE 
  1337.       subdirectory and type: 
  1338.  
  1339.               FSDIVE
  1340.  
  1341.      From the Desktop, open the Toolkit folder and then: 
  1342.  
  1343.         1. Open the Multimedia Samples folder. 
  1344.  
  1345.         2. Open the Video Samples folder. 
  1346.  
  1347.         3. Double-click on FS Dive. 
  1348.  
  1349.  
  1350. ΓòÉΓòÉΓòÉ 7.3.5.18. FSSHT Sample Program ΓòÉΓòÉΓòÉ
  1351.  
  1352. FSSHT (located in \TOOLKIT\SAMPLES\MM\FSSHT) contains a sample file system 
  1353. stream handler. 
  1354.  
  1355.  
  1356. ΓòÉΓòÉΓòÉ 7.3.5.19. MCD Command Tables ΓòÉΓòÉΓòÉ
  1357.  
  1358. Before a media control driver (MCD) can interpret a string command, the media 
  1359. device manager (MDM) must use a command table to change the string into an 
  1360. equivalent procedural command. Represented as resources to the driver, command 
  1361. tables are created using the RCDATA type of resource. The resource number of 
  1362. the RCDATA block is the device type number. The \TOOLKIT\SAMPLES\MM\MCDTBL 
  1363. subdirectory contains command tables for each of the following devices: 
  1364.  
  1365.      Amp Mixer 
  1366.      CD-ROM/XA 
  1367.      CD Audio 
  1368.      Digital Video 
  1369.      Sequencer 
  1370.      Videodisc 
  1371.      Wave Audio 
  1372.  
  1373.  If you want to support device-specific messages, you must create a device- 
  1374.  specific command table. 
  1375.  
  1376.  
  1377. ΓòÉΓòÉΓòÉ 7.3.5.20. MCDTEMP Template ΓòÉΓòÉΓòÉ
  1378.  
  1379. MCDTEMP (located in \TOOLKIT\SAMPLES\MM\MCDTEMP) provides a basic template to 
  1380. write a media control driver (MCD). Refer to the \ADMCT and \CDMCIDRV 
  1381. subdirectories for specific streaming or to the multimedia I/O (MMIO) samples. 
  1382.  
  1383.  
  1384. ΓòÉΓòÉΓòÉ 7.3.5.21. MCISPY Sample Program ΓòÉΓòÉΓòÉ
  1385.  
  1386. MCISPY (located in \TOOLKIT\SAMPLES\MM\MCISPY) monitors media control interface 
  1387. messages that are exchanged between applications and the OS/2 multimedia 
  1388. subsystem. 
  1389.  
  1390. In addition to teaching you about multimedia messages, MCISPY also serves as a 
  1391. powerful debugging aid. 
  1392.  
  1393. The MCISPY sample must be manually set up. To do so, follow these steps: 
  1394.  
  1395.    1. Copy the MDM.DLL file located in the \MMOS2\DLL subdirectory to the 
  1396.       \TOOLKIT\DLL subdirectory. 
  1397.  
  1398.    2. Use the DLLRNAME tool (available with C Set ++ or VisualAge C++) to 
  1399.       rename the copy to MCI.DLL. To do this, type: 
  1400.  
  1401.             DLLRNAME MDM.DLL MDM=MCI
  1402.  
  1403.    3. Create the executable (MCISPY.EXE) and the stub DLL (MDM.DLL) by running 
  1404.       the MCISPY makefile. 
  1405.  
  1406.    4. Place the stub MDM.DLL, built by the MCISPY makefile, in the LIBPATH so 
  1407.       that it is recognized prior to the MDM.DLL file located in the \MMOS2\DLL 
  1408.       subdirectory. The source code for the stub MDM.DLL is included in the 
  1409.       MCISPY sample. 
  1410.  
  1411.    5. Restart your system. 
  1412.  
  1413.  Note:  Driver notifications might not be visible in releases prior to OS/2 
  1414.         Warp Version 3. These notifications include all multimedia messages 
  1415.         routed through mdmDriverNotify(). 
  1416.  
  1417.  Hardware requirements: 
  1418.  
  1419.      Computer capable of running OS/2 Warp 
  1420.  
  1421.  Software requirements: 
  1422.  
  1423.      Multimedia support 
  1424.      OS/2 Warp 
  1425.  
  1426.       Note:  The files for the samples will be installed when the samples are 
  1427.              selected, but Workplace Shell objects will not be created for them 
  1428.              if the installed operating system is not OS/2 Warp. 
  1429.  
  1430.  
  1431. ΓòÉΓòÉΓòÉ 7.3.5.22. MCISTRNG Sample Program ΓòÉΓòÉΓòÉ
  1432.  
  1433. MCISTRNG (located in \TOOLKIT\SAMPLES\MM\MCISTRNG) serves as a powerful testing 
  1434. and debugging tool that enables developers, who are writing media drivers, to 
  1435. control their devices at the application level. The string test sample 
  1436. illustrates how an application uses the interpretive string interface provided 
  1437. by the media control interface. 
  1438.  
  1439. This sample also illustrates how notification messages are returned from the 
  1440. media drivers to the application. 
  1441.  
  1442. Hardware requirements: 
  1443.  
  1444.      Computer capable of running OS/2 Warp 
  1445.  
  1446.  Software requirements: 
  1447.  
  1448.      OS/2 Warp 
  1449.      Multimedia support 
  1450.  
  1451.  
  1452. ΓòÉΓòÉΓòÉ 7.3.5.23. MIDISAMP Sample Program ΓòÉΓòÉΓòÉ
  1453.  
  1454. MIDISAMP illustrates the use of the real-time MIDI (RTMIDI) programming 
  1455. concepts and usage of the new RTMIDI API. This sample initializes and sets up a 
  1456. small MIDI node network and subsequently sends a MIDI message from an 
  1457. application node to a hardware node, thereby demonstrating MIDI playback. 
  1458.  
  1459. The RTMIDI functions are documented in the Multimedia Programming Reference. 
  1460.  
  1461. Hardware requirements: 
  1462.  
  1463.      Computer capable of running OS/2 Warp 
  1464.      A sound card supported by a "Type A" RTMIDI device driver 
  1465.  
  1466.  Note:  Type A device drivers provide direct hardware support for RTMIDI. The 
  1467.         following is a list of supported Type A device drivers: 
  1468.  
  1469.      MPU-401 - A generic driver for sound cards with true hardware MPU-401 
  1470.       compatibility (for example, not the AWE-32).  It uses only UART dumb 
  1471.       mode. This driver is also an MMPM/2 driver. It can be found on the DDPak 
  1472.       CD-ROM. 
  1473.  
  1474.      OPL-3 - A generic driver for sound cards with true hardware Yamaha OPL-3 
  1475.       FM chips.  This driver is also an MMPM/2 driver. It can be found on the 
  1476.       DDPak CD-ROM. 
  1477.  
  1478.      PAS-16 - A device driver for the Media Vision PAS-16 line of audio cards. 
  1479.       This driver is also an MMPM/2 driver. It can be installed using the 
  1480.       Selective Install program. 
  1481.  
  1482.  Software requirements: 
  1483.  
  1484.      OS/2 Warp Version 4 or later 
  1485.      Multimedia support 
  1486.      Standard MIDI file 
  1487.  
  1488.  
  1489. ΓòÉΓòÉΓòÉ 7.3.5.23.1. Starting MIDISAMP ΓòÉΓòÉΓòÉ
  1490.  
  1491. You can start MIDISAMP in two ways: 
  1492.  
  1493.      From the command line, change to the TOOLKIT\SAMPLES\MM\MIDI subdirectory 
  1494.       and type: 
  1495.  
  1496.               MIDISAMP filename.mid
  1497.  
  1498.       where filename.mid  is a MIDI file. 
  1499.  
  1500.      From the Desktop, open the Toolkit folder and then: 
  1501.  
  1502.         1. Open the Multimedia Samples folder. 
  1503.  
  1504.         2. Open the Audio Samples folder. 
  1505.  
  1506.         3. Double-click on MIDI Samp. 
  1507.  
  1508.  Sample MIDI files are located in the MMOS2\SOUNDS subdirectory. 
  1509.  
  1510.  
  1511. ΓòÉΓòÉΓòÉ 7.3.5.24. MMBROWSE Sample Program ΓòÉΓòÉΓòÉ
  1512.  
  1513. MMBROWSE (located in \TOOLKIT\SAMPLES\MM\MMBROWSE) illustrates how to use the 
  1514. multimedia I/O (MMIO) subsystem to install I/O procedures for various image 
  1515. formats and then convert these image formats to OS/2 bitmaps. 
  1516.  
  1517. Hardware requirements: 
  1518.  
  1519.      Computer capable of running OS/2 Warp 
  1520.  
  1521.  Software requirements: 
  1522.  
  1523.      OS/2 Warp 
  1524.      Multimedia support 
  1525.  
  1526.  
  1527. ΓòÉΓòÉΓòÉ 7.3.5.25. MMOTTK I/O Procedure Sample ΓòÉΓòÉΓòÉ
  1528.  
  1529. MMOTTK (located in \TOOLKIT\SAMPLES\MM\MMIOPROC) provides an example of how to 
  1530. write an I/O procedure for use with image file formats. This sample enables 
  1531. file format transparency for M-Motion still video files and illustrates the use 
  1532. of data translation. 
  1533.  
  1534.  
  1535. ΓòÉΓòÉΓòÉ 7.3.5.26. MOVIE Sample Program ΓòÉΓòÉΓòÉ
  1536.  
  1537. MOVIE (located in \TOOLKIT\SAMPLES\MM\MOVIE) demonstrates device control of a 
  1538. software motion video device. 
  1539.  
  1540. This sample also illustrates how to cut, copy, paste, and delete movie data 
  1541. from an application. 
  1542.  
  1543. A movie can be played in an application-defined window or in the system default 
  1544. window provided by the software motion video subsystem. 
  1545.  
  1546. Note:  If you installed the OS/2 Warp Toolkit from diskette, the Movie sample 
  1547.        (located in \TOOLKIT\SAMPLES\MM\MOVIE) does not contain the MOVIE.AVI 
  1548.        file necessary to execute the application. Copy any .AVI file from the 
  1549.        \MMOS2\MOVIES subdirectory on the drive on which you have OS/2 
  1550.        multimedia installed. The .AVI file should be copied to the 
  1551.        \TOOLKIT\SAMPLES\MM\MOVIE subdirectory on which you have the OS/2 Warp 
  1552.        Toolkit samples installed, and the target name of the file should be 
  1553.        MOVIE.AVI. 
  1554.  
  1555.  Hardware requirements: 
  1556.  
  1557.      Computer capable of running OS/2 Warp 
  1558.      Speakers or headphones 
  1559.      Sound card 
  1560.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  1561.  
  1562.  Software requirements: 
  1563.  
  1564.      OS/2 Warp 
  1565.      Multimedia support 
  1566.      Software motion video 
  1567.  
  1568.  
  1569. ΓòÉΓòÉΓòÉ 7.3.5.27. RECORDER Sample Program ΓòÉΓòÉΓòÉ
  1570.  
  1571. RECORDER (located in \TOOLKIT\SAMPLES\MM\RECORDER) illustrates the concept of 
  1572. recording audio through the media control interface and how to query a device 
  1573. to find out the recording capabilities. 
  1574.  
  1575. This sample also illustrates how to change the audio recording and audio device 
  1576. properties, such as bits per sample, samples per second, input level, and input 
  1577. source. 
  1578.  
  1579. Hardware requirements: 
  1580.  
  1581.      Computer capable of running OS/2 Warp 
  1582.      Speaker or headphones 
  1583.      Sound card 
  1584.  
  1585.  Software requirements: 
  1586.  
  1587.      OS/2 Warp 
  1588.      Multimedia support 
  1589.  
  1590.  
  1591. ΓòÉΓòÉΓòÉ 7.3.5.28. Short Control File Templates ΓòÉΓòÉΓòÉ
  1592.  
  1593. The \TOOLKIT\SAMPLES\MM\SHORTCF subdirectory contains a simple example of 
  1594. control file templates you can use when installing a program using MINSTALL. 
  1595.  
  1596.  
  1597. ΓòÉΓòÉΓòÉ 7.3.5.29. SHRC Sample Program ΓòÉΓòÉΓòÉ
  1598.  
  1599. SHRC (located in \TOOLKIT\SAMPLES\MM\SHRC) provides a sample stream handler 
  1600. resource file. 
  1601.  
  1602.  
  1603. ΓòÉΓòÉΓòÉ 7.3.5.30. TUNER Sample Program ΓòÉΓòÉΓòÉ
  1604.  
  1605. TV tuner cards allow a desktop PC to receive and display broadcast television 
  1606. signals. TUNER (located in \TOOLKIT\SAMPLES\MM\TUNER), provides an example of 
  1607. how to use the media control interface (MCI) string interface to control a 
  1608. tuner card. 
  1609.  
  1610. When the application is running, the display window can be sized and a TV 
  1611. channel can be selected. The channel can be selected through up/down buttons or 
  1612. a text entry field displayed at the bottom of the window. 
  1613.  
  1614. Hardware requirements: 
  1615.  
  1616.      Computer capable of running OS/2 Warp 
  1617.      TV tuner card (such as the WinTV Basic) 
  1618.  
  1619.  Software requirements: 
  1620.  
  1621.      OS/2 Warp 
  1622.      Multimedia support 
  1623.      Appropriate drivers for installed tuner card 
  1624.  
  1625.  A TV tuner card is handled as a digital video device by the multimedia 
  1626.  subsystem. A typical system has one or more digital video devices, with 
  1627.  digitalvideo01 assigned to software motion video. By default this sample opens 
  1628.  the digitalvideo02 device. If the tuner card is not assigned to digital video 
  1629.  2 an alternate device ordinal must be provided at the command line with the 
  1630.  following format: 
  1631.  
  1632.     /d=digitalvideoxx
  1633.  
  1634.  where xx is a two digit number, padded on the left with zero. 
  1635.  
  1636.  For example: 
  1637.  
  1638.     /d=digitalvideo03
  1639.  
  1640.  Most TV tuner cards, such as the Hauppauge WinTV card, support several video 
  1641.  sources. The connector number that corresponds to the tuner video source is 
  1642.  dependent on the hardware and might not be the same for each tuner card. The 
  1643.  connector number is not changed by this sample. Instead, it uses the default 
  1644.  connector number that is set by the Multimedia Setup program. 
  1645.  
  1646.  
  1647. ΓòÉΓòÉΓòÉ 7.3.5.31. ULTIEYES Sample Program ΓòÉΓòÉΓòÉ
  1648.  
  1649. ULTIEYES (located in \TOOLKIT\SAMPLES\MM\ULTIEYES) demonstrates the use of 
  1650. non-linear video by displaying segments from a movie clip in response to input 
  1651. from the mouse. 
  1652.  
  1653. Hardware requirements: 
  1654.  
  1655.      SVGA (a screen mode of 640x480x256 constitutes a minimum SVGA system) 
  1656.  
  1657.  Software requirements: 
  1658.  
  1659.      Multimedia support 
  1660.      Software motion video 
  1661.      OS/2 Warp 
  1662.  
  1663.       Note:  The files for the samples will be installed when the samples are 
  1664.              selected, but Workplace Shell objects will not be created for them 
  1665.              if the installed operating system is not OS/2 Warp Version 3. 
  1666.  
  1667.  
  1668. ΓòÉΓòÉΓòÉ 7.3.5.32. ULIOT I/O Procedure Sample ΓòÉΓòÉΓòÉ
  1669.  
  1670. ULIOT (located in \TOOLKIT\SAMPLES\MM\ULTIMOIO) provides a detailed example of 
  1671. what you need to consider when writing I/O procedures for software motion video 
  1672. file formats. This sample program includes CODEC support and illustrates how to 
  1673. integrate common and file-format-specific code to support multiple I/O 
  1674. procedures. 
  1675.  
  1676.  
  1677. ΓòÉΓòÉΓòÉ 7.3.6. Open32 Samples ΓòÉΓòÉΓòÉ
  1678.  
  1679. The following Open32 samples are included in the OS/2 Warp Toolkit: 
  1680.  
  1681.      Browser 
  1682.      HiWorld 
  1683.      ToyBox 
  1684.      DLL Initialization Entry Point (DLLMAIN.C) 
  1685.      WinMain Wrapper Function (MAIN.C) 
  1686.  
  1687.  Note:  Open32 was formerly known as the IBM Developer API Extensions for OS/2. 
  1688.  
  1689.  
  1690. ΓòÉΓòÉΓòÉ 7.3.6.1. Browser ΓòÉΓòÉΓòÉ
  1691.  
  1692. The Browser sample enables you to view the lines of text files in a Multiple 
  1693. Document Interface (MDI) environment. The sample provides files containing the 
  1694. program source code. You can open one or more of them, scroll them, change 
  1695. their display fonts, and arrange their windows or icons inside the sample 
  1696. program window. 
  1697.  
  1698. There are two versions of the Browser sample. The Win32 version, located in the 
  1699. \TOOLKIT\SAMPLES\OPEN32\BROWSER subdirectory, will build without source changes 
  1700. on a Win32 system with the appropriate development tools. (Win32 tools are not 
  1701. provided with the OS/2 Warp Toolkit.) 
  1702.  
  1703. The OS/2 version of Browser is located in the \TOOLKIT\SAMPLES\OPEN32\BROWSER2 
  1704. subdirectory. 
  1705.  
  1706.  
  1707. ΓòÉΓòÉΓòÉ 7.3.6.2. HiWorld ΓòÉΓòÉΓòÉ
  1708.  
  1709. HiWorld is a simple Windows 32-bit (Win32) application that displays the 
  1710. following text, centered in the client area of the main window: 
  1711.  
  1712. Hello, World
  1713.  
  1714. There are two versions of the HiWorld sample. The Win32 version, located in the 
  1715. \TOOLKIT\SAMPLES\OPEN32\HIWORLD subdirectory, will build without source changes 
  1716. on a Win32 system with the appropriate development tools. (Win32 tools are not 
  1717. provided with the OS/2 Warp Toolkit.) 
  1718.  
  1719. The OS/2 version of HiWorld is located in the \TOOLKIT\SAMPLES\OPEN32\HIWORLD2 
  1720. subdirectory along with a README that briefly describes the steps that were 
  1721. taken to convert the Win32 version of HiWorld to this native OS/2 executable. 
  1722.  
  1723.  
  1724. ΓòÉΓòÉΓòÉ 7.3.6.3. ToyBox ΓòÉΓòÉΓòÉ
  1725.  
  1726. ToyBox is a basic Win32 application that uses bit-block transfer (BitBlt) to 
  1727. display a large number of simple bitmaps on the display screen and give them 
  1728. motion. It moves the objects around the client portion of the screen and makes 
  1729. the objects appear to change shape and rotate. 
  1730.  
  1731. There are two versions of the ToyBox sample. The Win32 version, located in the 
  1732. \TOOLKIT\SAMPLES\OPEN32\TOYBOX subdirectory, will build without source changes 
  1733. on a Win32 system with the appropriate development tools. (Win32 tools are not 
  1734. provided with the OS/2 Warp Toolkit.) 
  1735.  
  1736. The OS/2 version of ToyBox is located in the \TOOLKIT\SAMPLES\OPEN32\TOYBOX2 
  1737. subdirectory. 
  1738.  
  1739.  
  1740. ΓòÉΓòÉΓòÉ 7.3.6.4. DLL Initialization Entry Point ΓòÉΓòÉΓòÉ
  1741.  
  1742. The DLLMAIN.C file (located in the \TOOLKIT\SAMPLES\OPEN32\DLLENTRY 
  1743. subdirectory) contains the DLL initialization/termination function, which is 
  1744. called when a process gains or loses access to the DLL. The .DEF file used to 
  1745. build the DLL needs to specify INITINSTANCE and TERMINSTANCE; otherwise, this 
  1746. function will be called only for the first process to gain access and the last 
  1747. process to free up the DLL. 
  1748.  
  1749. This implementation is for IBM VisualAge C++ and assumes that the C Runtime 
  1750. library is being statically linked to the DLL and that the library uses C++ 
  1751. classes. 
  1752.  
  1753.  
  1754. ΓòÉΓòÉΓòÉ 7.3.6.5. WinMain Wrapper Function ΓòÉΓòÉΓòÉ
  1755.  
  1756. The MAIN.C file (located in the \TOOLKIT\SAMPLES\OPEN32\WINMAIN subdirectory) 
  1757. is provided as a helper (stub) to demonstrate how to invoke the Windows WinMain 
  1758. function from OS/2. 
  1759.  
  1760. This is the "main" wrapper for an application based on Open32. It initializes 
  1761. the Alternative Windows Emulator (AWE) environment, calls the WinMain function, 
  1762. and upon completion, calls the WinTerm function to shut down the AWE 
  1763. environment. 
  1764.  
  1765. Note:  To be able to use the Windows WinMain() function, use the OS/2 Warp 
  1766.        main() function located in the MAIN.C file. MAIN.C gets compiled and 
  1767.        linked with the module containing WinMain() and creates an OS/2 Warp 
  1768.        executable file. If you do not use the OS/2 Warp main() function, you 
  1769.        will receive a link error stating that there is no starting address for 
  1770.        your program. 
  1771.  
  1772.  
  1773. ΓòÉΓòÉΓòÉ 7.3.7. OpenGL Sample Programs ΓòÉΓòÉΓòÉ
  1774.  
  1775. The OpenGL sample programs are categorized as follows. 
  1776.  
  1777. Note that installation of OpenGL is required for execution of the OpenGL 
  1778. samples. 
  1779.  
  1780.      AUXDEMO - Auxiliary Library samples 
  1781.      GLUTDEMO - Graphics Library Utility Toolkit samples 
  1782.  
  1783.  
  1784. ΓòÉΓòÉΓòÉ 7.3.7.1. AUXDEMO Sample Programs ΓòÉΓòÉΓòÉ
  1785.  
  1786. The following Auxiliary Library samples are provided in the OS/2 Warp Toolkit: 
  1787.  
  1788.      ACCANTI 
  1789.  
  1790.       This program shows accumulation of jittered objects with an orthographic 
  1791.       projection in order to antialias a scene. 
  1792.  
  1793.      ACCNOT 
  1794.  
  1795.       This program is basically the same as ACCANTI, but without the jittering 
  1796.       to show the same scene aliased. 
  1797.  
  1798.      ACCPERSP 
  1799.  
  1800.       This program shows the same scene as the prior ACCANTI and ACCNOT, but 
  1801.       with a perspective projection and accumulation of jittered images to 
  1802.       antialias the scene. 
  1803.  
  1804.      ACCUM 
  1805.  
  1806.       This program is another example of accumulating multiple images in order 
  1807.       to antialias a scene. 
  1808.  
  1809.      AIM 
  1810.  
  1811.       This program calculates the fovy (field of view angle in the Y 
  1812.       direction), by using trigonometry, given the size of an object and its 
  1813.       size. 
  1814.  
  1815.      ALPHA 
  1816.  
  1817.       This program draws several overlapping filled polygons to demonstrate the 
  1818.       effect order has on alpha blending results. 
  1819.  
  1820.      ALPHA3D 
  1821.  
  1822.       This program demonstrates how to intermix opaque and alpha blended 
  1823.       polygons in the same scene, by using glDepthMask(). By pressing the left 
  1824.       mouse button, you can toggle the eye position. 
  1825.  
  1826.      ANTI 
  1827.  
  1828.       This program draws antialiased lines in RGBA mode. 
  1829.  
  1830.      ANTIINDX 
  1831.  
  1832.       This program draws a wireframe icosahedron with antialiased lines, in 
  1833.       color index mode. 
  1834.  
  1835.      ANTIPIDX 
  1836.  
  1837.       This program draws antialiased points, in color index mode. 
  1838.  
  1839.      ANTIPOLY 
  1840.  
  1841.       This program draws filled polygons with antialiased edges.  The special 
  1842.       GL_SRC_ALPHA_SATURATE blending function is used. By pressing the left 
  1843.       mouse button, you can turn the antialiasing on and off. 
  1844.  
  1845.      ANTIPT 
  1846.  
  1847.       This program draws antialiased points, in RGBA mode. 
  1848.  
  1849.      BEZCURVE 
  1850.  
  1851.       This program uses evaluators to draw a Bezier curve. 
  1852.  
  1853.      BEZSURF 
  1854.  
  1855.       This program renders a lighted, filled Bezier surface, using 
  1856.       two-dimensional evaluators. 
  1857.  
  1858.      BEZMESH 
  1859.  
  1860.       This program renders a wireframe Bezier surface, using two-dimensional 
  1861.       evaluators. 
  1862.  
  1863.      CHECKER 
  1864.  
  1865.       This program texture maps a checkerboard image onto two rectangles.  This 
  1866.       program clamps the texture, if the texture coordinates fall outside 0.0 
  1867.       and 1.0. 
  1868.  
  1869.      CHECKER2 
  1870.  
  1871.       This program texture maps a checkerboard image onto two rectangles.  This 
  1872.       program repeats the texture, if the texture coordinates fall outside 0.0 
  1873.       and 1.0. 
  1874.  
  1875.      CHESS 
  1876.  
  1877.       This program texture maps a checkerboard image onto two rectangles.  The 
  1878.       texture coordinates for the rectangles are 0.0 to 3.0. 
  1879.  
  1880.      CLIP 
  1881.  
  1882.       This program demonstrates arbitrary clipping planes. 
  1883.  
  1884.      COLORMAT 
  1885.  
  1886.       This program will be in ColorMaterial mode after initialization. By 
  1887.       pressing the mouse buttons, you can change the color of the diffuse 
  1888.       reflection. 
  1889.  
  1890.      CONE 
  1891.  
  1892.       This program demonstrates the use of the GL lighting model. A sphere is 
  1893.       drawn using a grey material characteristic.  A single light source 
  1894.       illuminates the object. 
  1895.  
  1896.      CUBE 
  1897.  
  1898.       This program draws a 3-D cube, viewed with perspective, stretched along 
  1899.       the Y-axis. 
  1900.  
  1901.      CURVE 
  1902.  
  1903.       This program uses the Utility Library NURBS routines to draw a 
  1904.       one-dimensional NURBS curve. 
  1905.  
  1906.      DEPTHCUE 
  1907.  
  1908.       This program draws a wireframe model, which uses intensity (brightness) 
  1909.       to give clues to distance. Fog is used to achieve this effect. 
  1910.  
  1911.      DISK 
  1912.  
  1913.       This program demonstrates the use of the quadrics Utility Library 
  1914.       routines to draw circles and arcs. 
  1915.  
  1916.      DOF 
  1917.  
  1918.       This program demonstrates use of the accumulation buffer to create an 
  1919.       out-of-focus depth-of-field effect.  The teapots are drawn several times 
  1920.       into the accumulation buffer.  The viewing volume is jittered, except at 
  1921.       the focal point, where the viewing volume is at the same position, each 
  1922.       time.  In this case, the gold teapot remains in focus. 
  1923.  
  1924.      DOFNOT 
  1925.  
  1926.       This program demonstrates the same scene as DOF.C, but without use of the 
  1927.       accumulation buffer, so that everything is in focus. 
  1928.  
  1929.      DOUBLE 
  1930.  
  1931.       This program demonstrates double buffering for flicker-free animation. 
  1932.       The left and middle mouse buttons start and stop the spinning motion of 
  1933.       the square. 
  1934.  
  1935.      DRAWF 
  1936.  
  1937.       This program draws the bitmapped letter F on the screen several times. 
  1938.       This demonstrates use of the glBitmap() function. 
  1939.  
  1940.      FEEDBACK 
  1941.  
  1942.       This program demonstrates use of OpenGL feedback.  First, a lighting 
  1943.       environment is set up and a few lines are drawn. Then feedback mode is 
  1944.       entered and the same lines are drawn.  The results in the feedback buffer 
  1945.       are printed. 
  1946.  
  1947.      FOG 
  1948.  
  1949.       This program draws five red teapots, each at a different Z-distance from 
  1950.       the eye, in different types of fog. By pressing the left mouse button, 
  1951.       you can choose between three types of fog:  exponential, exponential 
  1952.       squared, and linear. In this program, there is a fixed density value, as 
  1953.       well as fixed start and end values for the linear fog. 
  1954.  
  1955.      FOGINDEX 
  1956.  
  1957.       This program demonstrates fog in color index mode. Three cones are drawn 
  1958.       at different Z-values in a linear fog.  Thirty-two contiguous colors 
  1959.       (from 16 to 47) are loaded with a color ramp. 
  1960.  
  1961.      FONT 
  1962.  
  1963.       This program draws some text in a bitmapped font using glBitmap() and 
  1964.       other pixel routines.  FONT also demonstrates use of display lists. 
  1965.  
  1966.      LIGHT 
  1967.  
  1968.       This program demonstrates the use of the OpenGL lighting model.  A sphere 
  1969.       is drawn using a grey material characteristic. A single light source 
  1970.       illuminates the object. 
  1971.  
  1972.      LINELIST 
  1973.  
  1974.       This program demonstrates the use of display lists to call different line 
  1975.       stipples. 
  1976.  
  1977.      LINES 
  1978.  
  1979.       This program demonstrates different line stipples and widths. 
  1980.  
  1981.      LIST 
  1982.  
  1983.       This program demonstrates how to make and execute a display list.  Note 
  1984.       that attributes, such as current color and matrix, are changed. 
  1985.  
  1986.      LIST2 
  1987.  
  1988.       This program demonstrates the use of glGenList() and glPushAttrib(). The 
  1989.       matrix and color are restored before the line is drawn. 
  1990.  
  1991.      MAPLIGHT 
  1992.  
  1993.       This program demonstrates the use of the GL lighting model. A sphere is 
  1994.       drawn using a magenta diffuse reflective and white specular material 
  1995.       property. A single light source illuminates the object.  This program 
  1996.       illustrates lighting in color-map mode. 
  1997.  
  1998.      MATERIAL 
  1999.  
  2000.       This program demonstrates the use of the GL lighting model. Several 
  2001.       objects are drawn using different material characteristics. A single 
  2002.       light source illuminates the objects. 
  2003.  
  2004.      MIPMAP 
  2005.  
  2006.       This program demonstrates using mipmaps for texture maps. To overtly show 
  2007.       the effect of mipmaps, each mipmap reduction level has a solid colored, 
  2008.       contrasting texture image. Thus, the quadrilateral is drawn with several 
  2009.       different colors. 
  2010.  
  2011.      MODEL 
  2012.  
  2013.       This program demonstrates the use of OpenGL modeling transformations. 
  2014.       Four triangles are drawn, each with a different transformation. 
  2015.  
  2016.      MVLIGHT 
  2017.  
  2018.       This program demonstrates when to issue lighting and transformation 
  2019.       commands to render a model with a light, which is moved by a modeling 
  2020.       transformation (rotate or translate).  The light position is reset after 
  2021.       the modeling transformation is called.  The eye position does not change. 
  2022.  
  2023.       A sphere is drawn using a grey material characteristic. A single light 
  2024.       source illuminates the object. 
  2025.  
  2026.       By pressing the left or middle mouse button, you can alter the modeling 
  2027.       transformation (X-rotation) by 30 degrees. The scene is then redrawn with 
  2028.       the light in a new position. 
  2029.  
  2030.      NURBS 
  2031.  
  2032.       This program shows a NURBS (Non-uniform rational B-splines) surface, 
  2033.       shaped like a heart. 
  2034.  
  2035.      PICKDPTH 
  2036.  
  2037.       This program demonstrates picking.  In rendering mode, three overlapping 
  2038.       rectangles are drawn.  When you press the left mouse button, you enter 
  2039.       selection mode with the picking matrix. Rectangles that are drawn under 
  2040.       the cursor position are " picked."  Note the depth value range that is 
  2041.       returned. 
  2042.  
  2043.      PICKLINE 
  2044.  
  2045.       This program demonstrates picking.  Press the left mouse button to enter 
  2046.       picking mode.  You get two hits if you press the mouse, while the cursor 
  2047.       is where the lines intersect. 
  2048.  
  2049.      PICKSQR 
  2050.  
  2051.       This program demonstrates using multiple names and picking. A 3x3 grid of 
  2052.       squares is drawn.  When you press the left mouse button, all squares 
  2053.       under the cursor position change color. 
  2054.  
  2055.      PLANE 
  2056.  
  2057.       This program demonstrates the use of local versus infinite lighting on a 
  2058.       flat plane. 
  2059.  
  2060.      PLANET 
  2061.  
  2062.       This program shows how to composite modeling transformations to draw 
  2063.       translated and rotated models. 
  2064.  
  2065.       By pressing the Left, Right, Up, or Down Arrow key, you can alter the 
  2066.       rotation of the planet around the sun. 
  2067.  
  2068.      PLANETUP 
  2069.  
  2070.       In this program, the planets (from PLANET.C) have been rotated so their 
  2071.       polar regions are north/south. 
  2072.  
  2073.       By pressing the Left, Right, Up, or Down Arrow key, you can alter the 
  2074.       rotation of the planet around the sun. 
  2075.  
  2076.      POLYS 
  2077.  
  2078.       This program demonstrates polygon stippling. 
  2079.  
  2080.      ROBOT 
  2081.  
  2082.       This program shows how to composite modeling transformations to draw 
  2083.       translated and rotated hierarchical models. 
  2084.  
  2085.       By pressing any of the arrow keys, you can alter the rotation of the 
  2086.       robot arm. 
  2087.  
  2088.      SCENE 
  2089.  
  2090.       This program demonstrates the use of the GL lighting model. Objects are 
  2091.       drawn using a grey material characteristic. A single light source 
  2092.       illuminates the objects. 
  2093.  
  2094.      SCNBAMB 
  2095.  
  2096.       This program demonstrates use of a blue ambient light source. 
  2097.  
  2098.      SCNFLAT 
  2099.  
  2100.       This program draws lighted objects with flat shading. 
  2101.  
  2102.      SCNLIGHT 
  2103.  
  2104.       This program demonstrates the use of a colored (magenta, in this example) 
  2105.       light source.  Objects are drawn using a grey material characteristic. A 
  2106.       single light source illuminates the objects. 
  2107.  
  2108.      SELECT 
  2109.  
  2110.       This program is an illustration of the selection mode and name stack, 
  2111.       which detect whether objects collide with a viewing volume.  First, four 
  2112.       triangles and a rectangular box representing a viewing volume are drawn 
  2113.       (drawScene routine). The green triangle and yellow triangles appear to 
  2114.       lie within the viewing volume, but the red triangle appears to lie 
  2115.       outside it.  Then, the selection mode is entered (selectObjects routine). 
  2116.       Drawing to the screen ceases. To see if any collisions occur, the four 
  2117.       triangles are called.  In this example, the green triangle causes one hit 
  2118.       with the name 1 and the yellow triangles cause one hit with the name 3. 
  2119.  
  2120.      SIMPLE 
  2121.  
  2122.       This program draws a white rectangle on a black background. 
  2123.  
  2124.      SMOOTH 
  2125.  
  2126.       This program demonstrates smooth shading. A smooth shaded polygon is 
  2127.       drawn in a 2-D projection. 
  2128.  
  2129.      SPHERE 
  2130.  
  2131.       This program draws a wire frame sphere.  It uses glTranslatef() as a 
  2132.       viewing transformation. 
  2133.  
  2134.      STENCIL 
  2135.  
  2136.       This program draws two rotated tori in a window. A diamond in the center 
  2137.       of the window masks out part of the scene.  Within this mask, a different 
  2138.       model (a sphere) is drawn in a different color. 
  2139.  
  2140.      STROKE 
  2141.  
  2142.       This program demonstrates some characters of a stroke (vector) font.  The 
  2143.       characters are represented by display lists, which are given numbers 
  2144.       which correspond to the ASCII values of the characters. Use of 
  2145.       glCallLists() is demonstrated. 
  2146.  
  2147.      SURFACE 
  2148.  
  2149.       This program draws a NURBS surface in the shape of a symmetrical hill. 
  2150.  
  2151.      TEA 
  2152.  
  2153.       This program demonstrates two-sided lighting and compares it with 
  2154.       one-sided lighting.  Three teapots are drawn, with a clipping plane to 
  2155.       expose the interior of the objects. 
  2156.  
  2157.      TEAAMB 
  2158.  
  2159.       This program renders three lighted, shaded teapots, with different 
  2160.       ambient values. 
  2161.  
  2162.      TEAPOTS 
  2163.  
  2164.       This program demonstrates several material properties. A single light 
  2165.       source illuminates the objects. 
  2166.  
  2167.      TEXGEN 
  2168.  
  2169.       This program draws a texture mapped teapot with automatically generated 
  2170.       texture coordinates.  The texture is rendered as stripes on the teapot. 
  2171.  
  2172.      TEXSURF 
  2173.  
  2174.       This program uses evaluators to generate a curved surface and 
  2175.       automatically generated texture coordinates. 
  2176.  
  2177.      TRIM 
  2178.  
  2179.       This program draws a NURBS surface in the shape of a symmetrical hill, 
  2180.       using both a NURBS curve and pwl (piecewise linear) curve to trim part of 
  2181.       the surface. 
  2182.  
  2183.  
  2184. ΓòÉΓòÉΓòÉ 7.3.7.2. GLUTDEMO Sample Programs ΓòÉΓòÉΓòÉ
  2185.  
  2186. The following Graphics Library Utility Toolkit (GLUT) samples are provided in 
  2187. the OS/2 Warp Toolkit: 
  2188.  
  2189.      ATLANTIS 
  2190.  
  2191.       ATLANTIS displays sea-life (whales, sharks, and dolphins) using OpenGL 
  2192.       for rendering and the Graphics Library Utility Toolkit for window and 
  2193.       user interaction control. 
  2194.  
  2195.      TEST7 
  2196.  
  2197.       TEST7 demonstrates window manipulation using the Graphics Library Utility 
  2198.       Toolkit. 
  2199.  
  2200.  
  2201. ΓòÉΓòÉΓòÉ 7.3.8. OS/2 Sample Programs ΓòÉΓòÉΓòÉ
  2202.  
  2203. The OS/2 sample programs are as follows: 
  2204.  
  2205.      CLOCK - Timer Services Sample 
  2206.      DLLAPI - Dynamic Link Library Sample 
  2207.      EAS - Extended Attributes Editor 
  2208.      HANOI - Multithreaded Sample (Towers of Hanoi) 
  2209.      NPIPE - Named Pipe Sample 
  2210.      QUEUES - Interprocess Communication Queue Sample 
  2211.      SEMAPH - Semaphore Sample 
  2212.      SORT - Mulithreaded Sample (Sorting Algorithm) 
  2213.      TIMER0 - High Resolution Timer Sample 
  2214.      VMM - Virtual Memory Management Sample 
  2215.      WORMS - Console I/O Sample 
  2216.  
  2217.  
  2218. ΓòÉΓòÉΓòÉ 7.3.8.1. CLOCK Sample Program ΓòÉΓòÉΓòÉ
  2219.  
  2220. CLOCK (located in \TOOLKIT\SAMPLES\OS2\TIMESERV) demonstrates how to use and 
  2221. implement window timers and system-resource timers. This sample program 
  2222. displays both an analog and digital clock. To simulate elapsed seconds, the 
  2223. main PM thread repeatedly sets a one-second window timer that updates the 
  2224. current time. 
  2225.  
  2226. CLOCK features an audible and visual alarm that you can set. When the time 
  2227. expires, the sample makes use of the DOS timer services and notifies the user 
  2228. by sounding an alarm and displaying a message box. 
  2229.  
  2230.  
  2231. ΓòÉΓòÉΓòÉ 7.3.8.2. DLLAPI Sample Program ΓòÉΓòÉΓòÉ
  2232.  
  2233. DLLAPI (located in \TOOLKIT\SAMPLES\OS2\DLLAPI) demonstrates how to write and 
  2234. use a dynamic link library (DLL). The sample has a .DLL file and an executable 
  2235. (.EXE) file. The .DLL provides the 32-bit API function that is called by the 
  2236. .EXE file. 
  2237.  
  2238. The .DLL uses protected memory on its shared data, and exception management to 
  2239. validate the pointer parameters for a 32-bit API function. The .EXE file 
  2240. demonstrates how to handle a divide-by-zero exception, and calls the function 
  2241. with invalid pointer parameters, followed by a call with valid pointer 
  2242. parameters. 
  2243.  
  2244.  
  2245. ΓòÉΓòÉΓòÉ 7.3.8.3. EAS Sample Program ΓòÉΓòÉΓòÉ
  2246.  
  2247. EAS (located in \TOOLKIT\SAMPLES\OS2\EAEDIT) demonstrates a multithreaded 
  2248. application that retrieves, modifies, or sorts files by their extended 
  2249. attribute value. Included in this sample program are PM procedures for dialog 
  2250. boxes and a standard client window. The sample lets you select an extended 
  2251. attribute file name from a list, or enter a new name in an entry field. You can 
  2252. select the extended attribute type from a table. 
  2253.  
  2254.  
  2255. ΓòÉΓòÉΓòÉ 7.3.8.4. HANOI Sample Program ΓòÉΓòÉΓòÉ
  2256.  
  2257. HANOI (located in \TOOLKIT\SAMPLES\OS2\HANOI) demonstrates a multithreaded 
  2258. application with the familiar "towers of Hanoi" puzzle. When the sample program 
  2259. is started, you see three poles (A, B, and C). Initially, pole A has on it a 
  2260. stack of disks starting with the largest disks on the bottom and succeeding 
  2261. smaller disks on the top. The main thread handles the PM interface and lets the 
  2262. you start or stop the Hanoi routine. It also lets you reset the number of 
  2263. working disks. The second thread is created when the Start item is selected 
  2264. from the Options menu. This thread starts the recursive execution of the Hanoi 
  2265. algorithm, runs in the background, and moves and paints the disks. All disks 
  2266. end up on pole C. 
  2267.  
  2268.  
  2269. ΓòÉΓòÉΓòÉ 7.3.8.5. NPIPE Sample Program ΓòÉΓòÉΓòÉ
  2270.  
  2271. NPIPE (located in \TOOLKIT\SAMPLES\OS2\NPIPE) demonstrates two-way 
  2272. communication between two unrelated processes using named pipe functions. This 
  2273. sample program implements the game of TicTacToe with two executable files: 
  2274.  
  2275.      CLINPIPE.EXE (the client) 
  2276.  
  2277.       The client is the user.  For example, the client will: 
  2278.  
  2279.         -  Connect to the server and acknowledge successful connection 
  2280.            (START_MSG). 
  2281.         -  Notify the server through a pipe when it wishes to begin play 
  2282.            (YOU_FIRST or CLIENT_MOVE). 
  2283.         -  Notify the server when it wishes to quit (CLIENT_QUIT). 
  2284.         -  Send the server a valid move when requested by the server 
  2285.            (CLIENT_MOVE). 
  2286.  
  2287.      SVRNPIPE.EXE (the server) 
  2288.  
  2289.       The server is the computer.  For example, the server will: 
  2290.  
  2291.         -  Connect a pipe to the client through which play will be executed 
  2292.            (START_MSG) upon the initial request of a client to play. 
  2293.         -  Play with many clients simultaneously. 
  2294.         -  Notify the client of the server's move, and request a valid move 
  2295.            from the client (SERVER_MOVE). 
  2296.         -  Notify the client of game-end (WIN_SERVER, WIN_CLIENT, WIN_DRAW). 
  2297.  
  2298.  
  2299. ΓòÉΓòÉΓòÉ 7.3.8.6. QUEUES Sample Program ΓòÉΓòÉΓòÉ
  2300.  
  2301. QUEUES (located in \TOOLKIT\SAMPLES\OS2\QUEUES) demonstrates interprocess 
  2302. communications (IPC) using the 32-bit queue component. It consists of two 
  2303. executable programs: 
  2304.  
  2305.      SVRQUEUE.EXE 
  2306.  
  2307.       Creates an IPC queue; a named, shared-memory buffer for queue elements; 
  2308.       and a shared, named, mutex (mutual exclusive) semaphore. After 
  2309.       initializing the queue, SVRQUEUE starts a thread to read from the queue, 
  2310.       prints the contents of the messages read from the queue, and terminates 
  2311.       at the user's request. 
  2312.  
  2313.      CLIQUEUE.EXE 
  2314.  
  2315.       Opens the queue and accesses the shared-memory element buffer and mutex 
  2316.       semaphore, and starts a thread to write to the queue. CLIQUEUE requests a 
  2317.       string of data from the user, allocates a shared-memory element from the 
  2318.       buffer, puts the string in the shared-memory element, and then uses an 
  2319.       event semaphore to direct the thread to write the element to the queue. 
  2320.       CLIQUEUE terminates at the user's request. 
  2321.  
  2322.  
  2323. ΓòÉΓòÉΓòÉ 7.3.8.7. SEMAPH Sample Program ΓòÉΓòÉΓòÉ
  2324.  
  2325. SEMAPH (located in \TOOLKIT\SAMPLES\OS2\SEMAPH) demonstrates the use of mutex 
  2326. and event semaphores. In the sample, several threads share access to the same 
  2327. resource. 
  2328.  
  2329. A mutex semaphore is used to guarantee that only one thread has access to the 
  2330. resource at a time.  A mutex semaphore is used to check for a stop event or for 
  2331. a user signal to give up the resource. 
  2332.  
  2333. An event semaphore is used to signal the thread to give up the resource. An 
  2334. event semaphore can be posted by the user, or run in auto mode, in which case 
  2335. the event semaphore will be posted at fixed time intervals. 
  2336.  
  2337. Each thread can be displayed as a square of a unique color. Similarly, the 
  2338. resource can be displayed as a rectangle; its color is that of the first thread 
  2339. that owns it. 
  2340.  
  2341.  
  2342. ΓòÉΓòÉΓòÉ 7.3.8.8. SORT Sample Program ΓòÉΓòÉΓòÉ
  2343.  
  2344. SORT (located in \TOOLKIT\SAMPLES\OS2\SORT) demonstrates the use of multiple 
  2345. threads by performing multiple sorts at the same time. Each sorting algorithm 
  2346. runs from a separate thread. The main thread is used to handle the main 
  2347. window's messages, while the routine that updates the display is run from 
  2348. another thread. 
  2349.  
  2350.  
  2351. ΓòÉΓòÉΓòÉ 7.3.8.9. TIMER0 Sample Program ΓòÉΓòÉΓòÉ
  2352.  
  2353. TIMER0 (located in \TOOLKIT\SAMPLES\OS2\TIMER0) creates four threads. Each 
  2354. thread does the following: 
  2355.  
  2356.    1. Sets its priority to time-critical. 
  2357.  
  2358.    2. Sleeps for n milliseconds, where n is equal to 500 times the number of 
  2359.       the thread (for example, thread #1 sleeps 500ms, thread #2 sleeps 1000ms, 
  2360.       and so on). 
  2361.  
  2362.    3. Wakes up and increments a counter. 
  2363.  
  2364.  To start the TIMER0 sample from an OS/2 command line, type: 
  2365.  
  2366.   TIMER0
  2367.  
  2368.  While the four threads are running, the main thread (the one that created the 
  2369.  other four) is in an infinite loop. 
  2370.  
  2371.  Note:  To break out of the loop, press any key. 
  2372.  
  2373.  This loop displays the values of each of the four counters incremented by the 
  2374.  four threads.  For example: 
  2375.  
  2376.   TIMER0$ opened.  File Handle is 3
  2377.   Counter: 00008703  1:00000017 2:00000008 3:00000005 4:00000004
  2378.  
  2379.  The counter is the value of the millisecond counter in timer TIMER0 device 
  2380.  driver.  This value gets incremented every millisecond and is very accurate. 
  2381.  The other four values are the four counters and these values are incremented 
  2382.  by each thread.  The accuracy is dependent on the thread contention and other 
  2383.  things that are going on in the system.  Note that #2 is approximately 
  2384.  one-half of #1, #3 is approximately one-third of #1, and #4 is approximately 
  2385.  one-fourth of #1. 
  2386.  
  2387.  
  2388. ΓòÉΓòÉΓòÉ 7.3.8.10. VMM Sample Program ΓòÉΓòÉΓòÉ
  2389.  
  2390. VMM (located in \TOOLKIT\SAMPLES\OS2\VMM) demonstrates the use of virtual 
  2391. memory by using new memory-management functions to allocate and set the 
  2392. attributes of memory. Users can read or write data into memory and reset the 
  2393. attributes using a dialog box. The memory manager protects or opens the virtual 
  2394. memory to read or write operations according to the different attributes of 
  2395. each memory block. To free memory, the user enters the address of the memory. 
  2396.  
  2397.  
  2398. ΓòÉΓòÉΓòÉ 7.3.8.11. WORMS Sample Program ΓòÉΓòÉΓòÉ
  2399.  
  2400. WORMS (located in \TOOLKIT\SAMPLES\OS2\CONSOLIO) demonstrates how to call video 
  2401. (Vio), keyboard (Kbd), and mouse (Mou) 16-bit function from a 32-bit code 
  2402. segment. This sample program displays earthworms aimlessly moving about the 
  2403. screen. Each worm is a separate thread with a unique color combination and 
  2404. movement pattern. When one worm encounters another worm, the color attribute of 
  2405. the worm is set to red. You can add or delete worms using the keyboard or 
  2406. mouse. 
  2407.  
  2408.  
  2409. ΓòÉΓòÉΓòÉ 7.3.9. Presentation Manager Sample Programs ΓòÉΓòÉΓòÉ
  2410.  
  2411. The PM sample programs are as follows: 
  2412.  
  2413.      CLIPBRD - Clipboard Sample 
  2414.      DIALOG - Introductory Dialog Box Sample 
  2415.      DRAGDROP - Direct Manipulation (Dragdrop) Sample 
  2416.      GRAPHIC - Non-retained Graphics Sample 
  2417.      HELLO - Standard Windows Sample 
  2418.      IMAGE32 - PM 16-bit to 32-bit Porting Sample 
  2419.      IPF - Information Presentation Facility Sample 
  2420.      JIGSAW - Bitmap Manipulation Sample 
  2421.      PALETTE - Palette Sample 
  2422.      PRINT - Printer Sample Program 
  2423.      STYLE - PM Controls Sample 
  2424.      TEMPLATE - Application Template 
  2425.  
  2426.  
  2427. ΓòÉΓòÉΓòÉ 7.3.9.1. CLIPBRD Sample Program ΓòÉΓòÉΓòÉ
  2428.  
  2429. CLIPBRD (located in \TOOLKIT\SAMPLES\PM\CLIPBRD) demonstrates how to provide a 
  2430. PM interface to the clipboard. Initially, this sample program displays a 
  2431. standard window with a bitmap. You can cut and paste rectangular images in this 
  2432. window, using the system clipboard as an intermediate storage area. 
  2433.  
  2434.  
  2435. ΓòÉΓòÉΓòÉ 7.3.9.2. DIALOG Sample Program ΓòÉΓòÉΓòÉ
  2436.  
  2437. DIALOG (located in \TOOLKIT\SAMPLES\PM\DIALOG) demonstrates how to associate a 
  2438. dialog box with a standard window. The dialog box is defined as a dialog 
  2439. template in a resource file. 
  2440.  
  2441. This sample program also demonstrates how to implement entry fields, push 
  2442. buttons, and message boxes. Message boxes are displayed only for error 
  2443. conditions. 
  2444.  
  2445.  
  2446. ΓòÉΓòÉΓòÉ 7.3.9.3. DRAGDROP Sample Program ΓòÉΓòÉΓòÉ
  2447.  
  2448. DRAGDROP (located in \TOOLKIT\SAMPLES\PM\DRAGDROP) demonstrates how to move 
  2449. files between directories by using the drag and drop operation of direct 
  2450. manipulation. This sample program creates a drop-down list box that contains a 
  2451. scrollable file name list of the current directory. 
  2452.  
  2453. To change the current directory, select the Window option, type in the 
  2454. directory name, and press Enter. To change the current directory to one higher 
  2455. in the directory tree, select File from the menu bar, and then Open. The Select 
  2456. subdirectory window is displayed. Type in the name of the subdirectory, and 
  2457. then select OK. 
  2458.  
  2459. DRAGDROP must be started twice, so that there are two running instances of the 
  2460. sample. Then, using a mouse, you can: 
  2461.  
  2462.      Display a directory file list in the first sample. 
  2463.      Select a file name from the second sample. 
  2464.      Drag the file name (using the right mouse button) to the directory in the 
  2465.       first sample. 
  2466.      Drop the file name into the directory in the first sample. 
  2467.  
  2468.  The file is now moved to the chosen directory of the first sample. 
  2469.  
  2470.  
  2471. ΓòÉΓòÉΓòÉ 7.3.9.4. GRAPHIC Sample Program ΓòÉΓòÉΓòÉ
  2472.  
  2473. GRAPHIC (located in \TOOLKIT\SAMPLES\PM\GRAPHICS) demonstrates how to use 
  2474. default viewing transformation functions of the PM. It also demonstrates how to 
  2475. use an asynchronous drawing thread. This sample program lets you load metafiles 
  2476. using a dialog box. The dialog box contains a Help push button. When the Help 
  2477. push button is activated, it provides instructions on loading a metafile from 
  2478. another directory. You also can print a metafile or graphic circle. 
  2479.  
  2480.  
  2481. ΓòÉΓòÉΓòÉ 7.3.9.5. HELLO Sample Program ΓòÉΓòÉΓòÉ
  2482.  
  2483. HELLO (located in \TOOLKIT\SAMPLES\PM\STDWND) demonstrates how to create and 
  2484. display a standard window that conforms to the Common User Access requirements. 
  2485.  
  2486. This sample program also demonstrates how to use resources defined in a script 
  2487. file. Initially, HELLO displays a standard window with the text "Hello." The 
  2488. Options conditional-cascaded menu contains three items. Each item paints a 
  2489. different text string in the window. 
  2490.  
  2491. This sample also shows how to override the Ctrl+C key combination. 
  2492.  
  2493.  
  2494. ΓòÉΓòÉΓòÉ 7.3.9.6. IMAGE32 Sample Program ΓòÉΓòÉΓòÉ
  2495.  
  2496. IMAGE32 (located in \TOOLKIT\SAMPLES\PM\PORTING) demonstrates how to migrate an 
  2497. existing OS/2 16-bit application to a 32-bit application. 
  2498.  
  2499. This sample also demonstrates how to display an image using the GpiImage 
  2500. function. The image data comes from a file that you must select using the 
  2501. standard File Open menu item. 
  2502.  
  2503.  
  2504. ΓòÉΓòÉΓòÉ 7.3.9.7. IPF Sample Program ΓòÉΓòÉΓòÉ
  2505.  
  2506. IPF (located in \TOOLKIT\SAMPLES\PM\IPF) demonstrates how to use the IPF to 
  2507. create an online document. This sample program features customized windows that 
  2508. display text, graphics, and animation. 
  2509.  
  2510. Two files are associated with this sample: 
  2511.  
  2512.      IPF online document (INF) 
  2513.  
  2514.       The .INF file is the compiled IPF document. The source contains tagging 
  2515.       that defines different types of windows. Tags that control the format and 
  2516.       display of text also are included in this file. 
  2517.  
  2518.      OS/2 dynamic link library (DLL) 
  2519.  
  2520.       The .DLL file is the compiled OS/2 C language source for the code object 
  2521.       that is called when the .INF file is read at run time. A series of 
  2522.       bitmaps used for animation are included in the .DLL. 
  2523.  
  2524.  
  2525. ΓòÉΓòÉΓòÉ 7.3.9.8. JIGSAW Sample Program ΓòÉΓòÉΓòÉ
  2526.  
  2527. JIGSAW (located in \TOOLKIT\SAMPLES\PM\BMPSAMP) demonstrates the use of bitmaps 
  2528. in a graphics application. This sample provides a jigsaw puzzle based on the 
  2529. decomposition of an arbitrary bitmap loaded from a file. You can jumble the 
  2530. pieces, and then drag them with a mouse. The image can be made smaller, larger, 
  2531. scrolled horizontally, or scrolled vertically. 
  2532.  
  2533. This sample program also demonstrates how to call the Information Presentation 
  2534. Facility help hook, to create an instance and associate the instance with the 
  2535. active application window. 
  2536.  
  2537.  
  2538. ΓòÉΓòÉΓòÉ 7.3.9.9. PALETTE Sample Program ΓòÉΓòÉΓòÉ
  2539.  
  2540. PALETTE (located in \TOOLKIT\SAMPLES\PM\PALETTE) demonstrates 32-bit graphics 
  2541. functions including: 
  2542.  
  2543.      Creating a window using a custom palette and animation. 
  2544.      Using menus with switches, and modifying the menu text. 
  2545.      Using multiple threads and semaphores in the Presentation Manager 
  2546.       environment. 
  2547.      Displaying graphics on the screen using outline fonts and clip paths. 
  2548.      Online help. 
  2549.  
  2550.  When started, PALETTE displays a standard window with a large OS/2 logo in the 
  2551.  foreground. You have the ability to change the OS/2 logo to the IBM logo. If 
  2552.  you resize the window, the logo is scaled and redrawn to fit the new window 
  2553.  size. You can also control the animation speed from the PALETTE menu. 
  2554.  
  2555.  The animation is performed by: 
  2556.  
  2557.      Creating a clip path that represents the outline of the logo characters 
  2558.       (which are displayed using an outline font). 
  2559.      Setting the clip path to the presentation space. 
  2560.      Drawing a series of lines to the presentation space. 
  2561.  
  2562.  Each line is drawn with an incremental color index. Palette animation is 
  2563.  performed using the 32-bit GpiAnimatePalette function. 
  2564.  
  2565.  In order for PALETTE to remain responsive to system and user messages, no 
  2566.  animation is performed on the main window procedure thread. A second thread is 
  2567.  created from which all animation is performed. 
  2568.  
  2569.  Hardware requirements: 
  2570.  
  2571.      XGA adapter 
  2572.      1MG of RAM 
  2573.      32-bit graphics engine 
  2574.  
  2575.  
  2576. ΓòÉΓòÉΓòÉ 7.3.9.10. PRINT Sample Program ΓòÉΓòÉΓòÉ
  2577.  
  2578. PRINT (located in \TOOLKIT\SAMPLES\PM\PRINT) demonstrates how to display and 
  2579. print text, metafiles, and bitmaps. It also demonstrates how to: 
  2580.  
  2581.      Query and display system printer configurations 
  2582.      Interact with printer drivers to change job properties 
  2583.      Query and display available printer and screen fonts 
  2584.      Query and display printer forms and setup margins 
  2585.      Selectively print part or all of a document on an asynchronous thread. 
  2586.  
  2587.  
  2588. ΓòÉΓòÉΓòÉ 7.3.9.11. STYLE Sample Program ΓòÉΓòÉΓòÉ
  2589.  
  2590. STYLE (located in \TOOLKIT\SAMPLES\PM\CONTROLS) demonstrates a PM application 
  2591. that conforms with the Common User Access requirements and implements the 
  2592. following controls: 
  2593.  
  2594.      Container 
  2595.      Notebook 
  2596.      Slider 
  2597.      Spin button 
  2598.      Value set 
  2599.  
  2600.  This sample program also demonstrates secondary windows, such as dialogs and 
  2601.  message boxes. The program lets you edit and save text files. The source for 
  2602.  online help, in IPF format, is also provided. 
  2603.  
  2604.  STYLE also demonstrates the detection of a font that does not conform to the 
  2605.  International Standards Organization (ISO 9241). When you are running the 
  2606.  sample on an ISO-compliant monitor and select a non-compliant font in the 
  2607.  standard font dialog, a message box is displayed. 
  2608.  
  2609.  The code in STYLE is structured so that the addition of a new function is 
  2610.  handled in an efficient manner. For example, to add a new command to an 
  2611.  existing menu, you need only add the command to the resource file, and then 
  2612.  add the appropriate message-processing routines to the STY_USER.C file. 
  2613.  
  2614.  
  2615. ΓòÉΓòÉΓòÉ 7.3.9.12. TEMPLATE Sample Program ΓòÉΓòÉΓòÉ
  2616.  
  2617. TEMPLATE (located in \TOOLKIT\SAMPLES\PM\TEMPLATE) demonstrates the structure 
  2618. common to all PM applications. This sample program shows how to structure an 
  2619. application that has more than one source file. It includes the initialization 
  2620. file (which is used and then discarded), the resident code, and the 
  2621. non-resident code that is loaded only when needed. 
  2622.  
  2623. TEMPLATE also demonstrates how to: 
  2624.  
  2625.      Create a standard window 
  2626.      Load resources from a resource file 
  2627.      Create a dialog box and a button control 
  2628.      Display a message box 
  2629.      Open a file 
  2630.      Close a file 
  2631.      Print text 
  2632.      Paint a window 
  2633.      Process a message from a menu 
  2634.      Run a thread in the background 
  2635.      Exit a process. 
  2636.  
  2637.  Several online help files are also provided in IPF format. 
  2638.  
  2639.  
  2640. ΓòÉΓòÉΓòÉ 7.3.10. Problem Determination Sample Programs ΓòÉΓòÉΓòÉ
  2641.  
  2642. The Problem Determination sample programs are categorized as follows: 
  2643.  
  2644.      DMI - Desktop Management Interface Samples 
  2645.      ERRLOG  - Logging Framework Samples 
  2646.      FFST - First Failure Support Technology Sample 
  2647.      TRACE - Trace Sample 
  2648.  
  2649.  
  2650. ΓòÉΓòÉΓòÉ 7.3.10.1. DMI ΓòÉΓòÉΓòÉ
  2651.  
  2652. The following desktop management interface (DMI) samples are included with the 
  2653. OS/2 Warp Toolkit. They are used in conjunction with the DMI MIF Browser, which 
  2654. is provided with the OS/2 Warp Version 4 or later operating system. 
  2655.  
  2656.      DMI Overlay (DLL) Componentry Sample 
  2657.      DMI Direct Interface Componentry Sample 
  2658.  
  2659.  
  2660. ΓòÉΓòÉΓòÉ 7.3.10.1.1. DMI Overlay (DLL) Componentry Sample ΓòÉΓòÉΓòÉ
  2661.  
  2662. The DMI Overlay Componentry sample (NAMES.C) is located in the 
  2663. \TOOLKIT\SAMPLES\SYSMGT\DMI\NAMES subdirectory. To use NAMES, do the following: 
  2664.  
  2665.    1. Install the NAMES.MIF file into the DMI database. 
  2666.  
  2667.         a. Open the Problem Determination Tools folder (located in the OS/2 
  2668.            System folder). 
  2669.  
  2670.         b. Start the DMI MIF Browser. 
  2671.  
  2672.         c. Select Install new from the Components menu. 
  2673.  
  2674.         d. Select NAMES.MIF. 
  2675.  
  2676.         e. Do not close the DMI MIF Browser. 
  2677.  
  2678.    2. Copy the NAMES.DLL to a directory in the LIBPATH. 
  2679.  
  2680.    3. A component called DMI Service Layers will be created in the DMI MIF 
  2681.       browser.  Expand the component and double-click on one of the groups to 
  2682.       see information about the operating system, company name, and the name of 
  2683.       the DMI service layer.  This information is coming from the NAMES.DLL 
  2684.       file. 
  2685.  
  2686.  
  2687. ΓòÉΓòÉΓòÉ 7.3.10.1.2. DMI Direct Interface Componentry Sample ΓòÉΓòÉΓòÉ
  2688.  
  2689. The DMI Direct Interface Componentry sample (NAMEDIR.C) is located in the 
  2690. \TOOLKIT\SAMPLES\SYSMGT\DMI\NAMEDIR subdirectory. 
  2691.  
  2692. To use NAMEDIR, do the following: 
  2693.  
  2694.    1. Copy the NAMEDIR.MIF file to the \DMIPATH directory. 
  2695.  
  2696.    2. Open the Problem Determination Tools folder (located in the OS/2 System 
  2697.       folder). 
  2698.  
  2699.    3. Start the DMI MIF Browser. 
  2700.  
  2701.    4. From an OS/2 session, run the NAMEDIR.EXE program.  The following two 
  2702.       things will happen: 
  2703.  
  2704.           A new component will be added to the DMI database and will be 
  2705.            displayed in the DMI MIF Browser.  The name of the component will be 
  2706.            DMI Service Layers - Direct Interface (DI) version. 
  2707.  
  2708.           The OS/2 session will display the following messages: 
  2709.  
  2710.                           Preparing to install 'NAMEDIR.MIF'
  2711.                           Installation successful ComponentID=6.
  2712.                           Preparing to register component id 6
  2713.                           I got started
  2714.  
  2715.    5. Expand the new component and double-click on one of the groups to see 
  2716.       information about the operating system, company name, and the name of the 
  2717.       DMI service layer.  This information is coming from the NAMEDIR.EXE file. 
  2718.  
  2719.  
  2720. ΓòÉΓòÉΓòÉ 7.3.10.2. ERRLOG ΓòÉΓòÉΓòÉ
  2721.  
  2722. The following samples demonstrate use of the logging functions. 
  2723.  
  2724.      ERRLOG1 
  2725.      ERRLOG2 
  2726.  
  2727.  It is helpful to run these sample files using a debugger so that you can step 
  2728.  through the code to see the function the API is actually providing. 
  2729.  
  2730.  
  2731. ΓòÉΓòÉΓòÉ 7.3.10.2.1. ERRLOG1 ΓòÉΓòÉΓòÉ
  2732.  
  2733. ERRLOG1 (located in \TOOLKIT\SAMPLES\SYSMGT\ERRLOG\ERRLOG1) demonstrates how to 
  2734. use the following functions to open a file, read an entry from the log, format 
  2735. that entry, and then close the log. 
  2736.  
  2737.       LogOpenFile 
  2738.       LogReadEntry 
  2739.       LogFormatEntry 
  2740.       LogCloseFile 
  2741.  
  2742.  The program displays a message indicating whether each function call was 
  2743.  successful or not. 
  2744.  
  2745.  If the error log is empty, the program will end after the LogReadEntry 
  2746.  function call with a return code of 1750 indicating the end of the file was 
  2747.  reached without finding the desired record.  To have the program run 
  2748.  successfully, run the FFSTProbe sample program (PROBE.EXE) to put an entry in 
  2749.  the log.  PROBE.EXE is located in the \TOOLKIT\SAMPLES\SYSMGT\FFST\PROBE 
  2750.  subdirectory. 
  2751.  
  2752.  
  2753. ΓòÉΓòÉΓòÉ 7.3.10.2.2. ERRLOG2 ΓòÉΓòÉΓòÉ
  2754.  
  2755. ERRLOG2 (located in \TOOLKIT\SAMPLES\SYSMGT\ERRLOG\ERRLOG2) demonstrates how to 
  2756. use the following functions to open event notification, wait on an error log 
  2757. event, change an event filter, and then close event notification. 
  2758.  
  2759.       LogOpenEventNotification 
  2760.       LogWaitEvent 
  2761.       LogChangeEventFilter 
  2762.       LogCloseEventNotification 
  2763.  
  2764.  The program displays a message after each error logging function call 
  2765.  indicating whether the call was successful or not.  Because this program is 
  2766.  using the event notification functions, it will pause twice as it's waiting 
  2767.  for an error to be logged. At this time it will display a message indicating 
  2768.  that it is waiting for an event. 
  2769.  
  2770.  When event notification is started a filter is not specified.  Therefore, on 
  2771.  the first use of LogWaitEvent, any record placed in the log will cause the 
  2772.  notification to occur.  The LogChangeEventFilter function is then used to 
  2773.  filter on records where the vendor tag field contains IBM or the severity of 
  2774.  the error is less than, or equal, to 2.  In either case, the FFSTProbe sample 
  2775.  program (PROBE.EXE) will cause the notification to occur. 
  2776.  
  2777.  To run ERRLOG2, do the following: 
  2778.  
  2779.    1. At an OS/2 command line, type: 
  2780.  
  2781.             ERRLOG2
  2782.  
  2783.       It will run to the point where it displays a message stating that it is 
  2784.       waiting for an event. 
  2785.  
  2786.    2. Open another OS/2 window and start the FFSTProbe sample program by 
  2787.       changing to the \TOOLKIT\SAMPLES\SYSMGT\FFST\PROBE subdirectory and 
  2788.       typing: 
  2789.  
  2790.             PROBE
  2791.  
  2792.       The ERRLOG2 program will display messages stating that it has received an 
  2793.       event, that it's changing the event filter, and that it is waiting for an 
  2794.       event. 
  2795.  
  2796.    3. Open another OS/2 window and start the FFSTProbe sample program again. 
  2797.  
  2798.       The ERRLOG2 program will again display a message stating that it has 
  2799.       received an event, followed by a message stating that it is closing event 
  2800.       notification. 
  2801.  
  2802.  
  2803. ΓòÉΓòÉΓòÉ 7.3.10.3. FFST ΓòÉΓòÉΓòÉ
  2804.  
  2805. PROBE (located in \TOOLKIT\SAMPLES\SYSMGT\FFST\PROBE) shows how to use the 
  2806. FFSTProbe function. You should use the FFSTProbe function with a "wrapper" 
  2807. function. An example of a wrapper function is included in this sample code. You 
  2808. can add or delete parameters sent to the wrapper function based on your own 
  2809. needs. 
  2810.  
  2811. To run the PROBE sample, do the following: 
  2812.  
  2813.    1. Copy PROBE.MSG and PROBE.REP into the \OS2\SYSTEM directory. PROBEMSG.TXT 
  2814.       and PROBEREP.TXT are the source files used to create the message and 
  2815.       template repository files. 
  2816.  
  2817.    2. Install the MIF file into the DMI database. 
  2818.  
  2819.         a. Open the Problem Determination Tools folder (located in the OS/2 
  2820.            System folder). 
  2821.  
  2822.         b. Start the DMI MIF Browser. 
  2823.  
  2824.         c. Select Install new from the Components menu. 
  2825.  
  2826.         d. Select PROBE.MIF. 
  2827.  
  2828.         e. Do not close the DMI MIF Browser. 
  2829.  
  2830.    3. At an OS/2 command line type: 
  2831.  
  2832.             PROBE
  2833.  
  2834.  After the PROBE sample runs, use the System Error Logger (in the Problem 
  2835.  Determination Tools folder) to view the two probe entries, 1111 and 2222. 
  2836.  Double-click on the entries to view detailed information. 
  2837.  
  2838.  
  2839. ΓòÉΓòÉΓòÉ 7.3.10.4. TRACE ΓòÉΓòÉΓòÉ
  2840.  
  2841. TRACEEXP (located in \TOOLKIT\SAMPLES\SYSMGT\TRACE) shows how to create a trace 
  2842. event in the system-event trace buffer. The Trace Create Entry Request packet 
  2843. is initialized with the major code, minor code, length of data to be collected 
  2844. (if any), and starting address of the data (or NULL). The size of the packet 
  2845. and the trace release number must also be supplied. 
  2846.  
  2847. The call to TraceCreateEntry() will place this data into the system-event trace 
  2848. buffer if the major and minor codes were turned on by the user. If trace is not 
  2849. enabled, or if the major and minor code combination is not turned on, the call 
  2850. to TraceCreateEntry() performs no action. 
  2851.  
  2852. Use the Trace Formatter, provided with the OS/2 Warp Version 4 or later 
  2853. operating system, to look at the system-event trace buffer. 
  2854.  
  2855. For more information on using this sample, see Starting TRACEEXP. 
  2856.  
  2857.  
  2858. ΓòÉΓòÉΓòÉ 7.3.10.4.1. Starting TRACEEXP ΓòÉΓòÉΓòÉ
  2859.  
  2860. To run the TRACEEXP sample, you need one or both of the following lines in your 
  2861. CONFIG.SYS: 
  2862.  
  2863. trace=on
  2864. tracebuf=4
  2865.  
  2866. Be sure to restart your system if you make changes to CONFIG.SYS. 
  2867.  
  2868. Turn on trace for the major code in this example by typing the following: 
  2869.  
  2870. trace on 123
  2871.  
  2872. To run the sample, type: 
  2873.  
  2874. traceexp
  2875.  
  2876. To turn the trace off, type: 
  2877.  
  2878. trace off
  2879.  
  2880. To see the captured trace point, type: 
  2881.  
  2882. tracefmt
  2883.  
  2884. This should show an entry with major code 123. 
  2885.  
  2886.  
  2887. ΓòÉΓòÉΓòÉ 7.3.11. REXX Sample Programs ΓòÉΓòÉΓòÉ
  2888.  
  2889. The REXX sample programs are as follows: 
  2890.  
  2891.      CALLREXX 
  2892.      DEVINFO 
  2893.      PMREXX 
  2894.      REXXCALC 
  2895.      REXXUTIL 
  2896.      RXMACDLL 
  2897.      REXX Animal SOM Class Sample 
  2898.      REXX Workplace Shell Class Sample 
  2899.      REXX Workplace Shell Folder Sample 
  2900.      REXX Complex Number Sample 
  2901.      REXX Concurrency Sample 
  2902.      REXX Directives Sample 
  2903.      REXX Display Month Array Sample 
  2904.      REXX Factorial Sample 
  2905.      REXX Guard and Reply Sample 
  2906.      REXX Pipe Sample 
  2907.      REXX Query Date Sample 
  2908.      REXX Query Time Sample 
  2909.      REXX Semaphore Class Sample 
  2910.      REXX Stack Sample 
  2911.      REXX Start and Guard Sample 
  2912.  
  2913.  
  2914. ΓòÉΓòÉΓòÉ 7.3.11.1. CALLREXX Sample Program ΓòÉΓòÉΓòÉ
  2915.  
  2916. CALLREXX demonstrates how a C-language application calls a REXX application. To 
  2917. run the REXX application BACKWARD.FNC, CALLREXX.C issues RexxStart. RexxStart 
  2918. calls the REXX interpreter and passes it a parameter string. BACKWARD.FNC 
  2919. returns a result string to the C-language application. 
  2920.  
  2921.  
  2922. ΓòÉΓòÉΓòÉ 7.3.11.2. DEVINFO Sample Program ΓòÉΓòÉΓòÉ
  2923.  
  2924. DEVINFO issues DosDevConfig and returns the data in a collection of compound 
  2925. variables when all available items are requested or a single variable when only 
  2926. one item is requested. This is a REXX subcommand handler and variable pool 
  2927. example. This sample can be run in an OS/2 full-screen session, an OS/2 
  2928. text-window session, or in PMREXX. 
  2929.  
  2930.  
  2931. ΓòÉΓòÉΓòÉ 7.3.11.3. PMREXX Sample Program ΓòÉΓòÉΓòÉ
  2932.  
  2933. PMREXX provides a PM window in which you can display the output from a REXX 
  2934. procedure or from any programs called by the REXX procedure. The window has an 
  2935. entry field into which you can type. 
  2936.  
  2937.  
  2938. ΓòÉΓòÉΓòÉ 7.3.11.4. REXXCALC Sample Program ΓòÉΓòÉΓòÉ
  2939.  
  2940. REXXCALC illustrates the steps required to develop enhanced applications. 
  2941.  
  2942.  
  2943. ΓòÉΓòÉΓòÉ 7.3.11.5. REXXUTIL Sample Program ΓòÉΓòÉΓòÉ
  2944.  
  2945. REXXUTIL demonstrates a set of external functions packaged in a dynamic link 
  2946. library, including: 
  2947.  
  2948.      Use of OS/2 system functions in REXX external functions 
  2949.      Techniques for passing large amounts of data to a REXX program using REXX 
  2950.       compound variables as arrays. 
  2951.  
  2952.  REXXUTIL runs on 32-bit OS/2. It can be run in an OS/2 full-screen session, an 
  2953.  OS/2 window session, or in PMREXX. 
  2954.  
  2955.  
  2956. ΓòÉΓòÉΓòÉ 7.3.11.6. RXMACDLL Sample Program ΓòÉΓòÉΓòÉ
  2957.  
  2958. RXMACDLL demonstrates the macrospace interface with the two following 
  2959. C-language programs and that are compiled into two separate dynamic link 
  2960. libraries (DLLs): 
  2961.  
  2962.      MACRO.C 
  2963.  
  2964.       Contains REXX external functions, which perform REXX macrospace 
  2965.       operations. 
  2966.  
  2967.      RXNLSINF.C 
  2968.  
  2969.       Contains a REXX external function that provides information related to 
  2970.       national language support (for example, as a currency symbol and 
  2971.       separator). 
  2972.  
  2973.  RXMACDLL.CMD uses MACRO.DLL to load NLSMONEY.CMD into the macrospace and calls 
  2974.  NLSMONEY.CMD several times to format currency amounts. NLSMONEY.CMD formats 
  2975.  the amounts according to the specifications provided by RXNLSINF.DLL. 
  2976.  
  2977.  RXMACDLL can be run in an OS/2 full-screen session, an OS/2 window session, or 
  2978.  in PMREXX. 
  2979.  
  2980.  
  2981. ΓòÉΓòÉΓòÉ 7.3.11.7. REXX Animal SOM Class Sample ΓòÉΓòÉΓòÉ
  2982.  
  2983. The sample code in the \TOOLKIT\SAMPLES\REXX\SOM\ANIMAL directory illustrates 
  2984. the use of a simple metaclass to provide customized constructors and to perform 
  2985. basic instance tracking. 
  2986.  
  2987. For this sample to function properly, Object REXX must be installed. 
  2988.  
  2989.  
  2990. ΓòÉΓòÉΓòÉ 7.3.11.8. REXX Workplace Shell Class Sample ΓòÉΓòÉΓòÉ
  2991.  
  2992. The WPSORXCL.CMD sample in the \TOOLKIT\SAMPLES\REXX\WPS directory demonstrates 
  2993. how to use the OS/2 Workplace Shell folders to represent Object REXX classes. 
  2994. This is presented in a tree view where an Object REXX class is a folder and 
  2995. subclasses are subfolders. The top folder title is updated as classes are added 
  2996. for a progress indicator.  Methods in a class can be represented as abstract 
  2997. WPS objects; but the default is not to create them because it is quite time 
  2998. consuming. 
  2999.  
  3000. For this sample to function properly, Object REXX must be installed. 
  3001.  
  3002. The REXX Workplace Shell samples also require the REXX classes first be 
  3003. registered with the Workplace Shell. To register REXX classes with the 
  3004. Workplace Shell, type the following at an OS/2 command prompt: 
  3005.  
  3006.      WPSINST
  3007.  
  3008. The WPSINST.CMD program can be used at any time to query REXX classes and to 
  3009. register and deregister them. To deregister the REXX classes, type the 
  3010. following at an OS/2 command prompt: 
  3011.  
  3012.      WPSINST -
  3013.  
  3014.  
  3015. ΓòÉΓòÉΓòÉ 7.3.11.9. REXX Workplace Shell Folder Sample ΓòÉΓòÉΓòÉ
  3016.  
  3017. The WPSORXFL.CMD sample in the \TOOLKIT\SAMPLES\REXX\WPS directory demonstrates 
  3018. useful routines for folders.  The first routine will take a WPS folder as input 
  3019. and return an array of SOM objects; one for each object in that folder.  The 
  3020. second routine will take an array of WPS objects and a string; returning an 
  3021. array of objects that match the string.  The sample also uses three methods to 
  3022. iterate over arrays as iteration examples. 
  3023.  
  3024. For this sample to function properly, Object REXX must be installed. 
  3025.  
  3026. The REXX Workplace Shell samples also require the REXX classes first be 
  3027. registered with the Workplace Shell. To register REXX classes with the 
  3028. Workplace Shell, type the following at an OS/2 command prompt: 
  3029.  
  3030.      WPSINST
  3031.  
  3032. The WPSINST.CMD program can be used at any time to query REXX classes and to 
  3033. register and deregister them. To deregister the REXX classes, type the 
  3034. following at an OS/2 command prompt: 
  3035.  
  3036.      WPSINST -
  3037.  
  3038.  
  3039. ΓòÉΓòÉΓòÉ 7.3.11.10. REXX Complex Number Sample ΓòÉΓòÉΓòÉ
  3040.  
  3041. The COMPLEX.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how 
  3042. to create a complex number class using the ::class and ::method directives. 
  3043. Also shown is an example of subclassing the complex number class (the vector 
  3044. subclass).  Finally, the stringlike class demonstrates the use of a mixin to 
  3045. provide some string behavior to the complex number class. 
  3046.  
  3047. The USECOMP.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the 
  3048. use of the ::requires directive to use the complex number class defined in 
  3049. COMPLEX.CMD. 
  3050.  
  3051. For this sample to function properly, Object REXX must be installed. 
  3052.  
  3053.  
  3054. ΓòÉΓòÉΓòÉ 7.3.11.11. REXX Concurrency Sample ΓòÉΓòÉΓòÉ
  3055.  
  3056. The CCREPLY.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how 
  3057. to use reply to run two methods at the same time. 
  3058.  
  3059. For this sample to function properly, Object REXX must be installed. 
  3060.  
  3061.  
  3062. ΓòÉΓòÉΓòÉ 7.3.11.12. REXX Directives Sample ΓòÉΓòÉΓòÉ
  3063.  
  3064. The GUESS.CMD sample in the \TOOLKIT\SAMPLES\REXX directory creates a simple 
  3065. node class and uses it to create a logic tree.  The logic tree is filled in by 
  3066. playing a simple guessing game. 
  3067.  
  3068. For this sample to function properly, Object REXX must be installed. 
  3069.  
  3070.  
  3071. ΓòÉΓòÉΓòÉ 7.3.11.13. REXX Display Month Array Sample ΓòÉΓòÉΓòÉ
  3072.  
  3073. The MONTH.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the 
  3074. use of arrays to replace stems.  This sample displays the days of the month. 
  3075.  
  3076. For this sample to function properly, Object REXX must be installed. 
  3077.  
  3078.  
  3079. ΓòÉΓòÉΓòÉ 7.3.11.14. REXX Factorial Sample ΓòÉΓòÉΓòÉ
  3080.  
  3081. The FACTOR.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates a way 
  3082. to define a factorial class using the subclass method and the .methods 
  3083. environment symbol. 
  3084.  
  3085. For this sample to function properly, Object REXX must be installed. 
  3086.  
  3087.  
  3088. ΓòÉΓòÉΓòÉ 7.3.11.15. REXX Guard and Reply Sample ΓòÉΓòÉΓòÉ
  3089.  
  3090. The GREPLY.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the 
  3091. difference between Guarded and UnGuarded methods.  In the first example, the 
  3092. method is guarded, so it does not begin execution until the final result is 
  3093. tallied.  In the second example, the method is unguarded so it can begin 
  3094. execution while method sum_up is still looping.  In fact, unguarded_get often 
  3095. runs immediately after the Reply, so using a guard instruction ensures sum_up 
  3096. runs for a bit before unguarded_get returns with the intermediate sum. 
  3097.  
  3098. For this sample to function properly, Object REXX must be installed. 
  3099.  
  3100.  
  3101. ΓòÉΓòÉΓòÉ 7.3.11.16. REXX Pipe Sample ΓòÉΓòÉΓòÉ
  3102.  
  3103. The PIPE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the use 
  3104. of the ::class and ::method directives to create a simple implementation of a 
  3105. CMS-like pipeline function. 
  3106.  
  3107. The USEPIPE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how 
  3108. to use the pipes implemented in the PIPE.CMD sample. 
  3109.  
  3110. For this sample to function properly, Object REXX must be installed. 
  3111.  
  3112.  
  3113. ΓòÉΓòÉΓòÉ 7.3.11.17. REXX Query Date Sample ΓòÉΓòÉΓòÉ
  3114.  
  3115. The QDATE.CMD sample in the \TOOLKIT\SAMPLES\REXX directory displays the 
  3116. current date and moon phase for that date in English. 
  3117.  
  3118.  
  3119. ΓòÉΓòÉΓòÉ 7.3.11.18. REXX Query Time Sample ΓòÉΓòÉΓòÉ
  3120.  
  3121. The QTIME.CMD sample in the \TOOLKIT\SAMPLES\REXX directory displays the 
  3122. current time in English. 
  3123.  
  3124.  
  3125. ΓòÉΓòÉΓòÉ 7.3.11.19. REXX Semaphore Class Sample ΓòÉΓòÉΓòÉ
  3126.  
  3127. The SEMCLS.CMD sample in the \TOOLKIT\SAMPLES\REXX directory implements a 
  3128. semaphore class in Object REXX.  The class is defined to the Global OREXX 
  3129. environment. 
  3130.  
  3131. For this sample to function properly, Object REXX must be installed. 
  3132.  
  3133.  
  3134. ΓòÉΓòÉΓòÉ 7.3.11.20. REXX Stack Sample ΓòÉΓòÉΓòÉ
  3135.  
  3136. The STACK.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates how to 
  3137. implement a stack class using the ::class and 
  3138. ::method directives.  This sample also includes a short example of the use of a 
  3139. stack. 
  3140.  
  3141. For this sample to function properly, Object REXX must be installed. 
  3142.  
  3143.  
  3144. ΓòÉΓòÉΓòÉ 7.3.11.21. REXX Start and Guard Sample ΓòÉΓòÉΓòÉ
  3145.  
  3146. The KTGUARD.CMD sample in the \TOOLKIT\SAMPLES\REXX directory demonstrates the 
  3147. use of the start method and the guard instruction to control execution of 
  3148. several programs.  In this sample, the programs are controlled by one "guarded" 
  3149. variable. 
  3150.  
  3151. For this sample to function properly, Object REXX must be installed. 
  3152.  
  3153.  
  3154. ΓòÉΓòÉΓòÉ 7.3.12. SOM Sample Programs ΓòÉΓòÉΓòÉ
  3155.  
  3156. Note:  The ANIMALS and TP (text processing) sample programs are not included in 
  3157.        the OS/2 Warp Toolkit. Refer to the SOMobjects Developer Toolkit for 
  3158.        accessing them and obtaining information on them. 
  3159.  
  3160.  
  3161. ΓòÉΓòÉΓòÉ 7.3.13. TCP/IP Sample Programs ΓòÉΓòÉΓòÉ
  3162.  
  3163. The TCP/IP sample programs are categorized as follows: 
  3164.  
  3165.      ACCXRECV (accept_and_recv function) 
  3166.      ECHOSAMP 
  3167.      HPS 
  3168.      OS2IOCTL 
  3169.      R0LIB32 
  3170.      RCOPY 
  3171.      RPC 
  3172.      RPCGEN 
  3173.      SAMPDLL 
  3174.      SENDFILE 
  3175.      SOCKET 
  3176.      SYSCTL 
  3177.  
  3178.  
  3179. ΓòÉΓòÉΓòÉ 7.3.13.1. ACCXRECV Sample Program ΓòÉΓòÉΓòÉ
  3180.  
  3181. The accept_and_recv function call is explained in this sample program.  The 
  3182. server opens a socket to which it binds and then does a listen on that socket. 
  3183. It starts the number of specified threads and does accept_and_recv on each of 
  3184. them.  The client opens a socket, connects to the server and sends the data. As 
  3185. the timeout option is set (by using setsockeopt), whenever the client connects 
  3186. but doesn't send any data, the server times out. 
  3187.  
  3188.  
  3189. ΓòÉΓòÉΓòÉ 7.3.13.2. ECHOSAMP Sample Program ΓòÉΓòÉΓòÉ
  3190.  
  3191. This is a client/server application that is implemented using the Echo 
  3192. protocol.  Whatever the echo client sends to the server, the server sends it 
  3193. back to the client. 
  3194.  
  3195.  
  3196. ΓòÉΓòÉΓòÉ 7.3.13.3. HPS Sample Program ΓòÉΓòÉΓòÉ
  3197.  
  3198. This is a client/server application that is implemented for exploiting High 
  3199. Performance Send.  The server opens a socket to which the client connects and 
  3200. passes data using HPS.  The server responds to the client using HPS. 
  3201.  
  3202.  
  3203. ΓòÉΓòÉΓòÉ 7.3.13.4. OS2IOCTL Sample Program ΓòÉΓòÉΓòÉ
  3204.  
  3205. This sample program issues SIOSTATRT for getting the routing entries from the 
  3206. routing table, which is displayed on the screen, and issues SIOCSSYN to set the 
  3207. SYN attack prevention frunction flag to on. 
  3208.  
  3209.  
  3210. ΓòÉΓòÉΓòÉ 7.3.13.5. R0LIB32 Sample Program ΓòÉΓòÉΓòÉ
  3211.  
  3212. The client sends 1k of data (all 'a'). Then, the server modifies the data 
  3213. (changes all 'a' to 'b') and sends the modified data to the client. The client 
  3214. prints the data received from the server. The client sends a string to the 
  3215. client using sendmsg() call, and the server receives it (by recvmsg() call) and 
  3216. sends another string to the client. The client receives the string and prints 
  3217. it. The client program is a ring3 program.  The server program accesses the 
  3218. socket calls through r0lib32. 
  3219.  
  3220.  
  3221. ΓòÉΓòÉΓòÉ 7.3.13.6. RCOPY Sample Program ΓòÉΓòÉΓòÉ
  3222.  
  3223. RCOPY is located in \TOOLKIT\SAMPLES\TCPIPTK\RCOPY).  It makes use of the FTP 
  3224. API, FTPAPI.DLL, to transfer a directory and all of its subdirectories between 
  3225. a client and FTP server.  RCOPY does not read the user ID or password from the 
  3226. NETRC file, so they must be specified when required. 
  3227.  
  3228. The following explains how to build and run the RCOPY samples. 
  3229.  
  3230.    1. To compile and link the sample, type: 
  3231.  
  3232.             nmake -f vacpp.mak   (to build using the VisualAge C/C++ compiler)
  3233.  
  3234.    2. To run rcopy.exe: 
  3235.  
  3236.           Command syntax: 
  3237.  
  3238.                       RCOPY put|get ascii|binary [-l<local path>] -h<host>
  3239.                             -u<userid> -p<password> [-r<rem path>] [-a<account>]
  3240.  
  3241.            where: 
  3242.  
  3243.            put            Transfers from local host to remote host (default) 
  3244.  
  3245.            get            Transfers from remote host to local host 
  3246.  
  3247.            binary         Binary transfer mode (default) 
  3248.  
  3249.            ASCII          ASCII transfer mode 
  3250.  
  3251.           Example: 
  3252.  
  3253.                       rcopy put -ld:\tmp -holeg -uyozzo -pyozzops -rc:\newtmp
  3254.  
  3255.            where: 
  3256.  
  3257.            d:\tmp         Is a local path to transfer 
  3258.  
  3259.            oleg           Is a remote host (FTP server) 
  3260.  
  3261.            yozzo          Is a remote user ID 
  3262.  
  3263.            yozzops        Is a remote password 
  3264.  
  3265.  
  3266. ΓòÉΓòÉΓòÉ 7.3.13.7. RPC Sample Programs ΓòÉΓòÉΓòÉ
  3267.  
  3268. RPC consists of three C programs located in \TOOLKIT\SAMPLES\TCPIPTK\RPC: 
  3269.  
  3270.      RAWEX.C provides an example of the RAW client/server usage.  Portmapper 
  3271.       must be running. 
  3272.  
  3273.      GENESEND.C sends an integer to the remote host (GENESEND) and receives 
  3274.       the integer back at the local host.  Portmapper and Remote server 
  3275.       (GENESEND) must be running. 
  3276.  
  3277.      GENESERV.C is a generic server.  It receives an integer or float and 
  3278.       returns them, respectively.  Portmapper must be running. 
  3279.  
  3280.  The following explains how to build and run the RPC samples. 
  3281.  
  3282.    1. To compile and link the sample program, type: 
  3283.  
  3284.             nmake  -f rpcsamp.mak
  3285.  
  3286.    2. To start Portmapper, type: 
  3287.  
  3288.             start portmap
  3289.  
  3290.    3. To start the geneserv.exe server, type: 
  3291.  
  3292.             start geneserv
  3293.  
  3294.    4. To run genesend.exe, type: 
  3295.  
  3296.             genesend hostname integer
  3297.  
  3298.       For example: 
  3299.  
  3300.             genesend charm 1000
  3301.  
  3302.    5. To run rawex.exe, type: 
  3303.  
  3304.             rawex integer
  3305.  
  3306.       For example: 
  3307.  
  3308.             rawex 1000
  3309.  
  3310.  
  3311. ΓòÉΓòÉΓòÉ 7.3.13.8. RPCGEN Sample Programs ΓòÉΓòÉΓòÉ
  3312.  
  3313. RPCGEN consists of three user-written files located in 
  3314. \TOOLKIT\SAMPLES\TCPIPTK\RPCGEN): 
  3315.  
  3316.      RG.X defines the remote procedure characteristics 
  3317.  
  3318.      RGUS.C demonstrates an RPC server program 
  3319.  
  3320.      RGUC.C demonstrates an RPC client program 
  3321.  
  3322.  The following explains how to build and run the RPCGEN samples. 
  3323.  
  3324.    1. Perform the following: 
  3325.  
  3326.             rpcgen rg.x
  3327.  
  3328.       This generates rg.h, rg.i, rgs.c, rgc.c, and rgx.c. 
  3329.  
  3330.    2. From rgx.c, add the include headers to rgus.c and rguc.c if they do not 
  3331.       already exist 
  3332.  
  3333.    3. Run rpcgsamp.cmd to compile rgus.c, rguc.c, rgs.c, and rgc.c 
  3334.  
  3335.       Link rgs.obj and rgus.obj to generate rgs.exe 
  3336.  
  3337.       Link rgc.obj and rguc.obj to generate rgc.exe 
  3338.  
  3339.    4. Start portmap.exe and rgs.exe on the same machine: 
  3340.  
  3341.             start portmap
  3342.             start rgs
  3343.  
  3344.    5. Start rgc.exe by typing: 
  3345.  
  3346.             rgc hostname "user_input string"
  3347.  
  3348.  
  3349. ΓòÉΓòÉΓòÉ 7.3.13.9. SAMPDLL Sample Programs ΓòÉΓòÉΓòÉ
  3350.  
  3351. SAMPDLL (located in \TOOLKIT\SAMPLES\TCPIPTK\SAMPDLL) demonstrates the use of a 
  3352. DLL. 
  3353.  
  3354. MYPROG (located in \TOOLKIT\SAMPLES\TCPIPTK\SAMPDLL) demonstrates building a 
  3355. DLL. 
  3356.  
  3357.  
  3358. ΓòÉΓòÉΓòÉ 7.3.13.10. SENDFILE Sample Program ΓòÉΓòÉΓòÉ
  3359.  
  3360. This is a TCP client/server application that is used for explaining the 
  3361. send_file ().  The client sends a file to a server. 
  3362.  
  3363.  
  3364. ΓòÉΓòÉΓòÉ 7.3.13.11. SOCKET Sample Programs ΓòÉΓòÉΓòÉ
  3365.  
  3366. SOCKET consists of three client/server samples and SELECTS.C located in 
  3367. \TOOLKIT\SAMPLES\TCPIPTK\SOCKET. 
  3368.  
  3369. SELECTS.C is a simple TCP and UDP server that uses the BSD select() call. 
  3370. MSGC.C/MSGS.C, TCPC.C/TCPS.C, and UDPC.C/UDPS.C are sample C socket 
  3371. client/server programs demonstrating network programming with OS/2 sockets. 
  3372.  
  3373. The following explains how to build and run the SOCKET samples. 
  3374.  
  3375.    1. To compile and link the sample programs, type: 
  3376.  
  3377.             nmake -f vacpp.mak  (to build using the VisualAge C/C++ compiler)
  3378.  
  3379.    2. Running udps.exe and udpc.exe: 
  3380.  
  3381.         a. To start the udps server, type: 
  3382.  
  3383.                       start udps
  3384.  
  3385.            An additional session is created and the following message is 
  3386.            displayed: 
  3387.  
  3388.                 Port assigned is 1028 
  3389.  
  3390.         b. To run the udpc client, type: 
  3391.  
  3392.                       udpc 9.67.60.10 1028
  3393.  
  3394.            where: 
  3395.  
  3396.            9.67.60.10       Is the IP address of the machine where the udps 
  3397.                             server is running 
  3398.  
  3399.            1028             Is the port assigned by the udps server 
  3400.  
  3401.            After running the udpc client, you will see the following output on 
  3402.            the server session: 
  3403.  
  3404.                       Received message Hello ................
  3405.  
  3406.    3. Running tcps.exe and tcpc.exe 
  3407.  
  3408.         a. To start the tcps server, type: 
  3409.  
  3410.                       start tcps 2000
  3411.  
  3412.            where 2000 is the port number assigned to the tcps server. 
  3413.  
  3414.         b. To run the tcpc client, type: 
  3415.  
  3416.                       tcpc charm 2000
  3417.  
  3418.            where: 
  3419.  
  3420.            charm          Is the hostname of the machine where the tcps server 
  3421.                           is running 
  3422.  
  3423.            2000           Is the port assigned to the tcps server 
  3424.  
  3425.    4. Running selects.exe 
  3426.  
  3427.       The selects server has the same function as the tcps and udps servers. 
  3428.  
  3429.         a. To start the selects server, type: 
  3430.  
  3431.                       start selects 2000
  3432.  
  3433.            where 2000 is the port number assigned to the selects server. 
  3434.  
  3435.         b. To run the tcpc client, type: 
  3436.  
  3437.                       tcpc charm 2000
  3438.  
  3439.            where: 
  3440.  
  3441.            charm          Is the hostname of the machine where the selects 
  3442.                           server is running 
  3443.  
  3444.            2000           Is the port assigned to the selects server 
  3445.  
  3446.         c. To run the udpc client, type: 
  3447.  
  3448.                       udpc 9.67.60.10 2000
  3449.  
  3450.            where: 
  3451.  
  3452.            9.67.60.10       Is the IP address of the machine where the selects 
  3453.                             server is running 
  3454.  
  3455.            2000             Is the port assigned by the selects server 
  3456.  
  3457.       After running the udpc client, you will see the following output on the 
  3458.       server session: 
  3459.  
  3460.             Received message Hello ................
  3461.  
  3462.    5. Running msgs.exe and msgc.exe 
  3463.  
  3464.       msgs.c and msgc.c are the same program as udps.c and udpc.c, except they 
  3465.       are written using recvmsg() and sendmsg() calls. 
  3466.  
  3467.         a. To start the msgs server, type: 
  3468.  
  3469.                       start msgs
  3470.  
  3471.            An additional session is created and the following message appears: 
  3472.  
  3473.                       Port assigned is 1028
  3474.  
  3475.         b. To run the msgc client, type: 
  3476.  
  3477.                       msgc 9.67.60.10 1028
  3478.  
  3479.            where: 
  3480.  
  3481.            9.67.60.10     Is the IP address of the machine where the msgs 
  3482.                           server is running 
  3483.  
  3484.            1028           Is the port assigned by the msgs server 
  3485.  
  3486.  
  3487. ΓòÉΓòÉΓòÉ 7.3.13.12. SYSCTL Sample Program ΓòÉΓòÉΓòÉ
  3488.  
  3489. The sysctl() call accesses and modifies system-wide parameter values for the 
  3490. entire TCP/IP stack.  This sample program sets the ipgate to 1 and then back to 
  3491. 0. 
  3492.  
  3493.  
  3494. ΓòÉΓòÉΓòÉ 7.3.14. Workplace Shell Sample Programs ΓòÉΓòÉΓòÉ
  3495.  
  3496. The Workplace Shell sample programs are as follows: 
  3497.  
  3498.      BROWSE 
  3499.      CAR 
  3500.      CARPP 
  3501.      TEXTFLDR 
  3502.      WPSTUTOR 
  3503.      WSFILE 
  3504.  
  3505.  Note:  All Workplace Shell samples require SOM 2.1 in order to execute 
  3506.         properly. 
  3507.  
  3508.  
  3509. ΓòÉΓòÉΓòÉ 7.3.14.1. BROWSE Sample Program ΓòÉΓòÉΓòÉ
  3510.  
  3511. BROWSE displays file system objects in a PM window in either text or 
  3512. hexidecimal format.  Hexidecimal is the default format. To view a file, you can 
  3513. either drop a file system object on the Workplace Shell ASCII/Hex File Browser 
  3514. or double-click on the Workplace Shell ASCII/Hex File Browser and enter the 
  3515. name of a file to view. 
  3516.  
  3517. To choose the format for viewing an object, click on the Workplace Shell 
  3518. ASCII/Hex File Browser and select Open Text View or Open Hex View from the Open 
  3519. menu. 
  3520.  
  3521. The default view format can be changed in the Settings notebook of the 
  3522. Workplace Shell ASCII/Hex File Browser by doing the following: 
  3523.  
  3524.    1. Select the Menu tab. 
  3525.  
  3526.    2. Select ~Open from the Available menus: list box. 
  3527.  
  3528.    3. Select Settings. 
  3529.  
  3530.    4. Select Open ~Hex View or Open ~Text View from the Default action list 
  3531.       box. 
  3532.  
  3533.    5. Select OK. 
  3534.  
  3535.  
  3536. ΓòÉΓòÉΓòÉ 7.3.14.2. CAR Sample Program ΓòÉΓòÉΓòÉ
  3537.  
  3538. CAR demonstrates how to create a Workplace Shell object using basic 
  3539. object-oriented programming techniques and the SOM, including: 
  3540.  
  3541.      Initializing an object 
  3542.      Adding settings pages to an object 
  3543.      Saving and restoring the state of an object 
  3544.      Modifying an object's context menus (adding and deleting menu items) 
  3545.      Querying object class data 
  3546.      Processing context menu items 
  3547.      Implementing settings page dialog processing 
  3548.      Handling exceptions 
  3549.  
  3550.  
  3551. ΓòÉΓòÉΓòÉ 7.3.14.3. CARPP Sample Program ΓòÉΓòÉΓòÉ
  3552.  
  3553. CARPP is a C++ version of the CAR sample program. CARPP demonstrates how to 
  3554. create a Workplace Shell object using basic object-oriented programming 
  3555. techniques and the SOM, including: 
  3556.  
  3557.      Initializing an object 
  3558.      Adding settings pages to an object 
  3559.      Saving and restoring the state of an object 
  3560.      Modifying an object's context menus (adding and deleting menu items) 
  3561.      Querying object class data 
  3562.      Processing context menu items 
  3563.      Implementing settings page dialog processing 
  3564.      Handling exceptions 
  3565.  
  3566.  
  3567. ΓòÉΓòÉΓòÉ 7.3.14.4. TEXTFLDR Sample Program ΓòÉΓòÉΓòÉ
  3568.  
  3569. TEXTFLDR allows only plain text objects to be placed into the folder. Objects 
  3570. that are not plain text, that is, control- or extended-ASCII characters, are 
  3571. rejected. Objects are considered to be plain text if the "Associated type" 
  3572. field of the Settings notebook is set to plain text. If there is no associated 
  3573. type set, the first 500 bytes are placed into the folder. 
  3574.  
  3575.  
  3576. ΓòÉΓòÉΓòÉ 7.3.14.5. WPSTUTOR Sample Program ΓòÉΓòÉΓòÉ
  3577.  
  3578. WPSTUTOR displays the order in which object methods are invoked by the 
  3579. Workplace Shell. When a sample object's class method is executed, the method's 
  3580. name and a description of its function are displayed in a PM window. The sample 
  3581. saves the object's title and its icon title backwards. 
  3582.  
  3583. This object class subclasses the WPDataFile class. Most Workplace Shell 
  3584. instance and class methods are overridden so that information about the methods 
  3585. can be displayed to the user. 
  3586.  
  3587. This sample is designed to be more of a tutorial for Workplace Shell 
  3588. programming than a programming example. 
  3589.  
  3590. Note:  The SHOWDESC.EXE file should be renamed to SHOWDESC.BAK (or something 
  3591.        else) to turn off the sample. Rename the file back to SHOWDESC.EXE to 
  3592.        turn the sample back on. 
  3593.  
  3594.  
  3595. ΓòÉΓòÉΓòÉ 7.3.14.6. WSFILE Sample Program ΓòÉΓòÉΓòÉ
  3596.  
  3597. WSFILE displays, creates, and installs Workplace objects of two classes: WSFILE 
  3598. and WSFOLDER. The WSFILE class is a subclass of the WPDataFile class, and the 
  3599. WSFOLDER class is a subclass of the WPFolder class. 
  3600.  
  3601.  
  3602. ΓòÉΓòÉΓòÉ 7.4. Tools ΓòÉΓòÉΓòÉ
  3603.  
  3604. This section provides a brief description of each tool with just enough detail 
  3605. to get you started at the OS/2 command line. 
  3606.  
  3607. The tools are categorized as follows: 
  3608.  
  3609.      Development Tools 
  3610.      Multimedia 
  3611.      Presentation Manager (PM) 
  3612.      SOM 
  3613.      TCP/IP 
  3614.      Workplace Shell 
  3615.      XPG4 
  3616.  
  3617.  For complete information about the tools described here, please refer to the 
  3618.  online Tools Reference. 
  3619.  
  3620.  Note:  The Wave Doctor, previously available with the OS/2 Multimedia Toolkit 
  3621.         product, is not included in the OS/2 Warp Toolkit. 
  3622.  
  3623.  
  3624. ΓòÉΓòÉΓòÉ 7.4.1. Development Tools ΓòÉΓòÉΓòÉ
  3625.  
  3626. The Developer tools help you develop OS/2 programs. It is not likely that you 
  3627. will use the tools described in this section as much as the compiler and 
  3628. linker. Nonetheless, these tools are handy to have. Perhaps you will use only a 
  3629. few of them in your programming career, but it is important to know where you 
  3630. can find information about them, in the event you will ever need them. The 
  3631. tools included in this section are: 
  3632.  
  3633.      ALP - Assembly Language Processor 
  3634.      EXEHDR - Executable-Header Files 
  3635.      FWDSTAMP - Forwarders 
  3636.      IMPLIB - Import a Library 
  3637.      KwikINF - Quick Information 
  3638.      LINK386 
  3639.      MARKEXE 
  3640.      MASM2ALP - MASM Compatible Command Line Interface to ALP 
  3641.      MKMSGF - Make Message File 
  3642.      MKTMPF - Make Template File 
  3643.      MSGBIND - Message Binding 
  3644.      NMAKE 
  3645.      PACK and UNPACK 
  3646.      PACK2 and UNPACK2 
  3647.      TRCUST - Trace Customizer 
  3648.  
  3649.  
  3650. ΓòÉΓòÉΓòÉ 7.4.1.1. ALP ΓòÉΓòÉΓòÉ
  3651.  
  3652. The Assembly Language Processor (ALP) is a macro assembler that runs under the 
  3653. 32-bit OS/2 operating system. ALP is designed as a functional replacement for 
  3654. the Microsoft Macro Assembler (MASM). It accepts the full syntax of the MASM 
  3655. 5.10 assembly language, which is a subset of the MASM 6.00 high-level directive 
  3656. language.  It also understands the complete Intel 80X86 instruction set, 
  3657. including the MMX extensions. ALP creates standard Object Module Format (.OMF) 
  3658. files that can be linked to produce DOS or OS/2 executables and can generate 
  3659. line number debug information compatible with IBM's Presentation Manager 
  3660. Debugger. In addition, this tool offers a rich set of command-line options, as 
  3661. well as a comprehensive listing file with user-tailored formatting, allowing a 
  3662. visual perspective not possible with other assemblers. 
  3663.  
  3664. ALP translates assembly language source files (typically having a file-name 
  3665. extension of .ASM) into object (.OBJ) files. The LINK386 utility can then be 
  3666. used to combine multiple object files into a single executable file, dynamic 
  3667. link library, or device driver. 
  3668.  
  3669. While ALP is designed as a functional replacement for the Microsoft MASM 
  3670. assembler in terms of source code compatibility, it does not use the MASM 
  3671. command-line syntax. ALP uses a free-form syntax, has a comprehensive set of 
  3672. options, and allows assembly of multiple input files with a single command-line 
  3673. invocation. 
  3674.  
  3675. For each corresponding input source file, ALP can produce the following types 
  3676. of output files: 
  3677.  
  3678.      Object (.OBJ) files, which contain program data and executable code. 
  3679.      Listing (.LST) files, which document the results of the assembly. 
  3680.      Message (.MSG) files, which can contain all error, warning, and 
  3681.       informational messages produced during the assembly. 
  3682.  
  3683.  See the ALP Programming Guide and Reference for more information on ALP. 
  3684.  Online help is also available from the command line for all ALP options. 
  3685.  
  3686.  
  3687. ΓòÉΓòÉΓòÉ 7.4.1.2. EXEHDR ΓòÉΓòÉΓòÉ
  3688.  
  3689. EXEHDR provides a listing of the contents of the header of an executable file. 
  3690. It also provides a listing of the attributes of all segments in the file. 
  3691.  
  3692. Uses of EXEHDR include: 
  3693.  
  3694.      Determining whether a file is an application or a dynamic link library 
  3695.      Modifying and viewing the attributes set by the module definition file 
  3696.      Viewing the number and size of code and data segments. 
  3697.  
  3698.  
  3699. ΓòÉΓòÉΓòÉ 7.4.1.3. FWDSTAMP ΓòÉΓòÉΓòÉ
  3700.  
  3701. FWDSTAMP adds entry points, called forwarders, to a dynamic link library (.DLL) 
  3702. file. Forwarders point to API functions or other exported code or data. They 
  3703. contain an import reference so that the final target address of the forwarded 
  3704. entry is contained in a different module. A forwarder might be called an 
  3705. imported export. 
  3706.  
  3707. When a file has a fix-up to a forwarded entry point, the loader resolves that 
  3708. fix-up to the address of the entry point that the forwarder imports by 
  3709. traversing the chain of forwarders until the end of the chain (a non-forwarded 
  3710. export) is reached. All forwarders are implicitly exported. 
  3711.  
  3712. The imported entry point that a forwarder refers to may itself be another 
  3713. forwarder. The loader will process a chain of forwarders until a non-forwarder 
  3714. entry point is encountered. 
  3715.  
  3716. There is no run-time cost to forwarders; however, there is a slight load-time 
  3717. cost as the loader resolves forwarder chains with their final addresses. 
  3718.  
  3719.  
  3720. ΓòÉΓòÉΓòÉ 7.4.1.3.1. Using FWDSTAMP ΓòÉΓòÉΓòÉ
  3721.  
  3722. You use forwarders to combine several DLLs into one without having to relink 
  3723. old applications. For example, if MOUCALLS and VIOCALLS were combined into a 
  3724. single DLL called NEWLIB.DLL, then MOUCALLS and VIOCALLS could be replaced with 
  3725. special DLLs containing forwarders to NEWLIB.DLL. 
  3726.  
  3727.  
  3728. ΓòÉΓòÉΓòÉ 7.4.1.4. IMPLIB ΓòÉΓòÉΓòÉ
  3729.  
  3730. IMPLIB is used to generate an import library (.LIB) file. IMPLIB takes a module 
  3731. definition file (.DEF) as input. For each export definition in the .DEF file, 
  3732. IMPLIB generates a corresponding import definition. 
  3733.  
  3734. The .LIB file generated by IMPLIB is used as input to LINK386, which creates an 
  3735. executable (.EXE) file. The .LIB file provides LINK386 with information about 
  3736. imported dynamic link functions. 
  3737.  
  3738.  
  3739. ΓòÉΓòÉΓòÉ 7.4.1.4.1. Creating an IMPLIB ΓòÉΓòÉΓòÉ
  3740.  
  3741. Import libraries are created by IMPLIB and are used to link DLLs with 
  3742. applications. 
  3743.  
  3744. Import libraries are somewhat similar to standard libraries: 
  3745.  
  3746.      You specify import libraries and standard libraries in the same 
  3747.       command-line field of LINK386. 
  3748.  
  3749.      Both types of libraries resolve external references at link time. 
  3750.  
  3751.  However, import libraries differ from standard libraries in that they contain 
  3752.  no executable code. Rather, they identify the DLLs where the executable code 
  3753.  can be found at run time. 
  3754.  
  3755.  Creating import libraries is an extra step. Nevertheless, import libraries are 
  3756.  recommended for use with all DLLs for two reasons: 
  3757.  
  3758.      IMPLIB automates much of the program creation process for you. To use 
  3759.       IMPLIB, you need to supply the .DEF file you already created for the 
  3760.       dynamic link library. Without an import library, you must create a second 
  3761.       .DEF file that explicitly defines all needed functions in the dynamic 
  3762.       link library. 
  3763.  
  3764.      Import libraries make it easier for one person to write a library and 
  3765.       another to write the application. Much of the linking process (linking 
  3766.       the .DLL file and creating the import library) can be done by the author 
  3767.       of the dynamic link library. The import library and associated .DLL file 
  3768.       can then be given as a unit to the person linking the application--that 
  3769.       person need not worry about creating a .DEF file. 
  3770.  
  3771.  
  3772. ΓòÉΓòÉΓòÉ 7.4.1.5. KwikINF ΓòÉΓòÉΓòÉ
  3773.  
  3774. KwikINF provides you with a quick and convenient method of accessing 
  3775. information in online documents stored in the OS/2 BOOKSHELF from anywhere on 
  3776. the Desktop, with the exception of DOS or WIN-OS/2 sessions. When KwikINF is 
  3777. started, you can search for a text string of your choice directly or through a 
  3778. pop-up window by pressing a user-selectable hot key. Until you configure 
  3779. KwikINF, your KwikINF hot key is Alt+Q. 
  3780.  
  3781. How you initiate a search for information in online documents depends on where 
  3782. you are on the Desktop when you press the KwikINF hot key: 
  3783.  
  3784.      From an OS/2 full-screen session, a PM VIO or AVIO window, or PM MLE: 
  3785.  
  3786.       Position the cursor on the string you want to search for and press the 
  3787.       KwikINF hot key. KwikINF retrieves the word at the cursor. If you have 
  3788.       configured KwikINF to display the KwikINF window when the KwikINF hot key 
  3789.       is pressed, KwikINF will automatically place the retrieved word in the 
  3790.       Search string entry field of the KwikINF window. When you select Search 
  3791.       or press Enter, KwikINF displays the information. If you have configured 
  3792.       KwikINF to bypass the KwikINF window when the KwikINF hot key is pressed, 
  3793.       KwikINF automatically displays the information. 
  3794.  
  3795.      From a graphic-text PM window: 
  3796.  
  3797.       Press the KwikINF hot key, and then type the string you want to search 
  3798.       for in the Search string entry field of the KwikINF window. The KwikINF 
  3799.       text-retrieval feature is not available from graphic-text PM windows. 
  3800.  
  3801.  
  3802. ΓòÉΓòÉΓòÉ 7.4.1.6. LINK386 ΓòÉΓòÉΓòÉ
  3803.  
  3804. LINK386 is used to combine object files and standard library files into a 
  3805. single executable file. LINK386 also generates DLLs and device drivers. 
  3806.  
  3807. LINK386 uses the following files as input: 
  3808.  
  3809.      One or more object files that are linked with any optional library files 
  3810.       to create the executable file.  Object files usually have a .OBJ 
  3811.       extension. 
  3812.  
  3813.      One or more library files. The library files contain object modules that 
  3814.       are linked with the object files to create the executable file. Library 
  3815.       files usually have a .LIB extension. 
  3816.  
  3817.      A module definition file. The module definition file provides information 
  3818.       to LINK386 about the executable file or dynamic link library file it is 
  3819.       creating. The module definition file usually has a .DEF extension. 
  3820.  
  3821.  LINK386 produces three types of output files: 
  3822.  
  3823.      An executable file.  This executable file runs under OS/2 whenever you 
  3824.       specify a module definition file that has a NAME statement. The 
  3825.       executable file usually has an .EXE extension. 
  3826.  
  3827.      A dynamic link library file. A dynamic link library is produced whenever 
  3828.       you specify a module definition file that has a LIBRARY statement. A 
  3829.       dynamic link library file usually has a .DLL extension. 
  3830.  
  3831.      A device driver file. A virtual or physical device driver is produced 
  3832.       whenever you specify a module definition file that has the VIRTUAL DEVICE 
  3833.       or PHYSICAL DEVICE statements. A device driver file usually has a .SYS 
  3834.       extension. 
  3835.  
  3836.  Note: 
  3837.  
  3838.  Three additional options are available with the OS/2 Warp Toolkit: 
  3839.  
  3840.  /E[XEPACK:{1|2}]              Causes pages of code and data in the file to be 
  3841.                                compressed. 
  3842.  
  3843.  /NOO[UTPUTONERROR]            Prevents the LINK386 from creating the 
  3844.                                executable file if an error is encountered. 
  3845.  
  3846.  /NOS[ECTORALIGNCODE]          Turns off the alignment feature provided through 
  3847.                                the LINK386 linker. LINK386 normally aligns 
  3848.                                pages of code on sector (512 byte) boundaries, 
  3849.                                reducing the time to load the pages when the 
  3850.                                application is executed. The /NOSECTORALIGNCODE 
  3851.                                option aligns pages of code based on the value 
  3852.                                used in the /ALIGN option. 
  3853.  
  3854.  
  3855. ΓòÉΓòÉΓòÉ 7.4.1.6.1. Creating a Response File for LINK386 ΓòÉΓòÉΓòÉ
  3856.  
  3857. To operate LINK386 using a response file, you must first create a file that 
  3858. contains the responses you want LINK386 to process. You can give the file any 
  3859. name and create it with any text editor. 
  3860.  
  3861. Type the following command at the command prompt: 
  3862.  
  3863.    LINK386 @filename[.ext]
  3864.  
  3865. The @ symbol tells LINK386 that filename is a response file. If the file is not 
  3866. in the working directory, you must specify the path. Begin using a response 
  3867. file at any point on the LINK386 command line or at any LINK386 prompt. The 
  3868. file should contain responses in the same order as the LINK386 prompts. Each 
  3869. response needs to be on a separate line. If you choose to place responses on 
  3870. the same line, separate them with commas. 
  3871.  
  3872. If the file does not contain responses for all the prompts, LINK386 displays 
  3873. the appropriate prompt and waits for you to supply a response. End the response 
  3874. file with a semicolon. 
  3875.  
  3876. You can use special characters in the response file the same way you would use 
  3877. them in responses entered at the keyboard. 
  3878.  
  3879.  
  3880. ΓòÉΓòÉΓòÉ 7.4.1.6.2. Example of a Response File for LINK386 ΓòÉΓòÉΓòÉ
  3881.  
  3882. The response file in the following example instructs LINK386 to generate an 
  3883. executable file called FUN.EXE, and four object modules:  FUN, SUN, RUN, and 
  3884. GAMES. 
  3885.  
  3886.   fun+sun+run+games /map
  3887.   fun.exe
  3888.   funlist
  3889.   ;
  3890.  
  3891. If you specify the file name FUNLIST, LINK386 will generate a map file named 
  3892. FUNLIST.MAP. Adding the /MAP option causes LINK386 to include the public 
  3893. symbols of the application in the map file. 
  3894.  
  3895.  
  3896. ΓòÉΓòÉΓòÉ 7.4.1.6.3. OS2STUB.EXE ΓòÉΓòÉΓòÉ
  3897.  
  3898. OS2STUB.EXE is included in the executable file created by LINK386 if the STUB 
  3899. statement is included in the module definition file. The stub is invoked 
  3900. whenever the file is executed under DOS. By default, LINK386 adds its own 
  3901. standard stub for this purpose. 
  3902.  
  3903.  
  3904. ΓòÉΓòÉΓòÉ 7.4.1.7. MASM2ALP ΓòÉΓòÉΓòÉ
  3905.  
  3906. MASM2ALP is a utility that accepts a Microsoft Macro Assembler (MASM) 
  3907. command-line syntax, translates the parameters into a syntax acceptable to the 
  3908. ALP assembler, and then invokes ALP.EXE to perform the assembly.  It allows ALP 
  3909. to be used in place of MASM without requiring modifications to existing 
  3910. makefiles.  See the ALP Programming Guide and Reference for more information. 
  3911.  
  3912.  
  3913. ΓòÉΓòÉΓòÉ 7.4.1.8. MARKEXE ΓòÉΓòÉΓòÉ
  3914.  
  3915. MARKEXE lets you view and set the type of application. The type of application 
  3916. identifies the OS/2 sessions in which a program can run. You can use MARKEXE in 
  3917. conjunction with programs that you have created using LINK386 or with programs 
  3918. created by some other means. 
  3919.  
  3920.  
  3921. ΓòÉΓòÉΓòÉ 7.4.1.9. MKMSGF ΓòÉΓòÉΓòÉ
  3922.  
  3923. MKMSGF converts a text message file to an output (binary) message file that 
  3924. DosGetMessage uses to display messages. Text messages in OS/2 full-screen 
  3925. applications do not need to be loaded into memory with the application; they 
  3926. can reside on disk until needed. 
  3927.  
  3928. You can use the output message file by specifying a message file name and a 
  3929. message number in the DosGetMessage parameter list. The messages also can be 
  3930. bound to the executable file by MSGBIND. 
  3931.  
  3932.  
  3933. ΓòÉΓòÉΓòÉ 7.4.1.9.1. Creating a MKMSGF ΓòÉΓòÉΓòÉ
  3934.  
  3935. The input message file is a standard ASCII file that contains three types of 
  3936. lines: 
  3937.  
  3938.      Comment 
  3939.      Component identifier 
  3940.      Component message 
  3941.  
  3942.  Comment lines are the first lines of a file and must begin with a semicolon. A 
  3943.  component-identifier is a three-character name identifier (for example, "DOS") 
  3944.  that precedes all MKMSGF message numbers.  Component-message lines consist of 
  3945.  a message header and an ASCII text message. 
  3946.  
  3947.  The following is an example of a text message source file. 
  3948.  
  3949.     ;This is an example
  3950.     ;of a text message
  3951.     ;file
  3952.     DOS
  3953.     DOS0100E: File not found
  3954.     DOS0101?:
  3955.     DOS0102H: Usage: del [drive:][path] filename
  3956.     DOS0103?:
  3957.     DOS0104I: 1% files copied
  3958.     DOS0105?:
  3959.     DOS0106W: Warning! All data will be erased!
  3960.     DOS0107?:
  3961.     DOS0108?:
  3962.     DOS0109P: Do you wish to apply these patches (Y or N)? %0
  3963.  
  3964.  where: 
  3965.  
  3966.  DOS0100E - DOS0109P      Identifies message numbers in sequence. The first 
  3967.                           three characters indicate the component identifier; 
  3968.                           the four-digit number indicates the message number, 
  3969.                           which is followed by a letter (described below), and 
  3970.                           then a colon and blank space. If a message number is 
  3971.                           not used, type the number, end it with a question 
  3972.                           mark (?), and leave an empty entry. 
  3973.  
  3974.  E, H, I, P, W            Indicates the type of message. Categories include 
  3975.                           error (E), help (H), information (I), prompt (P), and 
  3976.                           warning (W). 
  3977.  
  3978.  %0                       Displays a prompt for input from the user, after 
  3979.                           which a carriage return and line feed are inserted. 
  3980.  
  3981.  
  3982. ΓòÉΓòÉΓòÉ 7.4.1.10. MKTMPF ΓòÉΓòÉΓòÉ
  3983.  
  3984. MKTMPF creates template repository files from text input files. A template 
  3985. repository is a binary file used by the OS/2 Error Logging Facility to find 
  3986. error messages, causes, and actions in various message files. MKTMPF is located 
  3987. in the \TOOLKIT\BIN subdirectory. 
  3988.  
  3989. MKTMPF is located in the \TOOLKIT\BIN subdirectory.
  3990.  
  3991.  
  3992. ΓòÉΓòÉΓòÉ 7.4.1.11. MSGBIND ΓòÉΓòÉΓòÉ
  3993.  
  3994. When DosGetMessage is issued, it searches for the message in the message 
  3995. segment bound to the application's executable file, and then searches the 
  3996. application's message file on a hard disk. To ensure that a message is 
  3997. displayed quickly, you can bind it to the application's executable file by 
  3998. using the MSGBIND utility program.  For each executable file, MSGBIND specifies 
  3999. which message files to scan; for each message file, it specifies which message 
  4000. to include in the executable file. 
  4001.  
  4002. Note:  The MSGBIND utility program supports the new compression format 
  4003.        available with LINK386 (/EXEPACK:2) and RC (-x2). 
  4004.  
  4005.  The input file contains three types of lines: 
  4006.  
  4007.      > Executable file 
  4008.      < Message file 
  4009.      Message numbers 
  4010.  
  4011.  An example of an input file follows: 
  4012.  
  4013.     >PROG1.EXE
  4014.     <\MESSAGES\PRGMSG.MSG
  4015.     PRG0100
  4016.     PRG0101
  4017.     PRG0102
  4018.     <\MESSAGES\APP.MSG
  4019.     APP0001
  4020.     APP0002
  4021.     APP0003
  4022.  
  4023.  where: 
  4024.  
  4025.  >PROG1.EXE      Is the executable file to be modified 
  4026.  
  4027.  <               Defines the first message of a series to be bound, delimited 
  4028.                  either by the end of the series or a less-than symbol (<). 
  4029.  
  4030.  <\MESSAGES\PRGMSG.MSG and <\MESSAGES\APP.MSG Names the files containing the 
  4031.                  binary versions of the messages (created by MKMSGF) and their 
  4032.                  identifying numbers: the three-character component identifier 
  4033.                  and the four-digit message number. 
  4034.  
  4035.  
  4036. ΓòÉΓòÉΓòÉ 7.4.1.12. NMAKE ΓòÉΓòÉΓòÉ
  4037.  
  4038. NMAKE carries out all tasks needed to create or update a program after one or 
  4039. more of the source files in the program have changed. NMAKE compares the 
  4040. modification dates for one set of files (the target files) with those of 
  4041. another set of files (the dependent files).  NMAKE then carries out a given 
  4042. task only if a target file is out of date. NMAKE does not compile and link all 
  4043. files just because one file was updated. This can save time when creating 
  4044. programs that have many source files or that take several steps to complete. 
  4045.  
  4046.  
  4047. ΓòÉΓòÉΓòÉ 7.4.1.12.1. Using NMAKE ΓòÉΓòÉΓòÉ
  4048.  
  4049. To use NMAKE, create a description file (or makefile). A description file, in 
  4050. its simplest form, lists which files depend on others and which commands need 
  4051. to be executed if a file changes. You can create an NMAKE description file with 
  4052. any text editor that produces ASCII files. 
  4053.  
  4054. A description file looks like this: 
  4055.  
  4056.     targets... : dependents...Γöé
  4057.          command              ΓöéΓöÇΓöÇΓöÇΓöÇ description block
  4058.             :                 Γöé
  4059.     targets... : dependents...
  4060.          command
  4061.             :
  4062.  
  4063. A dependent relationship among files is defined in a description block. A 
  4064. description block indicates the relationship among various parts of the 
  4065. program. It contains commands to bring all components up-to-date. The 
  4066. description file can contain any number of description blocks. 
  4067.  
  4068. Use NMAKE description files for creating backup files, configuring data files, 
  4069. and running programs when data files are modified. 
  4070.  
  4071.  
  4072. ΓòÉΓòÉΓòÉ 7.4.1.13. PACK and UNPACK ΓòÉΓòÉΓòÉ
  4073.  
  4074. PACK reduces the size of a file by compressing its data. You can use PACK for a 
  4075. single file or a group of files, thereby reducing the disk space required for 
  4076. your OS/2 application. UNPACK (provided with the OS/2 operating system) 
  4077. restores a compressed file to its original size and copies it to a specified 
  4078. directory. 
  4079.  
  4080.  
  4081. ΓòÉΓòÉΓòÉ 7.4.1.13.1. Creating a List File ΓòÉΓòÉΓòÉ
  4082.  
  4083. To use a list file with PACK, you must first create a file that contains the 
  4084. names of the files you want to compress. You can give the list file any name. 
  4085. Following is an example of specifying a list file at the command line: 
  4086.  
  4087.    PACK DEVICE.LST DEVICE.DRV /L
  4088.  
  4089. The /L indicates that DEVICE.LST is a list file. If the list file is not in the 
  4090. working directory, you must specify the drive and path. Global file-name 
  4091. characters are not permitted in the list-file name. DEVICE.DRV is the 
  4092. destination file for the end-to-end-compressed data. (End-to-end compressed 
  4093. data is the data from each of the files contained in the list file. This data 
  4094. is stored in a contiguous format in the destination file.) 
  4095.  
  4096. The syntax used in the list file is similar to that used in the command line. 
  4097. The syntax for a single line in the list file follows: 
  4098.  
  4099.    sourcefile [/H:headerpath\|/H:headerfile|/H:headerpath\ headerfile]
  4100.               [/D:headerdate] [/T:headertime] [/C]
  4101.  
  4102. Remember, when using the list-file method (method 2), global file-name 
  4103. characters are not permitted in the source-file name. Notice also that "PACK" 
  4104. is excluded, and packedfile is not permitted in the list file, because they 
  4105. were specified on the command line. You can include comments or blank lines by 
  4106. entering a semicolon as the first character of the line. An example of a list 
  4107. file follows: 
  4108.  
  4109.    ;This is a comment
  4110.    C:\OS2\COMMAND.COM
  4111.    CONFIG.SYS /H:CONFIG.BAK /C
  4112.    \OS2\INSTALL\DDINSTAL.EXE /H:\OS2\DDINSTAL.TMP /D:10-15-91 /T:11.45
  4113.  
  4114.  
  4115. ΓòÉΓòÉΓòÉ 7.4.1.14. PACK2 and UNPACK2 ΓòÉΓòÉΓòÉ
  4116.  
  4117. The algorithm used to compress files has been substantially enhanced. The use 
  4118. of these utility programs is identical to the PACK and UNPACK  utilities, which 
  4119. are documented in the Tools Reference. 
  4120.  
  4121. Note:  UNPACK2 is provided with the OS/2 operating system. 
  4122.  
  4123.  
  4124. ΓòÉΓòÉΓòÉ 7.4.1.15. TRCUST, MAKETSF, and DEBDEL ΓòÉΓòÉΓòÉ
  4125.  
  4126. The Trace Customizer utility program (TRCUST) converts a trace source file 
  4127. (TSF) to a trace format file (TFF) that defines the formatting for an event 
  4128. trace record. You can use TRCUST to combine multiple TFFs into a single TFF. 
  4129.  
  4130. Two additional tools that are complementary to TRCUST are also included in the 
  4131. Toolkit: 
  4132.  
  4133.      MAKETSF 
  4134.  
  4135.       The purpose of MAKETSF is to extract dynamic trace definitions imbedded 
  4136.       in C or ASM source file to which they  relate. MAKETSF can also 
  4137.       substitute line number information into those trace definitions that are 
  4138.       specified by line number and source file reference. 
  4139.  
  4140.      DEBDEL 
  4141.  
  4142.       The purpose of DEBDEL is to remove debugging information from a load 
  4143.       module after TRCUST has generated the trace definition file (TDF). 
  4144.  
  4145.  For more information on all of these tools, refer to the OS/2 Debugging 
  4146.  Handbook. 
  4147.  
  4148.  
  4149. ΓòÉΓòÉΓòÉ 7.4.2. Multimedia Tools ΓòÉΓòÉΓòÉ
  4150.  
  4151. This section describes the Multimedia tools that help you develop multimedia 
  4152. programs. The following multimedia tools are available in this release: 
  4153.  
  4154.      MIDICONV - MIDI Conversion Utility 
  4155.      P2STRING 
  4156.  
  4157.  Note:  The Wave Doctor, previously available with the OS/2 Multimedia Toolkit 
  4158.         product, is not available with this version of the OS/2 Warp Toolkit. 
  4159.  
  4160.  
  4161. ΓòÉΓòÉΓòÉ 7.4.2.1. MIDICONV ΓòÉΓòÉΓòÉ
  4162.  
  4163. MIDICONV is a conversion utility program that lets you convert a MIDI format 1 
  4164. file to a MIDI format 0 file through the use of an installable I/O procedure. 
  4165.  
  4166. Note:  A MIDI format 0 file has only one track of music; a MIDI format 1 file 
  4167.        has multiple tracks of music. 
  4168.  
  4169.  
  4170. ΓòÉΓòÉΓòÉ 7.4.2.2. P2STRING ΓòÉΓòÉΓòÉ
  4171.  
  4172. P2STRING is used to test OS/2 multimedia subsystems through the media control 
  4173. interface string commands in the OS/2 multimedia environment. This tool 
  4174. processes script files (containing string commands and tool directives) to test 
  4175. the behavior of subsystems in OS/2 multimedia.  P2STRING extracts the strings 
  4176. from the script files and processes the commands through the mciSendString 
  4177. function. Messages and error conditions of the processes included in the 
  4178. scripts are logged to an output file and displayed in windows. 
  4179.  
  4180. P2STRING provides subsystem developers with an effective testing tool because 
  4181. it alleviates the need for extensive test code to be written. Developers can 
  4182. write script files to test all relevant scenarios and it also aids in debugging 
  4183. using log files. 
  4184.  
  4185. Note:  Refer to the README.P2S file in the P2STRING subdirectory for 
  4186.        information about how to use P2STRING and how to create script files 
  4187.        that it can process. The OS/2 Multimedia Subsystem Programming Guide 
  4188.        contains additional information describing P2STRING. 
  4189.  
  4190.  
  4191. ΓòÉΓòÉΓòÉ 7.4.3. Presentation Manager (PM) Tools ΓòÉΓòÉΓòÉ
  4192.  
  4193. This section describes the Presentation Manager tools that help you develop 
  4194. Presentation Manager programs: 
  4195.  
  4196.      DLGEDIT - Dialog Editor 
  4197.      FONTEDIT - Font Editor 
  4198.      ICONEDIT - Icon Editor 
  4199.      IPFC - Information Presentation Facility Compiler 
  4200.      RC - Resource Compiler 
  4201.  
  4202.  
  4203. ΓòÉΓòÉΓòÉ 7.4.3.1. DLGEDIT ΓòÉΓòÉΓòÉ
  4204.  
  4205. DLGEDIT (Dialog Editor) is used to create and modify dialog boxes and specify 
  4206. the controls and text within dialog boxes. As you create a dialog box and add 
  4207. controls, the dialog editor draws it to the screen. You can resize and 
  4208. reposition the dialog box, and then test its controls before you incorporate it 
  4209. in your application. 
  4210.  
  4211. Although the dialog editor draws box outlines and controls to the screen so 
  4212. that you can view it from a user's perspective, the dialog editor does not save 
  4213. it as a graphic. Instead, the dialog editor stores a description of the dialog 
  4214. box and its controls in a text file that has a file-name extension of .DLG. It 
  4215. also creates a compiled form of the .DLG file into a resource file that has an 
  4216. extension of .RES. The dialog-box and resource files can each contain 
  4217. descriptions of more than one dialog box. The resource file can contain other 
  4218. application resources, such as icons, bitmaps, and string tables. It is 
  4219. attached to the application's executable (.EXE) file after the compile and link 
  4220. processes. 
  4221.  
  4222. This version of the Dialog Editor is enhanced for use with Pen for OS/2. With 
  4223. this enhanced version, handwriting and sketch controls are available. 
  4224.  
  4225.  
  4226. ΓòÉΓòÉΓòÉ 7.4.3.2. FONTEDIT ΓòÉΓòÉΓòÉ
  4227.  
  4228. FONTEDIT (Font Editor) is used to design and save fonts for use in 
  4229. applications. A font is a set of alphanumeric characters, punctuation marks, 
  4230. and other symbols that share a common typeface design and line weight. 
  4231.  
  4232. When the font editor creates a font file, it supplies an .FNT file-name 
  4233. extension. The font file contains a header, which describes the font in general 
  4234. terms, and a section that contains bitmaps of the characters themselves. 
  4235.  
  4236.  
  4237. ΓòÉΓòÉΓòÉ 7.4.3.2.1. Font Resource Files ΓòÉΓòÉΓòÉ
  4238.  
  4239. All resources, except fonts, can be bound to the application's executable file 
  4240. or compiled into a dynamic link library (DLL). Fonts must be put in a separate 
  4241. .DLL using the RC. You then link the file at run time and load the resources 
  4242. into your application by using DosLoadModule or GpiLoadFonts. A .DLL containing 
  4243. font resources must have a file-name extension of .FON. The .FON file can be 
  4244. installed on the system. 
  4245.  
  4246.  
  4247. ΓòÉΓòÉΓòÉ 7.4.3.3. ICONEDIT ΓòÉΓòÉΓòÉ
  4248.  
  4249. ICONEDIT (Icon Editor) is used to create icons, pointers, and bitmaps. In the 
  4250. PM, an icon is a graphic symbol that identifies a data object, a system action, 
  4251. or a minimized application. A pointer is a small shape on the screen that 
  4252. reflects the movement of the mouse. Pointers have a hot spot that identifies 
  4253. their exact location on the screen. 
  4254.  
  4255. Icons, pointers, and bitmaps produced by the Icon Editor are graphic symbols 
  4256. comprised of pels in any of the following display states: 
  4257.  
  4258.      Black 
  4259.      White 
  4260.      Color 
  4261.      Screen (background color) 
  4262.      Inverse screen (inverse of background color). 
  4263.  
  4264.  Mini-icons (also called small icons) are icons that are one-half the size of 
  4265.  normal icons (also called large icons). Normal icons are 32x32 or 40x40 pels 
  4266.  (depending on the monitor resolution). Mini-icons are 16x16 or 20x20 pels. 
  4267.  They are used in areas where a normal icon is too large, for example, in 
  4268.  toolbars. 
  4269.  
  4270.  If you previously had OS/2 installed on your system, and if you did not update 
  4271.  your icon profile when you installed this OS/2 Warp Toolkit, you need to run 
  4272.  the Icon Editor once with its profile update options in order to use the 
  4273.  mini-icon forms. To do this, enter: 
  4274.  
  4275.   X:\TOOLKIT\BIN\ICONEDIT /t /i
  4276.  
  4277.  where X is the drive location for the installed OS/2 Warp Toolkit. 
  4278.  
  4279.  After the initial run of Icon Editor, the new mini-icons will be part of your 
  4280.  profile and you will not need to use options /t /i again. 
  4281.  
  4282.  
  4283. ΓòÉΓòÉΓòÉ 7.4.3.3.1. Starting ICONEDIT ΓòÉΓòÉΓòÉ
  4284.  
  4285. To start the Icon Editor, select the PM Development Tools folder, and then 
  4286. select the Icon Editor object. The following window is displayed: 
  4287.  
  4288. Notice the information area at the top of the Icon Editor window; the items 
  4289. displayed from left to right include: 
  4290.  
  4291.      A two-button mouse, showing the color currently selected for each button 
  4292.      An actual-size image of the current figure that you are editing 
  4293.      A status area that provides: 
  4294.  
  4295.  
  4296.         -  Size (in pels using X- and Y-coordinates) 
  4297.         -  Pen location 
  4298.         -  Pen size (from 1-by-1 to 9-by-9) 
  4299.         -  Hot spot (for icons and pointers, but not bitmaps) 
  4300.         -  Figure type (icon, pointer, or bitmap) 
  4301.         -  Form name 
  4302.  
  4303.  The palette window, in the lower-right corner, displays the colors that are 
  4304.  available for use during editing. The colors currently selected are marked 
  4305.  with frames. 
  4306.  
  4307.  The editing window is the largest part of your working area. Use the mouse to 
  4308.  paint the enlarged representation with the selected color. 
  4309.  
  4310.  The menu-bar choices provide access to the many functions of the Icon Editor. 
  4311.  These choices enable you to: 
  4312.  
  4313.      Create a new icon, pointer, or bitmap 
  4314.      Edit an existing icon, pointer, or bitmap 
  4315.      Test the new icon or pointer 
  4316.      Superimpose a grid over the editing window (for drawing a symmetrical 
  4317.       figure) 
  4318.      Restrict a drawing to straight vertical or horizontal lines 
  4319.      Make transparent pels (for icons or pointers) visible 
  4320.      Change the shape and size of the pen 
  4321.      Select system preferences (to set prompts or suppress warnings) 
  4322.      Define hot spots (where the mouse pointer is directed). 
  4323.  
  4324.  
  4325. ΓòÉΓòÉΓòÉ 7.4.3.4. IPFC ΓòÉΓòÉΓòÉ
  4326.  
  4327. Information Presentation Facility (IPF) is a set of tools used to create an 
  4328. online help facility for an application. IPF is also used to create online 
  4329. information that can be viewed independent of an application. It is a tool for 
  4330. both the information author and the application programmer. 
  4331.  
  4332. As an author of online information, you can define the windows in which 
  4333. information is displayed. For example, a window can be split so that scrollable 
  4334. text can be displayed beside a stationary illustration that the text describes. 
  4335. The following figure shows an IPF application-control-window. 
  4336.  
  4337.  
  4338. ΓòÉΓòÉΓòÉ 7.4.3.4.1. Developing Online Information ΓòÉΓòÉΓòÉ
  4339.  
  4340. IPF makes it possible for you to design your information in two types of 
  4341. formats: 
  4342.  
  4343.      An online document format for reference books 
  4344.      A help-window format for context-sensitive help for your application 
  4345.       programs 
  4346.  
  4347.  To produce either format, you must create a text file using a text editor and 
  4348.  two IPF elements: 
  4349.  
  4350.      IPF tagging language, which consists of instructions for formatting and 
  4351.       displaying your document on the screen. 
  4352.      Information Presentation Facility Compiler (IPFC), which interprets the 
  4353.       tags and converts the source file into an IPF format. 
  4354.  
  4355.  
  4356. ΓòÉΓòÉΓòÉ 7.4.3.4.2. Compiling Help Files ΓòÉΓòÉΓòÉ
  4357.  
  4358. To compile a source file that is intended as a help-text window, use the IPFC 
  4359. command without the /INF option. For example: 
  4360.  
  4361. IPFC myhelp.hlp
  4362.  
  4363.  
  4364. ΓòÉΓòÉΓòÉ 7.4.3.4.3. Compiling with International Language Considerations ΓòÉΓòÉΓòÉ
  4365.  
  4366. The following parameters provide international language support: 
  4367.  
  4368.  /COUNTRY  = nnn  (where nnn is the 3-digit country code)
  4369.  /CODEPAGE = nnnn  (where nnnn is the 3 or 4-digit code page)
  4370.  /LANGUAGE = xxx  (where xxx is a 3-letter identifier that
  4371.              indicates an international language file is to be used)
  4372.  
  4373. An example of the command-line syntax follows: 
  4374.  
  4375. IPFC myfile.txt /INF /COUNTRY=033 /CODEPAGE=437 /LANGUAGE=FRA
  4376.  
  4377. You can now add additional languages to IPFC by providing an IPFxxx.NLS file 
  4378. where xxx matches the name of the language supplied with the /LANGUAGE or -L 
  4379. switch. 
  4380.  
  4381. You can also add additional code pages by providing an APSYxxxx.APS file where 
  4382. xxxx matches the number of the code page. Four-digit code pages are supported. 
  4383. Three-digit code pages have a leading 0 in their APSYxxxx.APS file name, but 
  4384. the leading 0 does not have to be passed with the /CODEPAGE or -C switch.  The 
  4385. underlying operating system must support the supplied code page. 
  4386.  
  4387. Note:  When adding new language or code page files, be sure they are located in 
  4388.        the same subdirectory where your IPFC program files are located. 
  4389.  
  4390.  The bidirectional version of IPFC.EXE (IPFCBIDI.EXE) is not included as a 
  4391.  separate program with this version of the OS/2 Warp Toolkit. However, the 
  4392.  bidirectional support in IPFCBIDI has been integrated into the American 
  4393.  version of the program, IPFC.EXE.  It will be necessary for you to modify any 
  4394.  makefiles that reference IPFCBIDI.EXE to reference IPFC.EXE instead. 
  4395.  
  4396.  
  4397. ΓòÉΓòÉΓòÉ 7.4.3.4.3.1. IPFC Environment Variables ΓòÉΓòÉΓòÉ
  4398.  
  4399. There are four environment variables that can be used to specify the location 
  4400. of source files: 
  4401.  
  4402.  IPFC               Specifies the location of the .IPF support files (such as 
  4403.                     APSYMBOL.APS and IPF*.NLS). 
  4404.  
  4405.  IPFCIMBED          Searches for files imbedded with the .im macro. 
  4406.  
  4407.  IPFCARTWORK        Specifies the location of artwork files and artlink files. 
  4408.  
  4409.  TMP                Indicates where the compiler should store the temporary 
  4410.                     files it creates during the compilation. 
  4411.  
  4412.  
  4413. ΓòÉΓòÉΓòÉ 7.4.3.4.4. Viewing an Online Document ΓòÉΓòÉΓòÉ
  4414.  
  4415. If you want to see your formatted online document, you can use the VIEW command 
  4416. to display it. 
  4417.  
  4418. An online document has an extension of .INF. It can be viewed by entering its 
  4419. name as a parameter to the VIEW command; for example: 
  4420.  
  4421. VIEW myfile
  4422.  
  4423. You do not need to include the .INF file extension. 
  4424.  
  4425. Note:  You cannot use VIEW to display help-text windows for application 
  4426.        programs. However, for test viewing purposes, you can compile the help 
  4427.        text as .INF files and use VIEW to look at the information. 
  4428.  
  4429.  
  4430. ΓòÉΓòÉΓòÉ 7.4.3.5. RC ΓòÉΓòÉΓòÉ
  4431.  
  4432. RC (Resource Compiler) is a tool that lets you add application resources, such 
  4433. as message strings, pointers, menus, and dialog boxes, to your application's 
  4434. executable file. The primary purpose of RC is to prepare data for applications 
  4435. that use functions such as WinLoadString, WinLoadPointer, WinLoadMenu, and 
  4436. WinLoadDlg. These functions load resources from the application's executable 
  4437. file or another specified executable file. The application then can use the 
  4438. loaded resources as needed. 
  4439.  
  4440. RC and the resource functions let you define and modify application resources 
  4441. without recompiling the application itself. RC can modify the resources in an 
  4442. executable file at any time without affecting the rest of the file. You can 
  4443. create custom applications from a single executable file by using RC to add the 
  4444. custom resources you need to each application.  RC is especially important for 
  4445. international language support because it lets you define all 
  4446. language-dependent data, such as message strings, as resources. Preparing the 
  4447. application for a new language is simply a matter of adding new resources to 
  4448. the existing executable file. 
  4449.  
  4450.  
  4451. ΓòÉΓòÉΓòÉ 7.4.3.5.1. Creating an RC File ΓòÉΓòÉΓòÉ
  4452.  
  4453. All resources are defined in a resource script file. You use a text editor to 
  4454. create a resource script file that has an .RC extension. Resources are defined 
  4455. either explicitly in statements in the resource script file, or in other files 
  4456. (such as output files from the resource editors). The .RC file is the input 
  4457. file to the RC; the output has an .RES extension. The .RC file can contain 
  4458. statements that define resources and that include resources from other files. 
  4459. Text-based resources such as menus, accelerator keys, and text strings are 
  4460. defined in the .RC file. Non-text-based resources are specified in the .RC file 
  4461. as file names of the external files where these resources reside. Such 
  4462. resources include icons, pointers, and bitmaps. The syntax for including 
  4463. external files in a resource script varies according to the nature of the 
  4464. resources defined or contained in the files. Fonts have a resource file to 
  4465. themselves. 
  4466.  
  4467. Make sure that none of the include files in your resource script file contain 
  4468. an end-of-file character. When the RC sees an end-of-file character, it assumes 
  4469. it to be the end of all input. 
  4470.  
  4471. For an example of a resource script file, see the sample program TEMPLATE. 
  4472.  
  4473.  
  4474. ΓòÉΓòÉΓòÉ 7.4.4. SOM Tools ΓòÉΓòÉΓòÉ
  4475.  
  4476. SOM tools help you develop SOM programs. This section describes the SOM tools: 
  4477.  
  4478.      CTOI 
  4479.      IRDUMP - Information Repository Dump 
  4480.      PDL - Public Definition Language 
  4481.      PREGIMPL  - PM version of REGIMPL 
  4482.      REGIMPL - Implementation Registration 
  4483.      SC - SOM Compiler 
  4484.      SOMCORBA - SOM CORBA 
  4485.      SOMDCHK - SOM Check 
  4486.      SOMDD - SOM DSOM Daemon 
  4487.      SOMDSRV - SOM Server 
  4488.      SOMENV - SOM Environment 
  4489.      SOMSTARS 
  4490.      SOMXH - SOM .XH Header Files 
  4491.      WPIDL2XH - Workplace Shell .IDL To .XH Files 
  4492.  
  4493.  
  4494. ΓòÉΓòÉΓòÉ 7.4.4.1. CTOI ΓòÉΓòÉΓòÉ
  4495.  
  4496. CTOI automates the conversion process from the SOM 1.0 format (.CSC files) to 
  4497. SOM 2.0 format (.IDL files). An example of the syntax follows: 
  4498.  
  4499. CTOI f1
  4500.  
  4501. where f1 is the name of the .CSC file to be converted. 
  4502.  
  4503. You might require some modifications to your environment and your existing code 
  4504. in order to use this tool successfully. For more information, see the article 
  4505. titled Using the SOM CTOI Tool in the online version of the Developer 
  4506. Connection News, Volume 5. This newsletter can be found by opening the 
  4507. following folders, starting with The Developer Connection folder: 
  4508.  
  4509.   The Developer Connection Browser
  4510.     The Developer Connection for OS/2 References
  4511.       Newsletters
  4512.         Developer Connection News
  4513.  
  4514.  
  4515. ΓòÉΓòÉΓòÉ 7.4.4.2. IRDUMP ΓòÉΓòÉΓòÉ
  4516.  
  4517. IRDUMP (Information Repository Dump) verifies that a class exists in the 
  4518. Information Repository. An example of the syntax follows: 
  4519.  
  4520. IRDUMP [-o] [-w] [-?] [object]
  4521.  
  4522. where: 
  4523.  
  4524.  -o       Includes file offset information. 
  4525.  
  4526.  -w       Follows dump with "within" operation. 
  4527.  
  4528.  -?       Shows this usage information. 
  4529.  
  4530.  object   Is a simple or fully qualified name of an object in the Interface 
  4531.           Repository. 
  4532.  
  4533.  The default action is to dump all objects. 
  4534.  
  4535.  
  4536. ΓòÉΓòÉΓòÉ 7.4.4.3. PDL ΓòÉΓòÉΓòÉ
  4537.  
  4538. PDL (Public Definition Language) is a separate program that performs the same 
  4539. function as the Public Definition Language (PDL) emitter used with the SOM 
  4540. Compiler.  That emitter generates a copy of an .IDL file that has had the 
  4541. portions designated as private removed. The file generated is the same as the 
  4542. .IDL file from which it is produced, except that it removes all items within 
  4543. the .IDL file that are marked as "private." An item is marked as private by 
  4544. surrounding it with #ifdef __PRIVATE__ and #endif directives.  Thus, the PDL 
  4545. emitter can be used to generate a "public" version of an .IDL file. (Generally, 
  4546. client programs will need only the "public" methods and attributes.) 
  4547.  
  4548. The PDL program can be invoked independently of the SOM Compiler.  In addition, 
  4549. the PDL program can remove any kind of items in the .IDL file that are preceded 
  4550. by a user-specified #ifdef directive and followed by an #endif directive. 
  4551.  
  4552. The PDL program is invoked as follows: 
  4553.  
  4554. PDL [-c] [-d] [-f] [-h] [-s] [-/] files
  4555.  
  4556. where: 
  4557.  
  4558.  -c cmd         Specifies that, for each .IDL file, the PDL program is to run 
  4559.                 the specified system command. This command can contain a single 
  4560.                 occurrence of the string %s, which will be replaced with the 
  4561.                 source file name before the command is executed. For example, 
  4562.                 the option -c sc -sh %s has the same effect as issuing the SC 
  4563.                 command with the -sh option. 
  4564.  
  4565.  -d dir         Specifies a directory in which the output files are to be 
  4566.                 placed. (The output files are given the same name as the input 
  4567.                 files). If no directory is specified, the output files are 
  4568.                 named <fileStem>.PDL (where fileStem is the file stem of the 
  4569.                 input file) and are placed in the current working directory. 
  4570.  
  4571.  -h             Requests this description of the PDL command syntax and 
  4572.                 options. 
  4573.  
  4574.  -f             Specifies that output files are to replace existing files with 
  4575.                 the same name, even if the existing files are read-only. By 
  4576.                 default, files are replaced only if they have write access. 
  4577.  
  4578.  -s smemit      Specifies the SMEMIT variable with which the PDL program is to 
  4579.                 invoke the SOM Compiler. 
  4580.  
  4581.  -/ <string>    Specifies the #ifdef pattern for which the PDL program will 
  4582.                 strip out .IDL statements.  The default value is #ifdef 
  4583.                 __PRIVATE__. 
  4584.  
  4585.  files          Specifies one or more .IDL files whose specified #ifdef 
  4586.                 sections are to be removed. File names must be completely 
  4587.                 specified (with the .IDL extension). If no #ifdef directive is 
  4588.                 specified (by including a -/<string> option), the #ifdef 
  4589.                 __PRIVATE__ sections will be removed by default. 
  4590.  
  4591.  Selected options can be specified individually, as a string of option 
  4592.  characters, or as a combination of both. Any option that takes an argument 
  4593.  either must be specified individually or must appear as the final option in a 
  4594.  string of option characters. 
  4595.  
  4596.  
  4597. ΓòÉΓòÉΓòÉ 7.4.4.4. PREGIMPL ΓòÉΓòÉΓòÉ
  4598.  
  4599. PREGIMPL is a Presentation Manager version of the REGIMPL tool. 
  4600.  
  4601.  
  4602. ΓòÉΓòÉΓòÉ 7.4.4.5. REGIMPL ΓòÉΓòÉΓòÉ
  4603.  
  4604. Before an implementation (a server program and class libraries) can be used by 
  4605. client applications, it must be registered with DSOM by running the 
  4606. Implementation Registration utility program, REGIMPL. This facility is 
  4607. available primarily for use in command (.CMD) files. 
  4608.  
  4609. During execution of REGIMPL, DSOM updates its database to include the new 
  4610. server implementation and the associated classes. This enables DSOM to find 
  4611. and, if necessary, to activate the server so that clients can invoke methods on 
  4612. it. 
  4613.  
  4614. Below are some examples on how you can use REGIMPL. 
  4615.  
  4616.      To enter interactive mode: 
  4617.  
  4618.             REGIMPL
  4619.  
  4620.      To add implementation: 
  4621.  
  4622.             REGIMPL -A -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>]
  4623.                                 [-h <str>] [-m {on|off}] [-z <str>]
  4624.  
  4625.      To update implementation: 
  4626.  
  4627.             REGIMPL -U -i <str> [-p <str>] [-v <str>] [-f <str>] [-b <str>]
  4628.                                 [-h <str>] [-m {on|off}]
  4629.  
  4630.      To delete implementation: 
  4631.  
  4632.             REGIMPL -D -i <str> [-i ...]
  4633.  
  4634.      To list implementations: 
  4635.  
  4636.             REGIMPL -L [-i <str> [-i ...]]
  4637.  
  4638.      To list aliases: 
  4639.  
  4640.             REGIMPL -S
  4641.  
  4642.      To add classes: 
  4643.  
  4644.             REGIMPL -a -c <str> [-c ...] -i <str> [-i ...]
  4645.  
  4646.      To delete classes: 
  4647.  
  4648.             REGIMPL -d -c <str> [-c ...] [-i <str> [-i ...]]
  4649.  
  4650.      To list classes associated with implementations: 
  4651.  
  4652.             REGIMPL -l [-i <str> [-i ...]]
  4653.  
  4654.       where: 
  4655.  
  4656.       -i <str>            Is the implementation alias name. 
  4657.       -p <str>            Is the server program name. The default value is 
  4658.                           SOMDSVR.EXE. 
  4659.       -v <str>            Is the server-class name. The default value is 
  4660.                           SOMDServer. 
  4661.       -f <str>            Is the reference data file name.  Use NULL to delete. 
  4662.       -b <str>            Is the reference data backup file name. Use NULL to 
  4663.                           delete. 
  4664.       -h <str>            Is the host machine name. The default value is 
  4665.                           localhost. 
  4666.       -m {on|off}         Enables multi-threaded server. 
  4667.       -z <str>            Is the implementation ID. 
  4668.       -c <str>            Is the class name. 
  4669.  
  4670.  
  4671. ΓòÉΓòÉΓòÉ 7.4.4.6. SC ΓòÉΓòÉΓòÉ
  4672.  
  4673. The OS/2 operating system provides a programming interface that enables 
  4674. applications to implement Desktop objects. This programming interface enables 
  4675. you to create Desktop objects that conform to the CUA architecture using a 
  4676. basic object-oriented programming interface. The interface is implemented using 
  4677. the IBM SC (SOM Compiler). 
  4678.  
  4679. The SOM Compiler (SC) helps implementers build classes in which interface and 
  4680. implementation are decoupled.  The SOM Compiler reads the IDL definition of a 
  4681. class interface and generates: 
  4682.  
  4683.      An implementation skeleton for the class 
  4684.      Bindings for implementors 
  4685.      Bindings for client programs 
  4686.  
  4687.  Bindings are language-specific macros and procedures that make implementing 
  4688.  and using SOM classes more convenient. These bindings offer a convenient 
  4689.  interface to SOM that is tailored to a particular programming language. For 
  4690.  instance, C programmers can invoke methods in the same way they make ordinary 
  4691.  procedure calls. The C++ bindings "wrap" SOM objects as C++ objects, so that 
  4692.  C++ programmers can invoke methods on SOM objects in the same way they invoke 
  4693.  methods on C++ objects. In addition, SOM objects receive full C++ 
  4694.  typechecking, just as C++ objects do. Currently, the SOM Compiler can generate 
  4695.  both C and C++ language bindings for a class. 
  4696.  
  4697.  
  4698. ΓòÉΓòÉΓòÉ 7.4.4.6.1. SMEMIT Environment Variable ΓòÉΓòÉΓòÉ
  4699.  
  4700. SMEMIT is used to indicate which emitter programs should be executed. Like the 
  4701. SMINCLUDE environment variable it can consist of a list of items separated by 
  4702. semicolons. Each item designates a particular emitter by the name of the file 
  4703. extension the emitter produces. The syntax is as follows: 
  4704.  
  4705. SMEMIT=[h;ih;c;xh;xih;xc;def;ir;pdl]
  4706.  
  4707. The default values are h and ih. For example: 
  4708.  
  4709. SET SMEMIT=H;IH;DEF;
  4710.  
  4711. indicates that EMITH.EXE, EMITIH.EXE, and EMITDEF.EXE programs should be 
  4712. executed to produce .H, .IH, and .DEF files, respectively. By default all 
  4713. emitted output files are placed in the same directory as the input file. If the 
  4714. SMEMIT environment variable is not defined, the SOM compiler will perform a 
  4715. syntax check of your class definition but no output will be produced. 
  4716.  
  4717. Note:  All command-line modifiers can be set in the environment by changing 
  4718.        them to UPPERCASE and preappending SM to them. 
  4719.  
  4720.  
  4721. ΓòÉΓòÉΓòÉ 7.4.4.6.2. SMINCLUDE Environment Variable ΓòÉΓòÉΓòÉ
  4722.  
  4723. The SOM compiler uses an environment variable called SMINCLUDE to locate 
  4724. included class definitions. SMINCLUDE specifies where to search for .IDL and 
  4725. .EFW files. Because every SOM class will have an include file for its parent 
  4726. class definition, you must set SMINCLUDE before running the SOM compiler. Its 
  4727. form is similar to the OS/2 PATH or DPATH environment variables, in that it can 
  4728. consist of one or more directory names, separated by a semicolon. Directory 
  4729. names can be specified with absolute or relative path names. The syntax is as 
  4730. follows: 
  4731.  
  4732. SMINCLUDE=<dir1>[;<dir2>]+
  4733.  
  4734. For example: 
  4735.  
  4736. SET SMINCLUDE=.;C:\TOOLKIT\SOM\INCLUDE;C:\TOOLKIT\IDL;
  4737.  
  4738. Note:  All command-line modifiers can be set in the environment by changing 
  4739.        them to UPPERCASE and preappending SM to them. 
  4740.  
  4741.  
  4742. ΓòÉΓòÉΓòÉ 7.4.4.6.3. SMKNOWNEXTS Environment Variable ΓòÉΓòÉΓòÉ
  4743.  
  4744. SMKNOWNEXTS add headers to user-written emitters. The syntax is as follows: 
  4745.  
  4746. SMKNOWNEXTS=ext[;ext]+
  4747.  
  4748. Note:  All command-line modifiers can be set in the environment by changing 
  4749.        them to UPPERCASE and preappending SM to them. 
  4750.  
  4751.  
  4752. ΓòÉΓòÉΓòÉ 7.4.4.6.4. SMTMP Environment Variable ΓòÉΓòÉΓòÉ
  4753.  
  4754. The SMTMP environment variable specifies the name of a directory that the SOM 
  4755. compiler uses to hold intermediate output files. The syntax is as follows: 
  4756.  
  4757. SMTMP=<dir>
  4758.  
  4759. For example: 
  4760.  
  4761. SET SMTMP=%TMP%
  4762.  
  4763. tells the SOM compiler to use the same directory for temporary files as given 
  4764. by the setting of the TMP environment variable. As a general rule, the 
  4765. directory indicated by SMTMP should never coincide with the directory used by 
  4766. the SOM compiler for its input or the emitted output files. 
  4767.  
  4768. Note:  All command-line modifiers can be set in the environment by changing 
  4769.        them to UPPERCASE and preappending SM to them. 
  4770.  
  4771.  
  4772. ΓòÉΓòÉΓòÉ 7.4.4.6.5. SOMIR Environment Variable ΓòÉΓòÉΓòÉ
  4773.  
  4774. SOMIR provides a list of IRs to search for. The syntax is as follows: 
  4775.  
  4776. SOMIR=<path>[;<path>]+
  4777.  
  4778. Note:  All command-line modifiers can be set in the environment by changing 
  4779.        them to UPPERCASE and preappending SM to them. 
  4780.  
  4781.  
  4782. ΓòÉΓòÉΓòÉ 7.4.4.6.6. #pragma Directives ΓòÉΓòÉΓòÉ
  4783.  
  4784. There are two pragma directives: 
  4785.  
  4786.  #pragma somemittypes on                 Turns on the emission of global types. 
  4787.  
  4788.  #pragma somemittypes off                Turns off the emission of global 
  4789.                                          types. 
  4790.  
  4791.  #pragma modifier <modifier stm>         Replaces a modifier statement. 
  4792.  
  4793.  
  4794. ΓòÉΓòÉΓòÉ 7.4.4.6.7. Running SOM Emitters ΓòÉΓòÉΓòÉ
  4795.  
  4796. You complete the SOM compilation process by running the emitters. You can 
  4797. control the output of the emitters from the command line by typing: 
  4798.  
  4799. command [-o filename] [-a name[=value]]*
  4800.  
  4801. where: 
  4802.  
  4803.  command              Is one of the following: 
  4804.  
  4805.                           EMITH 
  4806.                           EMITIH 
  4807.                           EMITC 
  4808.                           EMITDEF 
  4809.  
  4810.  filename             Is an explicit name (including drive, path, and file-name 
  4811.                       extension) for the emitted output file. If this option is 
  4812.                       not specified, the output file is placed in the current 
  4813.                       directory, and the file-name extension defaults to a type 
  4814.                       appropriate to the selected emitter program. 
  4815.  
  4816.  -a name[=value]      Adds a global attribute. 
  4817.  
  4818.  
  4819. ΓòÉΓòÉΓòÉ 7.4.4.7. SOMCORBA ΓòÉΓòÉΓòÉ
  4820.  
  4821. SOMCORBA is a command script that you can use to convert to implicit pointers 
  4822. (like CORBA) for interface references. 
  4823.  
  4824.  
  4825. ΓòÉΓòÉΓòÉ 7.4.4.8. SOMDCHK ΓòÉΓòÉΓòÉ
  4826.  
  4827. SOMDCHK evaluates the environment to verify whether DSOM can operate correctly. 
  4828. The program generates messages that evaluate the DSOM environment. It 
  4829. determines whether the necessary SOM DLLs can be located, whether DSOM is 
  4830. enabled for workgroup (cross-machine) communication, whether Interface and 
  4831. Implementation Repositories can be located, and it displays the settings of 
  4832. important environment variables. In its "verbose" mode, SOMDCHK gives the 
  4833. default settings for DSOM environment variables and explains how DSOM uses 
  4834. them. 
  4835.  
  4836. The program is invoked from the command line using the syntax given below. The 
  4837. optional verbose setting can be turned on by including the -v option with the 
  4838. following command: 
  4839.  
  4840. SOMDCHK [-v]
  4841.  
  4842.  
  4843. ΓòÉΓòÉΓòÉ 7.4.4.9. SOMDD ΓòÉΓòÉΓòÉ
  4844.  
  4845. SOMDD is the DSOM daemon. It must be started prior to running a DSOM 
  4846. application. The daemon can be started manually from the command line, or it 
  4847. could be started automatically from a start-up script run at boot time. It can 
  4848. be run in the background with the following command: 
  4849.  
  4850. START SOMDD
  4851.  
  4852. The SOMDD program requires no parameters. An optional -q  parameters can be 
  4853. used to set "quiet" mode, to suppress messages. 
  4854.  
  4855. Note:  The SOMDD.EXE program included with VisualAge C++ is incompatible with 
  4856.        the version of SOM used with OS/2 Warp Toolkit and should not be used. 
  4857.        You will need to update both your LIBPATH and PATH statements to ensure 
  4858.        that the OS/2 Warp Toolkit path is ahead of the VisualAge C++ compiler. 
  4859.  
  4860.  
  4861. ΓòÉΓòÉΓòÉ 7.4.4.10. SOMDSVR ΓòÉΓòÉΓòÉ
  4862.  
  4863. SOMDSVR is the "generic" server program. It can be started either from the 
  4864. command line or automatically upon demand. When starting SOMDSVR from the 
  4865. command line, the server's implementation ID or alias must be supplied as an 
  4866. argument. The command syntax for starting a generic SOM server is: 
  4867.  
  4868. SOMDSVR [impl_id | -a alias]
  4869.  
  4870.  
  4871. ΓòÉΓòÉΓòÉ 7.4.4.11. SOMENV ΓòÉΓòÉΓòÉ
  4872.  
  4873. SOMENV is a command script to set the environment variables required for SOM 
  4874. programming. This command script requires that the SOMBASE environment variable 
  4875. be set. 
  4876.  
  4877.  
  4878. ΓòÉΓòÉΓòÉ 7.4.4.12. SOMSTARS ΓòÉΓòÉΓòÉ
  4879.  
  4880. SOMSTARS is a command script that you can use to convert to explicit pointers 
  4881. for interface references. 
  4882.  
  4883.  
  4884. ΓòÉΓòÉΓòÉ 7.4.4.13. SOMXH ΓòÉΓòÉΓòÉ
  4885.  
  4886. SOMXH is a command script that you can use to create the .XH header files from 
  4887. the .IDL files located in the \TOOLKIT\SOM\INCLUDE subdirectory. 
  4888.  
  4889.  
  4890. ΓòÉΓòÉΓòÉ 7.4.4.14. WPIDL2XH ΓòÉΓòÉΓòÉ
  4891.  
  4892. WPIDL2XH.CMD is a command file to emit .XH header files from Workplace Shell 
  4893. .IDL files. 
  4894.  
  4895. To re-generate the .XH headers for C++, invoke this command file on each 
  4896. Workplace Shell class .IDL file from the Toolkit. It is only necessary to do 
  4897. this when you upgrade to a new level of SOM.  Invoking the SOMXH command script 
  4898. will create .XH files for you, as the Workplace Shell classes currently only 
  4899. maintain passthru sections for .H files for C. The syntax is as follows: 
  4900.  
  4901. WPIDL2XH <inputfile>
  4902.  
  4903.  
  4904. ΓòÉΓòÉΓòÉ 7.4.5. TCP/IP Tools ΓòÉΓòÉΓòÉ
  4905.  
  4906. The following TCP/IP tools are available in this release of the OS/2 Warp 
  4907. Toolkit: 
  4908.  
  4909.      RPCGEN 
  4910.      WSFORMAT 
  4911.  
  4912.  
  4913. ΓòÉΓòÉΓòÉ 7.4.5.1. RPCGEN ΓòÉΓòÉΓòÉ
  4914.  
  4915. Use the RPCGEN command to generate C code to implement an RPC protocol. The 
  4916. input to RPCGEN is a language similar to C, known as RPC language. 
  4917.  
  4918. You normally use RPCGEN infile to generate the following four output files. For 
  4919. example, if the infile is named PROTO.X, RPCGEN generates: 
  4920.  
  4921.      A header file called PROTO.H 
  4922.      XDR routines called PROTOX.C 
  4923.      Server-side stubs called PROTOS.C 
  4924.      Client-side stubs called PROTOC.C 
  4925.  
  4926.  RPCGEN is located in the \TOOLKIT\BIN subdirectory. 
  4927.  
  4928.  
  4929. ΓòÉΓòÉΓòÉ 7.4.5.2. WSFORMAT ΓòÉΓòÉΓòÉ
  4930.  
  4931. WSFORMAT is the WinSock 1.1 for OS/2 trace formatter. The WSFORMAT command 
  4932. accepts binary trace input from a serial port, file, or an OS/2 pipe, and 
  4933. converts the input into a readable format that can be displayed on the screen 
  4934. or written to a file, serial port, or OS/2 pipe. 
  4935.  
  4936.  
  4937. ΓòÉΓòÉΓòÉ 7.4.6. VoiceType Tools ΓòÉΓòÉΓòÉ
  4938.  
  4939. The Grammar Compiler takes a plain-text grammar file (BNF) and compiles it into 
  4940. a finite state grammar file (FSG). The FSG file is what the speech engine uses 
  4941. at run time to determine which words and phrases are currently available for a 
  4942. user to say to your application. 
  4943.  
  4944. Documentation on the Grammar compiler can be found in the Grammar Guide. The 
  4945. VoiceType Developer's Toolkit also includes the following utilities to assist 
  4946. you in evaluating grammars: 
  4947.  
  4948.      FSGENUM.EXE - Enumerates the strings produced by the grammar. 
  4949.  
  4950.      FSGTEST.EXE - Determines whether input strings are accepted by the 
  4951.       grammar. 
  4952.  
  4953.      FSGPRINT.EXE - Displays the graph that defines the grammar. 
  4954.  
  4955.      TIDYGRAM.EXE - Used to combine the Finite State Grammer (FSG) and What 
  4956.       Can I Say (WCS) files, allowing grammars to be displayed in the What Can 
  4957.       I Say window. 
  4958.  
  4959.  The Grammar compiler and utilities are located in the TOOLKIT\SPEECH\BIN 
  4960.  subdirectory. 
  4961.  
  4962.  
  4963. ΓòÉΓòÉΓòÉ 7.4.7. Workplace Shell Tools ΓòÉΓòÉΓòÉ
  4964.  
  4965. This section describes the Workplace Shell tools that help you develop 
  4966. Workplace Shell programs. There are two Workplace Shell tools in this release : 
  4967.  
  4968.      OBJUTIL - Object Utility/2 
  4969.      WPCLSLST - Workplace Class List 
  4970.  
  4971.  
  4972. ΓòÉΓòÉΓòÉ 7.4.7.1. OBJUTIL ΓòÉΓòÉΓòÉ
  4973.  
  4974. OBJUTIL (Object Utility/2) is a new Workplace Shell tool that provides a 
  4975. facility for registering classes, and creating and modifying instances of 
  4976. classes. 
  4977.  
  4978.  
  4979. ΓòÉΓòÉΓòÉ 7.4.7.2. WPCLSLST ΓòÉΓòÉΓòÉ
  4980.  
  4981. WPCLSLST (Workplace Class List) creates a workplace object class and an 
  4982. instance of a workplace object class. Workplace objects are constructed using 
  4983. the SOM protocol and are instances of one of the following workplace object 
  4984. classes: 
  4985.  
  4986.  Predefined     These classes are defined by the system. Examples of predefined 
  4987.                 workplace object classes are WPObject, WPFileSystem, and 
  4988.                 WPAbstract. 
  4989.  
  4990.  Subclass       These classes are derived from existing predefined workplace 
  4991.                 object classes. They add or remove function; however, they 
  4992.                 retain the basic behavior of that class. 
  4993.  
  4994.  Replaced       These classes replace the class being subclassed. They notify 
  4995.                 the behavior of an instance of a predefined workplace object 
  4996.                 class without the instance being aware of the new class. 
  4997.  
  4998.  
  4999. ΓòÉΓòÉΓòÉ 7.4.8. XPG4 Tools ΓòÉΓòÉΓòÉ
  5000.  
  5001. The OS/2 Warp Toolkit supports the development of fully internationalized, 
  5002. single source, single object (SSSO) applications that can be translated into 
  5003. other languages. This support is now enhanced by the addition of two new 
  5004. internationalization (I18N) models:  an implementation of industry standard 
  5005. XPG4 I18N functions and tools and an implementation of the IBM Universal 
  5006. Language Support (ULS) functions. 
  5007.  
  5008. Internationalization of programs requires that messages be displayed in the 
  5009. language of the user. This requirement is satisfied by producing versions of 
  5010. the messages that are translated into all supported languages. The OS/2 C 
  5011. library messaging support is based on the messaging support described in the 
  5012. X/Open XPG4 specification. It consists of functions for extracting messages 
  5013. from message catalog files (catopen, catgets, catclose) and the following 
  5014. utilities for producing message catalog files: 
  5015.  
  5016.      GENCAT - Generate Message Catalog Utility 
  5017.      MKCATDEF - Preprocess Message Source File Utility 
  5018.  
  5019.  The functions for extracting message from message catalog files are found in 
  5020.  the C Library Reference. 
  5021.  
  5022.  
  5023. ΓòÉΓòÉΓòÉ 7.4.8.1. GENCAT ΓòÉΓòÉΓòÉ
  5024.  
  5025. The GENCAT utility processes a message source file and produces a catalog file 
  5026. usable by the C library messaging functions. 
  5027.  
  5028. GENCAT creates the message catalog (usually *.cat) from a message source file 
  5029. (usually *.msg) or standard input. You can specify any number of message source 
  5030. files. A message source file is a text file that contains messages consisting 
  5031. of a message number followed by the message text. See the Preprocess Message 
  5032. Source File Utility (MKCATDEF) for using symbolic message identifiers in your 
  5033. message source file. 
  5034.  
  5035.  
  5036. ΓòÉΓòÉΓòÉ 7.4.8.2. MKCATDEF ΓòÉΓòÉΓòÉ
  5037.  
  5038. The Generate Message Catalog Utility (GENCAT) does not accept symbolic message 
  5039. identifiers; you must use the MKCATDEF utility if you want to use symbolic 
  5040. message identifiers in your message source file for use with GENCAT. 
  5041.  
  5042. MKCATDEF processes a message source file containing symbolic identifiers and 
  5043. produces the following output: 
  5044.  
  5045.      The SYMBOLNAME.H file, containing statements that equate symbolic 
  5046.       identifiers with the set numbers and message ID numbers assigned by 
  5047.       MKCATDEF. You must include the SYMBOLNAME.H file in your application 
  5048.       program to associate the symbolic names to the set and message numbers 
  5049.       assigned by MKCATDEF. 
  5050.  
  5051.      A new message source file containing message numbers instead of symbolic 
  5052.       message identifiers. This output is suitable for input to GENCAT. 
  5053.  
  5054.  MKCATDEF sends the new message source file, with numbers instead of symbolic 
  5055.  identifiers, to standard output. You can use MKCATDEF output as input to 
  5056.  GENCAT in the following ways: 
  5057.  
  5058.      Use MKCATDEF with a > (redirection symbol) to write the new message 
  5059.       source to a file. Use this file as input to GENCAT. 
  5060.  
  5061.      Pipe the MKCATDEF output file directly to GENCAT. 
  5062.  
  5063.  After running MKCATDEF, you can use symbolic names in an application to refer 
  5064.  to messages. 
  5065.  
  5066.  
  5067. ΓòÉΓòÉΓòÉ 7.5. Online Documentation ΓòÉΓòÉΓòÉ
  5068.  
  5069. The Toolkit provides a variety of online documentation for your needs.  The 
  5070. OS/2 Warp Online Technical Library provides both guidance and reference 
  5071. information.  This information can help you develop applications for OS/2 Warp. 
  5072.  
  5073. The following topics describe the different online documentation. 
  5074.  
  5075.  
  5076. ΓòÉΓòÉΓòÉ 7.5.1. OS/2 Warp Online Technical Library ΓòÉΓòÉΓòÉ
  5077.  
  5078. The following online books are located in the \TOOLKIT\BOOK subdirectory. You 
  5079. can also access them from the Desktop by opening the Toolkit folder and then 
  5080. the Toolkit Information folder. The titles in the list below are the same as 
  5081. the associated book icon names in the Toolkit Information folder. 
  5082.  
  5083.      ALP Programming Guide and Reference 
  5084.      Bidirectional Language Programming Guide 
  5085.      C Library Reference 
  5086.      Control Program Programming Guide and Reference 
  5087.      DMI Programmer's Guide 
  5088.      DPI Programmer's Guide 
  5089.      GPI Guide and Reference 
  5090.      IBM OS/2 Server Family Programming Reference 
  5091.      IPF Programming Guide and Reference 
  5092.      Multimedia Application Programming Guide 
  5093.      Multimedia Programming Reference 
  5094.      Multimedia Subsystem Programming Guide 
  5095.      Object REXX Programming Guide for OS/2 
  5096.      Open32 Programming Guide and Reference 
  5097.      OpenGL Programming Reference 
  5098.      OS/2 Debugging Handbook 
  5099.      OS/2 Programming Guide and Reference Addendum for OS/2 Warp Server for 
  5100.       e-business 
  5101.      Presentation Manager Programming Guide and Reference 
  5102.      Problem Determination Guide and Reference 
  5103.      RXSTRING.DOC 
  5104.      SOM Programming Guide 
  5105.      SOM Programming Reference 
  5106.      TCP/IP Programming Reference 
  5107.      Tools Reference 
  5108.      Unicode Programming Reference 
  5109.      Windows Sockets 
  5110.      Workplace Shell Programming Guide 
  5111.      Workplace Shell Programming Reference 
  5112.  
  5113.  
  5114. ΓòÉΓòÉΓòÉ 7.5.1.1. How to Use Online Documents ΓòÉΓòÉΓòÉ
  5115.  
  5116. The online documents in the OS/2 Warp Toolkit were developed with IPF. IPF 
  5117. displays information through a familiar user interface and lets you do the 
  5118. following: 
  5119.  
  5120.      View a table of contents from which you can quickly gain access to a 
  5121.       category 
  5122.      View the category and select related topics from a menu 
  5123.      View multiple windows of related information for comparison values 
  5124.      Search for a topic throughout the document 
  5125.      Copy the contents of a topic to the system clipboard for editing with the 
  5126.       OS/2 System Editor, the Enhanced Editor, or any other editor with this 
  5127.       capability 
  5128.      Copy the contents of a topic to a temporary file for editing with a text 
  5129.       editor 
  5130.  
  5131.  When installed, the online documents are added to the Toolkit Information 
  5132.  folder. To access the online documents, double-click on the folder, and then 
  5133.  select the appropriate book. A window that has a table of contents (Contents 
  5134.  window) is displayed. 
  5135.  
  5136.  When the Contents window is displayed, some categories have a plus sign (+) 
  5137.  beside them. The plus sign indicates that additional topics are available. 
  5138.  Using the left mouse button, click on the plus sign to expand the category. 
  5139.  
  5140.  For more information about using the OS/2 Warp Toolkit online documents, refer 
  5141.  to the How to Use This Book section. 
  5142.  
  5143.  
  5144. ΓòÉΓòÉΓòÉ 7.5.1.2. ALP Programming Guide and Reference ΓòÉΓòÉΓòÉ
  5145.  
  5146. This book describes how to install and run the ALP assembler. It provides a 
  5147. complete description of the following: 
  5148.  
  5149.      Installing ALP 
  5150.      Using ALP 
  5151.      Language Reference 
  5152.      Processor Reference 
  5153.      Assembler Messages 
  5154.      Return Codes 
  5155.  
  5156.  
  5157. ΓòÉΓòÉΓòÉ 7.5.1.3. Bidirectional Language Programming Guide ΓòÉΓòÉΓòÉ
  5158.  
  5159. This book provides information about the interface (API) for the Arabic and 
  5160. Hebrew languages to help programmers create Arabic or Hebrew applications for 
  5161. this environment. 
  5162.  
  5163. The Bidirectional support in PM is provided in the Arabic and Hebrew language 
  5164. versions of the OS/2 operating system. The support is active/configured when 
  5165. the COUNTRY selection during OS/2 installation is Arabic or Hebrew in these 
  5166. versions. 
  5167.  
  5168.  
  5169. ΓòÉΓòÉΓòÉ 7.5.1.4. C Library Reference ΓòÉΓòÉΓòÉ
  5170.  
  5171. This book describes the C library functions provided as part of OS/2 Warp. 
  5172.  
  5173.  
  5174. ΓòÉΓòÉΓòÉ 7.5.1.5. Control Program Programming Guide and Reference ΓòÉΓòÉΓòÉ
  5175.  
  5176. This book provides the C-language syntax for each of the base operating-system 
  5177. application programming interfaces (APIs), including input and output 
  5178. parameters, data structures, data types, return codes, and example codes. 
  5179. Guidance information is also provided to assist you in developing applications 
  5180. using these items. API functions (indicated by the prefix "Dos") are presented 
  5181. by component, such as Error Management, Exception Management, and File System. 
  5182. The API functions, within each of the components to which they apply, are 
  5183. listed in alphabetic order. API functions also are available from a single 
  5184. alphabetic list. 
  5185.  
  5186.  
  5187. ΓòÉΓòÉΓòÉ 7.5.1.6. DMI Programmer's Guide ΓòÉΓòÉΓòÉ
  5188.  
  5189. This book is designed as a programmer's guide for the System Management Agent, 
  5190. which provides access to system components that have been defined according to 
  5191. the Desktop Management Interface (DMI) standard.  These components can be 
  5192. hardware or software in the system that have been defined in the Management 
  5193. Information Format (MIF).  Although the DMI itself is protocol-independent, the 
  5194. System Management Agent can manage any DMI-enabled components in the system and 
  5195. translate the MIF information into SNMP management information bases (MIBs). 
  5196.  
  5197.  
  5198. ΓòÉΓòÉΓòÉ 7.5.1.7. DPI Programmer's Guide ΓòÉΓòÉΓòÉ
  5199.  
  5200. This book is designed as a programmer's guide for the System Management Agent, 
  5201. which provides the Simple Network Management Protocol (SNMP) distributed 
  5202. protocol interface (DPI).  The SNMP DPI permits users to dynamically add, 
  5203. delete, or replace management variables in the local Management Information 
  5204. Base (MIB) without requiring you to recompile the SNMP agent. 
  5205.  
  5206.  
  5207. ΓòÉΓòÉΓòÉ 7.5.1.8. GPI Guide and Reference ΓòÉΓòÉΓòÉ
  5208.  
  5209. This book describes the concepts associated with graphical output-- 
  5210. presentation spaces, device contexts, graphic primitives, fonts--and how to 
  5211. prepare graphical output for display and printing.  It provides the C-language 
  5212. syntax for all the graphical programming interface (GPI), including input and 
  5213. output parameters, data structures, data types, return codes, and example 
  5214. codes. Guidance information is also provided to assist you in developing 
  5215. applications using these items. GPI functions (indicated by the prefix "Gpi") 
  5216. are listed in alphabetic order. 
  5217.  
  5218.  
  5219. ΓòÉΓòÉΓòÉ 7.5.1.9. IPF Programming Guide and Reference ΓòÉΓòÉΓòÉ
  5220.  
  5221. This book describes the concepts--help windows, hypertext linking, author- 
  5222. controlled viewports, dynamic data formatting--and the functions used for 
  5223. implementing help in OS/2 applications. It describes how to create online help 
  5224. and information. It also contains an alphabetic list of IPF tags, symbols, and 
  5225. control words. The IPFC error messages, window functions, dynamic data 
  5226. formatting functions, and help manager messages and functions are included. 
  5227.  
  5228.  
  5229. ΓòÉΓòÉΓòÉ 7.5.1.10. IBM OS/2 Server Family Programming Reference ΓòÉΓòÉΓòÉ
  5230.  
  5231. This reference provides a description of the application programming interfaces 
  5232. (APIs) provided by the IBM Operating System/2 for OS/2 Warp Servers, LAN 
  5233. Servers, and the Directory and Security Server (DSS). These functions provide 
  5234. the functional interface for server and client application development. The 
  5235. OS/2 operating system referred to in this book is OS/2 Versions 2.1 through 
  5236. OS/2 Warp 4 (with the applicable CSDs and ServicePaks applied). 
  5237.  
  5238. This book also provides the OS/2 Warp LAN Requester API. These functions are 
  5239. 32-bit and are generally consistent with the Net32xxx and Dos32xxx LAN 
  5240. functions that are included with LAN Server 4.0. DOS refers to DOS versions 
  5241. 3.3, 5.0, 6.x, or 7.0. 
  5242.  
  5243. This book is written as a reference for the application or system programmer 
  5244. who is developing Directory and Security Server (DSS) software applications or 
  5245. OS/2 LAN Server software for a LAN Server, LAN Requester, OS/2 Warp Connect LAN 
  5246. Requester (client only), or DOS LAN Services (DLS) workstation. Information in 
  5247. this book applies to the following servers and clients: 
  5248.  
  5249.      LAN Server 3.0 
  5250.      LAN Server 4.0 
  5251.      OS/2 Warp Server 
  5252.      OS/2 Warp Connect 
  5253.      Directory and Security Server 
  5254.  
  5255.  This book includes DLS programming information that is not supported by 
  5256.  Directory and Security Server. 
  5257.  
  5258.  The reader should be familiar with programming the OS/2 base operating system 
  5259.  or an equivalent multitasking operating system and should understand the C 
  5260.  programming language. 
  5261.  
  5262.  
  5263. ΓòÉΓòÉΓòÉ 7.5.1.11. Multimedia Application Programming Guide ΓòÉΓòÉΓòÉ
  5264.  
  5265. This book describes the concepts associated with managing audio and video data 
  5266. and hardware using an extendable architecture that includes logical media 
  5267. devices (amplifier-mixer, waveform audio, MIDI sequencer, CD-audio, CD-XA, 
  5268. digital video, and videodisc) and I/O procedures for supporting various file 
  5269. formats. 
  5270.  
  5271.  
  5272. ΓòÉΓòÉΓòÉ 7.5.1.12. Multimedia Programming Reference ΓòÉΓòÉΓòÉ
  5273.  
  5274. This book describes the media control interface, PM graphic push buttons, 
  5275. secondary windows functions, multimedia I/O services, direct interface video 
  5276. extensions (DIVE), and subsystem services for synchronization and streaming. 
  5277.  
  5278.  
  5279. ΓòÉΓòÉΓòÉ 7.5.1.13. Multimedia Subsystem Programming Guide ΓòÉΓòÉΓòÉ
  5280.  
  5281. This book describes the subsystem components--media control driver, stream 
  5282. handler, and I/O procedure--that support a multimedia device. 
  5283.  
  5284.  
  5285. ΓòÉΓòÉΓòÉ 7.5.1.14. Object REXX Programming Guide for OS/2 ΓòÉΓòÉΓòÉ
  5286.  
  5287. The Object REXX Programming Guide for OS/2 describes the Object-based 
  5288. REstructured eXtended eXecutor, or Object REXX programming language. (When not 
  5289. comparing it to its traditional predecessor, it is just referred to as REXX.) 
  5290. REXX is an integral part of the OS/2 operating system. 
  5291.  
  5292. This information is aimed at developers familiar with OS/2 who want to use REXX 
  5293. to do object-oriented programming--or some mix of traditional and 
  5294. object-oriented programming--with the shortest learning curve possible. 
  5295.  
  5296. This information assumes you are already familiar with the techniques of 
  5297. traditional structured programming and uses them as a springboard for 
  5298. explaining REXX and, in particular, Object REXX. This "no frills" approach is 
  5299. designed to help experienced programmers get involved quickly with the REXX 
  5300. language, exploit its virtues, and become productive fast. 
  5301.  
  5302.  
  5303. ΓòÉΓòÉΓòÉ 7.5.1.15. Open32 Programming Guide and Reference ΓòÉΓòÉΓòÉ
  5304.  
  5305. The Open32 Programming Guide and Reference provides information on the 
  5306. following topics: 
  5307.  
  5308.      What Open32 is and how it can help you to either: 
  5309.  
  5310.         -  Migrate Windows code to OS/2 code 
  5311.         -  Write common source code for OS/2 and Windows 
  5312.  
  5313.      How to use the SMART tool to analyze Windows code and see how much effort 
  5314.       is involved to migrate it to OS/2 code 
  5315.  
  5316.      Differences in behavior between some Open32 functions and their Windows 
  5317.       counterparts 
  5318.  
  5319.      The functions supported by Open32 
  5320.  
  5321.  As an enhancement for Open32, the OS/2 Resource Compiler (RC) now supports 
  5322.  string IDs for resources in addition to numbers. You can use either SMART or 
  5323.  the Resource Compiler to convert resources. If you use the Resource Compiler, 
  5324.  you do not need to include the hhh file with your code. OS/2 supports string 
  5325.  IDs that contain quotation marks. See the discussion of the RESOURCE statement 
  5326.  in the Tools Reference for more information. 
  5327.  
  5328.  
  5329. ΓòÉΓòÉΓòÉ 7.5.1.16. OpenGL Programming Reference ΓòÉΓòÉΓòÉ
  5330.  
  5331. This book provides an overview of OpenGL function and describes in detail the 
  5332. window and input interface that integrates OpenGL with the Presentation 
  5333. Manager. Application developers can use this interface to: 
  5334.  
  5335.      Create and prepare an OpenGL context for rendering 
  5336.      Swap a window's front and back buffers 
  5337.      Select a color palette for a color index context 
  5338.      Integrate GPI and OpenGL rendering and fonts 
  5339.  
  5340.  The interface provides much the same functionality as the OpenGL window 
  5341.  interfaces for X Windows and Microsoft systems. 
  5342.  
  5343.  
  5344. ΓòÉΓòÉΓòÉ 7.5.1.17. OS/2 Debugging Handbook ΓòÉΓòÉΓòÉ
  5345.  
  5346. This book explains problem debugging in an OS/2 environment.  The book is 
  5347. written for service personnel, system programmers, and software developers. It 
  5348. provides information about the internal workings of the OS/2 operating system 
  5349. and describes the use of system debugging tools. 
  5350.  
  5351.  
  5352. ΓòÉΓòÉΓòÉ 7.5.1.18. OS/2 Programming Guide and Reference Addendum for OS/2 Warp Server for e-business ΓòÉΓòÉΓòÉ
  5353.  
  5354. This book provides information about APIs that are new to OS/2 Warp Server for 
  5355. e-business.  This information includes syntax, input and output parameters, 
  5356. data structures, data types, return codes, and sample code. 
  5357.  
  5358.  
  5359. ΓòÉΓòÉΓòÉ 7.5.1.19. Presentation Manager Programming Guide and Reference ΓòÉΓòÉΓòÉ
  5360.  
  5361. This book provides the C-language syntax for the base operating-system 
  5362. application programming interface (API), including input and output parameters, 
  5363. data structures, data types, return codes, and example codes. API function 
  5364. prefixes include Drg (dragdrop), Ddf (dynamic data format), Prf (profile), Spl 
  5365. (spooler), and Win (window). Also included are application hooks and PM 
  5366. messages. 
  5367.  
  5368.  
  5369. ΓòÉΓòÉΓòÉ 7.5.1.20. Problem Determination Guide and Reference ΓòÉΓòÉΓòÉ
  5370.  
  5371. This book provides programmers with guide and reference information for 
  5372. collecting and managing problem determination data. 
  5373.  
  5374. This book first provides conceptual and introductory information about OS/2 
  5375. Warp's First Failure Support Technology (FFST). This sophisticated and powerful 
  5376. tool requires thoughtful planning and code instrumentation. These topics 
  5377. present planning, setup, and examples that are used for collecting and managing 
  5378. problem determination data. 
  5379.  
  5380. Separate sections are devoted to understanding the aids that are provided for 
  5381. tracking, collecting, storing, and formatting problem determination data, such 
  5382. as traces, dumps, and error logs. 
  5383.  
  5384. After reading this book you should understand the benefits of FFST and know how 
  5385. to instrument your code. This understanding enables you to take advantage of 
  5386. the technology and tools that are associated with problem determination data. 
  5387. You should also know how to use the API, trace, error logging, and dump 
  5388. functions. These functions retrieve, format, and analyze problem determination 
  5389. data. 
  5390.  
  5391. This book assumes that you have the OS/2 Toolkit installed and you are 
  5392. developing application programs. 
  5393.  
  5394.  
  5395. ΓòÉΓòÉΓòÉ 7.5.1.21. RXSTRING.DOC ΓòÉΓòÉΓòÉ
  5396.  
  5397. RXSTRING.DOC is an ASCII text file that documents the utility library that is 
  5398. included with the OS/2 Warp Toolkit. The utilities enable C programmers to 
  5399. effectively handle REXX string variables. 
  5400.  
  5401.  
  5402. ΓòÉΓòÉΓòÉ 7.5.1.22. SOM Programmers Reference ΓòÉΓòÉΓòÉ
  5403.  
  5404. This book is a complete reference for each of the classes and methods used for 
  5405. the object-oriented programming environment. Also included are System Object 
  5406. Model (SOM) C-language and C++ bindings, the Object Interface Definition 
  5407. Language syntax, and the SOM compiler command syntax. 
  5408.  
  5409.  
  5410. ΓòÉΓòÉΓòÉ 7.5.1.23. SOM User's Guide ΓòÉΓòÉΓòÉ
  5411.  
  5412. This book explains how programmers using C, C++, and other languages can: 
  5413.  
  5414.      Implement class libraries that exploit the SOM library-packaging 
  5415.       technology 
  5416.  
  5417.      Develop client programs that use class libraries that were built using 
  5418.       SOM 
  5419.  
  5420.      Develop applications that use the frameworks supplied with the SOMobjects 
  5421.       Developer Toolkit, class libraries that facilitate development of 
  5422.       object-oriented applications. 
  5423.  
  5424.  
  5425. ΓòÉΓòÉΓòÉ 7.5.1.24. TCP/IP Programming Reference ΓòÉΓòÉΓòÉ
  5426.  
  5427. This book describes the routines for application programming in the TCP/IP for 
  5428. OS/2 Warp environment on a workstation. 
  5429.  
  5430.  
  5431. ΓòÉΓòÉΓòÉ 7.5.1.25. Tools Reference ΓòÉΓòÉΓòÉ
  5432.  
  5433. This book describes the tools that are included in the IBM Developer's Toolkit 
  5434. for OS/2 Warp. 
  5435.  
  5436.  
  5437. ΓòÉΓòÉΓòÉ 7.5.1.26. Unicode Programming Reference ΓòÉΓòÉΓòÉ
  5438.  
  5439. The Unicode Programming Reference documents the Universal Language Support 
  5440. (ULS) and Unicode conversion functions. OS/2 Warp Version 4 or later provides a 
  5441. dynamically linked C-language run-time library that supports multithreaded and 
  5442. Unicode-enabled programs. For information on this library, see the C Library 
  5443. Reference. 
  5444.  
  5445.  
  5446. ΓòÉΓòÉΓòÉ 7.5.1.27. Windows Sockets ΓòÉΓòÉΓòÉ
  5447.  
  5448. The Windows Sockets specification defines a network programming interface for 
  5449. Microsoft Windows, which is based on the "socket" paradigm popularized in the 
  5450. Berkeley Software Distribution (BSD) from the University of California at 
  5451. Berkeley.  It encompasses both familiar Berkeley socket style routines and a 
  5452. set of Windows-specific extensions designed to help the programmer to take 
  5453. advantage of the message-driven nature of Windows. 
  5454.  
  5455. The Windows Sockets Specification is intended to provide a single API to which 
  5456. application developers can program and multiple network software vendors can 
  5457. conform.  Furthermore, in the context of a particular version of Microsoft 
  5458. Windows, it defines a binary interface (ABI) such that an application written 
  5459. to the Windows Sockets API can work with a conformant protocol implementation 
  5460. from any network software vendor.  This specification thus defines the library 
  5461. calls and associated semantics to which an application developer can program 
  5462. and which a network software vendor can implement. 
  5463.  
  5464. Network software which conforms to this Windows Sockets specification will be 
  5465. considered "Windows Sockets Compliant."  Suppliers of interfaces that are 
  5466. "Windows Sockets Compliant" are referred to as "Windows Sockets Suppliers." To 
  5467. be Windows Sockets Compliant, a vendor must implement 100% of this Windows 
  5468. Sockets specification. 
  5469.  
  5470. Applications that are capable of operating with any "Windows Sockets Compliant" 
  5471. protocol implementation are considered as having a "Windows Sockets Interface" 
  5472. and are referred to as "Windows Sockets Applications." 
  5473.  
  5474. This version of the Windows Sockets specification defines and documents the use 
  5475. of the API in conjunction with the Internet Protocol Suite (IPS, generally 
  5476. referred to as TCP/IP).  Specifically, all Windows Sockets implementations 
  5477. support both stream (TCP) and datagram (UDP) sockets. 
  5478.  
  5479. While the use of this API with alternative protocol stacks is not precluded 
  5480. (and is expected to be the subject of future revisions of the specification), 
  5481. such usage is beyond the scope of this version of the specification. 
  5482.  
  5483.  
  5484. ΓòÉΓòÉΓòÉ 7.5.1.28. Workplace Shell Programming Guide ΓòÉΓòÉΓòÉ
  5485.  
  5486. This book describes the concepts associated with object-oriented programming 
  5487. for the OS/2 operating system--SOM, Workplace Shell classes and methods--and 
  5488. how to create object-oriented applications for the OS/2 Desktop. 
  5489.  
  5490.  
  5491. ΓòÉΓòÉΓòÉ 7.5.1.29. Workplace Shell Programming Reference ΓòÉΓòÉΓòÉ
  5492.  
  5493. This book provides the detailed descriptions of the Workplace Shell 
  5494. object-oriented programming interface. 
  5495.  
  5496.  
  5497. ΓòÉΓòÉΓòÉ 7.5.2. VoiceType Developer's Toolkit Documentation ΓòÉΓòÉΓòÉ
  5498.  
  5499. Online documentation for the VoiceType Developer's Toolkit is located in the 
  5500. \TOOLKIT\SPEECH\BOOK subdirectory. You can also access the information from the 
  5501. Desktop by opening the Toolkit folder, and then the VoiceType Developer's 
  5502. Toolkit folder. 
  5503.  
  5504. Note:  The VoiceType Developer's Toolkit online documentation is in HTML 
  5505.        format.  You need a Web browser to view it. 
  5506.  
  5507.  The following information is provided: 
  5508.  
  5509.      Application Programming Interface (API) Reference 
  5510.      Grammar Guide 
  5511.  
  5512.  
  5513. ΓòÉΓòÉΓòÉ 7.5.2.1. API Reference ΓòÉΓòÉΓòÉ
  5514.  
  5515. This reference provides a description of the Speech Manager (Sm) application 
  5516. programming interface. Two types of functions are covered--function calls to 
  5517. the speech engine and data access functions, which are functions that retrieve 
  5518. data from reply messages. 
  5519.  
  5520.  
  5521. ΓòÉΓòÉΓòÉ 7.5.2.2. Grammar Guide ΓòÉΓòÉΓòÉ
  5522.  
  5523. Grammars can be used by speech-enabled applications to specify what phrases to 
  5524. accept. Grammars can also be used to enhance Voice Manager navigation of 
  5525. applications that are not speech-enabled. The Grammar Guide describes the basic 
  5526. steps for writing an application grammar. It also contains information that 
  5527. explains how to use the grammar utilities that are provided with the VoiceType 
  5528. Developer's Toolkit. 
  5529.  
  5530.  
  5531. ΓòÉΓòÉΓòÉ 8. Programming Considerations ΓòÉΓòÉΓòÉ
  5532.  
  5533. Programming considerations apply for the following areas of the OS/2 Warp 
  5534. operating system: 
  5535.  
  5536.      General Considerations 
  5537.      Presentation Manager 
  5538.      SOM 
  5539.      IBM VisualAge C++ for OS/2 Compiler 
  5540.      Workplace Shell 
  5541.  
  5542.  
  5543. ΓòÉΓòÉΓòÉ 8.1. General Considerations ΓòÉΓòÉΓòÉ
  5544.  
  5545. Included in this section are important items that can affect your future 
  5546. development efforts when using the IBM Developer's Toolkit for OS/2 Warp. 
  5547.  
  5548.      Compiling with IBM C/2 
  5549.      Compiling with IBM VisualAge C++ for OS/2 
  5550.      Installing IBM VisualAge C++ for OS/2 
  5551.      Known Limitations for the Container Part 
  5552.      Known Limitations for DIVE 
  5553.  
  5554.  
  5555. ΓòÉΓòÉΓòÉ 8.1.1. Compiling with IBM C/2 ΓòÉΓòÉΓòÉ
  5556.  
  5557. The IBM Developer's Toolkit for OS/2 Warp Version 4 and later versions are not 
  5558. intended to be used with the IBM C/2, Version 1.1 compiler. If you choose to 
  5559. use that compiler, you should use version 1.3 of the Toolkit. 
  5560.  
  5561. The OS/2 Warp Toolkit is intended to be used with the IBM VisualAge C++ 
  5562. compiler. 
  5563.  
  5564.  
  5565. ΓòÉΓòÉΓòÉ 8.1.2. Compiling with IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
  5566.  
  5567. The latest version of the C Set ++ compiler (now called VisualAge C++) has been 
  5568. released. VisualAge C++ includes its own version of the OS/2 Warp Toolkit, 
  5569. which includes updated sample makefiles. Changes to the sample makefiles relate 
  5570. to the new linker (ILINK) and to the new library (CPPOM30.LIB). 
  5571.  
  5572. With this version of the OS/2 Warp Toolkit, the same sample makefile changes 
  5573. have been made so that you can use VisualAge C++. 
  5574.  
  5575. You can compile the samples included with the OS/2 Warp Toolkit with C Set ++ 
  5576. (using LINK386) by changing any reference to CPPOM30.LIB to: 
  5577.  
  5578. DDE4MBS.LIB
  5579.  
  5580. and changing any reference to ILINK to: 
  5581.  
  5582. LINK386
  5583.  
  5584. Note:  The /nofree option must be removed from the LINK386 statement. 
  5585.  
  5586.  
  5587. ΓòÉΓòÉΓòÉ 8.1.3. Installing IBM VisualAge C++ for OS/2 ΓòÉΓòÉΓòÉ
  5588.  
  5589. Installing your compiler first and the OS/2 Warp Toolkit last prevents 
  5590. unexpected results due to environment variable changes (automatic updates to 
  5591. CONFIG.SYS). 
  5592.  
  5593. To avoid a downlevel SOM Runtime installed by the VisualAge C++ 3.0 compiler, 
  5594. follow these steps for installation: 
  5595.  
  5596.    1. Start the installation program for VisualAge C++ 3.0. 
  5597.  
  5598.    2. Deselect the OS/2 Warp Toolkit entries in the installation screen and 
  5599.       proceed with the installation. 
  5600.  
  5601.    3. After completing the installation of VisualAge C++ but before restarting 
  5602.       the system, edit CONFIG.SYS and modify the LIBPATH statement by moving 
  5603.       x:\ IBMCPP\DLL after y:\OS2\DLL, where x is the drive where the VisualAge 
  5604.       C++ compiler is installed and y is the drive where the OS/2 Warp 
  5605.       operating system files are installed.  This prevents the SOM Runtime 
  5606.       installed by VisualAge C++ from overriding the SOM Runtime shipped with 
  5607.       OS/2 Warp Version 4 or later. 
  5608.  
  5609.    4. Save the modified CONFIG.SYS and restart your system. 
  5610.  
  5611.    5. Install the OS/2 Toolkit and restart your system. 
  5612.  
  5613.  
  5614. ΓòÉΓòÉΓòÉ 8.1.4. Known Limitations for the Container Part ΓòÉΓòÉΓòÉ
  5615.  
  5616. The Container part has the following known limitations. Note that the behavior 
  5617. described below will be exhibited by all samples that subclass from the 
  5618. Container part. 
  5619.  
  5620.      A SYS3175 error occurs when you select Open As->Details from the 
  5621.       Container part's View menu.  This error will close the document. 
  5622.  
  5623.      A SYS3175 error occurs when saving a document containing a selected 
  5624.       Container part inside a root Container part.  It will occur if the 
  5625.       selected part subclasses from the Container part.  This error will not 
  5626.       occur if the selected part, for example, is the Cookbook part. 
  5627.  
  5628.      The Container part's Show As menu selection from the View menu does not 
  5629.       work correctly. This selection will incorrectly change the view type of 
  5630.       selected parts, when it should only change the activated part's view 
  5631.       type. The correct way to change the view type of selected parts would be 
  5632.       to select Show selection as from the Edit menu. 
  5633.  
  5634.      The Move selection from the Edit menu is incorrectly enabled for an 
  5635.       activated part. The Move selection, like all Edit menu selections, are 
  5636.       for selected parts only. 
  5637.  
  5638.      A part that subclasses from the Container part may not have its intrinsic 
  5639.       content clipped correctly to the embedded parts.  The Container part 
  5640.       correctly handles the clipping of its embedded parts, but there is no way 
  5641.       for a part that subclasses from the Container part to tell the Container 
  5642.       part how to clip the embedded parts to its own content. Generally, the 
  5643.       subclass part's intrinsic content will write over the embedded parts. 
  5644.  
  5645.  
  5646. ΓòÉΓòÉΓòÉ 8.1.5. Known Limitations for DIVE ΓòÉΓòÉΓòÉ
  5647.  
  5648. DIVE will not run in direct mode on some systems if the video card requires 
  5649. bank switching. To determine if your video card requires bank switching, select 
  5650. Query Caps from the Options menu of the DIVE sample. If the Screen access 
  5651. requires bank switch field is set to YES, setting a lower Desktop resolution in 
  5652. the System Setup might fix this. 
  5653.  
  5654. DIVE might not work on some systems when the Desktop is set to 16 million 
  5655. colors. If your system is set to 16 million colors and DIVE does not work 
  5656. properly, try setting the Desktop to fewer colors in the System Setup. 
  5657.  
  5658.  
  5659. ΓòÉΓòÉΓòÉ 8.1.6. Replacing DLGEDIT ΓòÉΓòÉΓòÉ
  5660.  
  5661. IBM supports the version of the Dialog Editor (DLGEDIT) in this release of the 
  5662. OS/2 Warp Toolkit. 
  5663.  
  5664.  
  5665. ΓòÉΓòÉΓòÉ 8.2. Presentation Manager Considerations ΓòÉΓòÉΓòÉ
  5666.  
  5667. Making modifications to Microsoft Windows programs to enable dynamic data 
  5668. exchange (DDE) communications with PM programs helps facilitate a gradual 
  5669. migration of applications to PM. Not all data formats are automatically 
  5670. converted when using DDE between Windows programs and PM programs (DDE set 
  5671. public). 
  5672.  
  5673. The following formats are converted automatically by the OS/2 operating system: 
  5674.  
  5675.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5676.  Γöé PM Application       Γöé Windows Application  Γöé
  5677.  Γöé Data Format          Γöé Interpretation       Γöé
  5678.  ΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöé
  5679.  Γöé PM bitmap            Γöé Windows DIB          Γöé
  5680.  Γöé PM private           Γöé Windows private      Γöé
  5681.  Γöé Text                 Γöé Text (codepage 819)  Γöé
  5682.  Γöé---------------------------------------------Γöé
  5683.  Γöé Windows Application  Γöé PM Application       Γöé
  5684.  Γöé Data Format          Γöé Interpretation       Γöé
  5685.  Γö£ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöéΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓöñ
  5686.  Γöé Text (codepage 819)  Γöé Text                 Γöé
  5687.  Γöé Windows DIB          Γöé PM Bitmap            Γöé
  5688.  Γöé Windows private      Γöé PM Private           Γöé
  5689.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5690.  
  5691. Note:  Code page translation (Windows 819 to/from current PM code page) is 
  5692.        performed for topic name in all cases. 
  5693.  
  5694. When data conversion is not automatically performed, programs can still 
  5695. communicate using DDE when the two programs perform the data conversion and 
  5696. pass private data formats. 
  5697.  
  5698.  
  5699. ΓòÉΓòÉΓòÉ 8.3. SOM Considerations ΓòÉΓòÉΓòÉ
  5700.  
  5701. This version of the OS/2 Warp Toolkit contains a subset of the SOMobjects 
  5702. Developer Toolkit. The following SOM programming considerations are briefly 
  5703. described: 
  5704.  
  5705.      Distributed SOM 
  5706.      SNGLICLS.HH 
  5707.      SOM 1.0 OIDL 
  5708.      SOM Bindings 
  5709.      SOM Coding Styles 
  5710.      SOM Compiler 
  5711.      SOM DLLs 
  5712.  
  5713.  
  5714. ΓòÉΓòÉΓòÉ 8.3.1. Distributed SOM (DSOM) ΓòÉΓòÉΓòÉ
  5715.  
  5716. New features, known limitations, and restrictions pertain to Distributed SOM 
  5717. (DSOM).  They are briefly described as follows: 
  5718.  
  5719.      DSOM now provides a PM version of the REGIMPL tool for registering 
  5720.       servers in the implementation repository. It is called PREGIMPL and is 
  5721.       similar in functionality to REGIMPL. To invoke the tool, type PREGIMPL on 
  5722.       a command line. Remember to select File Save before exiting to save any 
  5723.       changes you make. 
  5724.  
  5725.      You are now able to control the number of request threads created per 
  5726.       server. The environment variable SOMDNUMTHREADS is used to indicate the 
  5727.       maximum size of the thread pool. If this environment variable is not set, 
  5728.       a separate thread will be created for each request. 
  5729.  
  5730.      The OUT_LIST_MEMORY, IN_COPY_VALUE, and DEPENDENT_LIST flags, used with 
  5731.       the dynamic invocation interface, are not supported. 
  5732.  
  5733.      Concurrent updates to the implementation repository are currently not 
  5734.       properly serialized and can conflict. 
  5735.  
  5736.      The is_nil method of SOMDObject has been changed from a true method to a 
  5737.       procedure so that is_nil can be safely invoked on a NULL object pointer. 
  5738.       As a result, the syntax for invoking is_nil from C++ client programs has 
  5739.       changed. The new syntax is: 
  5740.  
  5741.                 obj->is_nil(obj,env);
  5742.  
  5743.       Rather than: 
  5744.  
  5745.                 obj->is_nil(env);
  5746.  
  5747.       where: 
  5748.  
  5749.       obj        Is an object pointer of type SOMDObject. 
  5750.       env        Is of type Environment. 
  5751.  
  5752.  
  5753. ΓòÉΓòÉΓòÉ 8.3.2. SNGLICLS.HH ΓòÉΓòÉΓòÉ
  5754.  
  5755. The Direct-to-SOM version of the SNGLICLS header file cannot be emitted with 
  5756. the version of the SOM Compiler included with this Toolkit.  Therefore, this 
  5757. file (SNGLICLS.HH) is provided as part of the SOM Direct-to-SOM headers. 
  5758.  
  5759.  
  5760. ΓòÉΓòÉΓòÉ 8.3.3. SOM 1.0 OIDL Users ΓòÉΓòÉΓòÉ
  5761.  
  5762. If you need to recompile an OIDL class that overrides somDumpSelf or 
  5763. somDumpSelfInt, change the data type of the level parameter in the function 
  5764. definition in your C source program from INT to LONG.  For example, if your 
  5765. original class source program has a somDumpSelfInt override procedure similar 
  5766. to: 
  5767.  
  5768.   SOM_Scope void SOMLINK somDumpSelfInt(
  5769.        <className> *somSelf, INT level)
  5770.   {
  5771.     ...
  5772.   }
  5773.  
  5774. Change it to read: 
  5775.  
  5776.   SOM_Scope void SOMLINK somDumpSelfInt(
  5777.        <className> *somSelf, LONG level)
  5778.   {
  5779.    ...
  5780.   }
  5781.  
  5782. Because both INT and LONG data types require 4 bytes on OS/2, this change does 
  5783. not affect the binary interface of your class. 
  5784.  
  5785.  
  5786. ΓòÉΓòÉΓòÉ 8.3.4. SOM Bindings ΓòÉΓòÉΓòÉ
  5787.  
  5788. The XH and H files included with this OS/2 Warp Toolkit work only with the IDL 
  5789. files included with this Toolkit. You will need to generate new SOM bindings if 
  5790. you install a new version of SOM. This means that the XH and H files will need 
  5791. to be re-emitted if new versions of the IDL files are made available. There are 
  5792. two steps that you need to take. 
  5793.  
  5794. If you install version 'Y' of SOM on top of version 'X', you will need to 
  5795. generate SOM bindings for version 'Y'. The version 'X' SOM bindings are not 
  5796. guaranteed to be compatible with version 'Y'. 
  5797.  
  5798.      Use the SOMSTARS.CMD file to generate the SOMSTARS version of the 
  5799.       bindings. 
  5800.  
  5801.      Use SOMCORBA.CMD to generate the SOMCORBA version of the bindings. This 
  5802.       upgrades your SOM bindings. 
  5803.  
  5804.  The command file WPIDL2XH.CMD is provided to upgrade Workplace Shell bindings 
  5805.  for developers who will upgrade their SOMobjects Developer Toolkit in the 
  5806.  future. This command file emits the .XH header files from the Workplace Shell 
  5807.  .IDL files. The file should be invoked upon each of the .IDL files from the 
  5808.  OS/2 Warp Toolkit to regenerate the headers for C++. This is only necessary 
  5809.  when you upgrade to a new level of the SOMobjects Developer Toolkit. Invoking 
  5810.  the SOM compiler's .XH emitter on the Workplace Shell .IDL files do not emit 
  5811.  .XH files for you, because the Workplace Shell classes currently only maintain 
  5812.  passthru sections for .H files for C. 
  5813.  
  5814.  
  5815. ΓòÉΓòÉΓòÉ 8.3.5. SOM Coding Styles ΓòÉΓòÉΓòÉ
  5816.  
  5817. There are two possible forms of C bindings for SOM programming: 
  5818.  
  5819.  SOMCORBA       The strict CORBA-compliant form in which pointer references 
  5820.                 ('*'s) are NOT exposed in object references. 
  5821.  
  5822.  SOMSTARS       The OIDL-compatible C++ form in which pointer references ('*'s) 
  5823.                 are visible in object references. 
  5824.  
  5825.  The SOMSTARS form is more appropriate if you plan to move your class 
  5826.  implementations from C to C++ at some future point. This choice will determine 
  5827.  how object references will appear in all of your C programs. For example, to 
  5828.  declare a reference to an instance of class Foo, you would code either: 
  5829.  
  5830.     Foo afoo;   /* Strict CORBA compliant form          */
  5831.     or
  5832.     Foo *afoo; /* C++ migration or OIDL-compatible form */
  5833.  
  5834.  If you later decide to switch from one SOM coding style to the other, you will 
  5835.  have to convert any C code that you have already written in one style to the 
  5836.  other style. 
  5837.  
  5838.  The Workplace Shell uses the SOMSTARS version of the SOM header files. 
  5839.  Therefore, the OS/2 Warp Toolkit installs the SOMSTARS version of the header 
  5840.  files. 
  5841.  
  5842.  The Workplace Shell interface definition language (IDL) files (WP*.IDL) are 
  5843.  the counterparts for the documented Workplace Shell classes' SC files provided 
  5844.  with the OS/2 2.1 Toolkit. The WP*.H and WP*.XH files emitted from the 
  5845.  Workplace Shell's IDL files by the SOM compiler are also provided. 
  5846.  
  5847.  The OS/2 makefiles for the Workplace Shell OS/2 Warp Toolkit samples are 
  5848.  written assuming the SOMSTARS style of coding. The C samples provided with the 
  5849.  SOMobjects Developer Toolkit use the SOMCORBA style of coding (these samples 
  5850.  are not part of the IBM Developer's Toolkit for OS/2 Warp). 
  5851.  
  5852.  
  5853. ΓòÉΓòÉΓòÉ 8.3.6. SOM Compiler ΓòÉΓòÉΓòÉ
  5854.  
  5855. New features, known limitations, and restrictions pertain to the SOM compiler. 
  5856. There are briefly described as follows: 
  5857.  
  5858.      Mutually recursive IDL struct and union are not currently supported. The 
  5859.       following is an example of unsupported mutual recursion: 
  5860.  
  5861.               struct X;
  5862.               struct Y
  5863.               {
  5864.                 sequence<X> indirectSelf;
  5865.               };
  5866.               struct X
  5867.               {
  5868.                 sequence<Y> indirectSelf;
  5869.               };
  5870.  
  5871.      The C bindings do not permit the use of multiple methods with the same 
  5872.       name that also take an argument of data type VA_LIST within the same 
  5873.       module. For example, the following legal IDL will result in incorrect C 
  5874.       usage bindings: 
  5875.  
  5876.               module X
  5877.               {
  5878.                 interface Y
  5879.                 {
  5880.                   void Foo (in LONG f, in VA_LIST ap);
  5881.                 };
  5882.                 interface Z
  5883.                 {
  5884.                   void Foo (in LONG f, in VA_LIST ap);
  5885.                 };
  5886.               };
  5887.  
  5888.      The SOM C++ language bindings are built assuming use of the VisualAge C++ 
  5889.       for OS/2 compiler, but other C++ compilers should be able to use these 
  5890.       bindings as well. For example, to use BCOS2 (the Borland C++ compiler for 
  5891.       OS/2), use -DSOMLINK=_syscall on the compile line, and make sure that the 
  5892.       SOMobjects' include directory is consulted before BCOS2/include (because 
  5893.       BCOS2/include contains older SOM.H include files). 
  5894.  
  5895.      If the SOM compiler is interrupted by the user (using Ctrl+C, for 
  5896.       example), it sometimes leaves a temporary file with a .CTN extension in 
  5897.       the temporary directory specified by the SMTMP environmental variable. 
  5898.       These temporary files should be removed periodically. 
  5899.  
  5900.      When direct references to SOMFOREIGN types are made in an IDL struct or 
  5901.       union, the C or C++ language bindings are generated incorrectly. To refer 
  5902.       to a SOMFOREIGN type (for example, "somId") in a struct  or union , it is 
  5903.       necessary to supply a secondary typedef for "somId." For example: 
  5904.  
  5905.               #include <somobj.idl>
  5906.               struct S1
  5907.               {
  5908.                 somId badId;    /* Generates incorrect */
  5909.               };                /* C/C++ bindings      */
  5910.               #include <somobj.idl>
  5911.               typedef somId somId2;
  5912.               struct S1
  5913.               {
  5914.                 somId2 badId;   /* OK                  */
  5915.               };
  5916.  
  5917.  
  5918. ΓòÉΓòÉΓòÉ 8.3.7. SOM Dynamic Link Libraries (DLLs) ΓòÉΓòÉΓòÉ
  5919.  
  5920. When SOMobjects 2.0 (not the version included with this OS/2 Warp Toolkit) is 
  5921. installed on OS/2 Warp Version 3, the LIBPATH, PATH, and DPATH environment 
  5922. variables in CONFIG.SYS are changed to place the SOMobjects directories before 
  5923. the operating system directories in the search order for DLLs, EXEs, and data 
  5924. files. This causes the Workplace Shell to encounter an unrecoverable error the 
  5925. next time the system is restarted because it requires the SOM DLLs that are 
  5926. contained in the \OS2\DLL subdirectory. 
  5927.  
  5928. In order to allow SOMobjects 2.0 Workstation applications to run successfully, 
  5929. you must edit CONFIG.SYS and change the LIBPATH, PATH, and DPATH statements 
  5930. before restarting the system. These statements must be changed to place the 
  5931. operating system directories before the SOMobjects directories. 
  5932.  
  5933. Note:  This only applies to SOMobjects Workstation applications, not Workgroup 
  5934.        applications. 
  5935.  
  5936.  The same problem will occur for any application that includes SOMobjects 2.0 
  5937.  DLLs if the application places its DLL directory first in the LIBPATH. Again, 
  5938.  the workaround is to assure that the \OS2\DLL subdirectory is before any other 
  5939.  directory that contains earlier versions of the SOM DLLs. Any changes made to 
  5940.  the PATH and DPATH environment variables by the application installation must 
  5941.  also be reversed. 
  5942.  
  5943.  
  5944. ΓòÉΓòÉΓòÉ 8.4. Workplace Shell Considerations ΓòÉΓòÉΓòÉ
  5945.  
  5946. When including an OBJECTID=<....> keyname=value pair in a setup string, you 
  5947. must specify it at the end of the setup string. 
  5948.  
  5949.  
  5950. ΓòÉΓòÉΓòÉ 9. Toolkit Support ΓòÉΓòÉΓòÉ
  5951.  
  5952. The OS/2 Developer's Toolkit provides programming tools, samples and 
  5953. information to support end-user development of OS/2 applications.  We will make 
  5954. every effort to respond to support requests, but the Toolkit is provided on an 
  5955. as-is basis, and there is no guarantee of formal support. 
  5956.  
  5957. Informal electronic support for the IBM Developer's Toolkit is provided through 
  5958. the Internet and the OS/2 BBS.  Internet users may report problems by sending 
  5959. mail to devcon@us.ibm.com.  Users may obtain informal support or exchange ideas 
  5960. or comments by accessing the DEVCON CFORUM on the OS/2 BBS under Talklink (a 
  5961. feature under the IBMLink Commercial Services).  For TalkLink access, U.S. 
  5962. customers can call 1-800-547-1283; other customers can contact their IBM 
  5963. Marketing Representatives. 
  5964.  
  5965.  
  5966. ΓòÉΓòÉΓòÉ 10. Notices ΓòÉΓòÉΓòÉ
  5967.  
  5968. (C) Copyright International Business Machines Corporation 1997, 1999. All 
  5969. rights reserved. 
  5970. Note to U.S. Government Users Restricted Rights --Use, duplication or 
  5971. disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 
  5972.  
  5973. This information was developed for products and services offered in the U.S.A. 
  5974. IBM may not offer the products, services, or features discussed in this 
  5975. document in other countries. Consult your local IBM representative for 
  5976. information on the products and services currently available in your area. Any 
  5977. reference to an IBM product, program, or service is not intended to state or 
  5978. imply that only that IBM product, program, or service may be used. Any 
  5979. functionally equivalent product, program, or service that does not infringe any 
  5980. IBM intellectual property right may be used instead. However, it is the user's 
  5981. responsibility to evaluate and verify the operation of any non-IBM product, 
  5982. program, or service. 
  5983.  
  5984. IBM may have patents or pending patent applications covering subject matter in 
  5985. this document. The furnishing of this document does not give you any license to 
  5986. these patents. You can send license inquiries, in writing, to: 
  5987.  
  5988. IBM Director of Licensing
  5989. IBM Corporation
  5990. North Castle Drive
  5991. Armonk, NY  10504-1785
  5992. U.S.A.
  5993.  
  5994. For license inquiries regarding double-byte (DBCS) information, contact the IBM 
  5995. Intellectual Property Department in your country or send inquiries, in writing, 
  5996. to: 
  5997.  
  5998. IBM World Trade Asia Corporation Licensing
  5999. 2-31 Roppongi 3-chome, Minato-ku
  6000. Tokyo 106, Japan
  6001.  
  6002. The following paragraph does not apply to the United Kingdom or any other 
  6003. country where such provisions are inconsistent with local law:  INTERNATIONAL 
  6004. BUSINESS MACHINES CORPORATION PROVIDES THIS information "AS IS" WITHOUT 
  6005. WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 
  6006. THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 
  6007. PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied 
  6008. warranties in certain transactions, therefore, this statement may not apply to 
  6009. you. 
  6010.  
  6011. This information could include technical inaccuracies or typographical errors. 
  6012. Changes are periodically made to the information herein; these changes will be 
  6013. incorporated in new editions of the information. IBM may make improvements 
  6014. and/or changes in the product(s) and/or the program(s) described in this 
  6015. information at any time without notice. 
  6016.  
  6017. Any references in this information to non-IBM Web sites are provided for 
  6018. convenience only and do not in any manner serve as an endorsement of those Web 
  6019. sites.  The materials at those Web sites are not part of the materials for this 
  6020. IBM product and use of those Web sites is at your own risk. 
  6021.  
  6022. IBM may use or distribute any of the information you supply in any way it 
  6023. believes appropriate without incurring any obligation to you. 
  6024.  
  6025. Licensees of this program who wish to have information about it for the purpose 
  6026. of enabling: (i) the exchange of information between independently created 
  6027. programs and other programs (including this one) and (ii) the mutual use of the 
  6028. information which has been exchanged, should contact: 
  6029.  
  6030. IBM Corporation
  6031. Department LZKS
  6032. 11400 Burnet Road
  6033. Austin, TX 78758
  6034. U.S.A.
  6035.  
  6036. Such information may be available, subject to appropriate terms and conditions, 
  6037. including in some cases, payment of a fee. 
  6038.  
  6039. The licensed program described in this document and all licensed material 
  6040. available for it are provided by IBM under terms of the IBM Customer Agreement, 
  6041. IBM International Program License Agreement or any equivalent agreement between 
  6042. us. 
  6043.  
  6044. Any performance data contained herein was determined in a controlled 
  6045. environment.  Therefore, the results obtained in other operating environments 
  6046. may vary significantly.  Some measurements may have been made on 
  6047. development-level systems and there is no guarantee that these measurements 
  6048. will be the same on generally available systems.  Furthermore, some measurement 
  6049. may have been estimated through extrapolation.  Actual results may vary.  Users 
  6050. of this document should verify the applicable data for their specific 
  6051. environment. 
  6052.  
  6053. Information concerning non-IBM products was obtained from the suppliers of 
  6054. those products, their published announcements or other publicly available 
  6055. sources.  IBM has not tested those products and cannot confirm the accuracy of 
  6056. performance, compatibility or any other claims related to non-IBM products. 
  6057. Questions on the capabilities of non-IBM products should be addressed to the 
  6058. suppliers of those products. 
  6059.  
  6060. All statements regarding IBM's future direction or intent are subject to change 
  6061. or withdrawal without notice, and represent goals and objectives only. 
  6062.  
  6063. All IBM prices shown are IBM's suggested retail prices, are current and are 
  6064. subject to change without notice.  Dealer prices may vary. 
  6065.  
  6066. COPYRIGHT LICENSE: 
  6067.  
  6068. This information contains sample application programs in source language, which 
  6069. illustrates programming techniques on various operating platforms.  You may 
  6070. copy, modify, and distribute these sample programs in any form without payment 
  6071. to IBM, for the purposes of developing, using, marketing or distributing 
  6072. application programs conforming to the application programming interface for 
  6073. the operating platform for which the sample programs are written. 
  6074.  
  6075. These examples have not been thoroughly tested under all conditions.  IBM, 
  6076. therefore, cannot guarantee or imply reliability, serviceability, or function 
  6077. of these programs.  You may copy, modify, and distribute these sample programs 
  6078. in any form without payment to IBM for the purposes of developing, using, 
  6079. marketing, or distributing application programs conforming to IBM's application 
  6080. programming interfaces. 
  6081.  
  6082.  
  6083. ΓòÉΓòÉΓòÉ 10.1. Trademarks ΓòÉΓòÉΓòÉ
  6084.  
  6085. The following terms are trademarks of the IBM Corporation in the United States 
  6086. or other countries or both: 
  6087.  
  6088.  AVC                      Presentation Manager 
  6089.  C/2                      SOMobjects 
  6090.  Common User Access       Ultimotion 
  6091.  C Set ++                 VisualAge 
  6092.  CUA                      WIN-OS2 
  6093.  IBM                      VoiceType 
  6094.  Workplace Shell          OS/2 
  6095.  
  6096.  Microsoft, Windows, and the Windows 95 logo are trademarks or registered 
  6097.  trademarks of Microsoft Corporation. 
  6098.  
  6099.  UNIX is a registered trademark in the United States and other countries 
  6100.  licensed exclusively through X/Open Company Limited. 
  6101.  
  6102.  Other company, product, and service names, which may be denoted by a double 
  6103.  asterisk (**), may be trademarks or service marks of others. 
  6104.  
  6105.  
  6106. ΓòÉΓòÉΓòÉ 11. Toolkit Licensing Information ΓòÉΓòÉΓòÉ
  6107.  
  6108. The IBM OS/2 Developer's Toolkit includes header files, include files, and 
  6109. audio files.  These files have extensions of .H, .HH, .XH, .INC, and .WAV. The 
  6110. Toolkit also contain programming tutorials illustrating OS/2 and multimedia 
  6111. programming techniques.  Both executable and source files for these tutorials 
  6112. are included.  You may copy and distribute the above header files, include 
  6113. files, audio files, and programming turorials in any form without payment to 
  6114. IBM, for the sole purposes of developing, using, marketing, and distributing 
  6115. application programs written to the OS/2 and MMPM/2 application programming 
  6116. interface.  Each copy or any portion of these programming tutorials or any 
  6117. derivative work thereof, which are distributed to others, must include a 
  6118. copyright notice as follows: "(C) Copyright (your company name) (year). All 
  6119. Rights Reserved."  The IBM Developer's Toolkit for OS/2 Warp includes a dynamic 
  6120. link library, SMAPI.DLL, for the Voice Type application programming interfaces. 
  6121. You may copy and distribute this library in object code form only, as part of 
  6122. your OS/2 software application program, without payment to IBM, provided that 
  6123. (1) you agree to indemnify, hold harmless and defend IBM against any claims, 
  6124. lawsuits and liabilities arising out of the use and distribution of your 
  6125. applications and (2) you distribute your applications pursuant to a license 
  6126. that prohibits the user from copying (except for backup purposes) or 
  6127. distributing this library.